Expo Android

🚀 expo-android

expo-android 是一個用於通過 ADB 實現 Android 模擬器自動化的 MCP 服務器，可幫助開發者更高效地進行 Android 設備的自動化操作。

🚀 快速開始

1. 啟動一個模擬器或連接一臺設備。
2. 運行 doctor 命令來驗證 ADB 和設備選擇。
3. 使用 inspect、tapElement、inputText 等工具進行操作。

示例代碼如下：

await client.callTool({ name: 'expo-android.doctor', arguments: {} });
await client.callTool({
  name: 'expo-android.inspect',
  arguments: { onlyInteractive: true, maxElements: 200 },
});

✨ 主要特性

• 支持通過 ADB 對 Android 模擬器或設備進行自動化操作。
• 提供多種工具，如設備列表查看、元素檢查、點擊、輸入文本等。
• 支持靈活的搜索條件，方便查找元素。
• 可與 Claude Code CLI 和 OpenAI Codex CLI 集成使用。

📦 安裝指南

npm install -g @fndchagas/expo-android
# 或者
npx -y @fndchagas/expo-android

💻 使用示例

基礎用法

// 驗證 ADB 和設備選擇
await client.callTool({ name: 'expo-android.doctor', arguments: {} });
// 檢查 UI 元素
await client.callTool({
  name: 'expo-android.inspect',
  arguments: { onlyInteractive: true, maxElements: 200 },
});

高級用法

與 Claude Code CLI 集成

claude mcp add expo-android \
  --env ADB_PATH="$HOME/Library/Android/sdk/platform-tools/adb" \
  --env ADB_SERIAL="auto" \
  -- npx -y @fndchagas/expo-android

與 OpenAI Codex CLI 集成

codex mcp add expo-android \
  --env ADB_PATH="$HOME/Library/Android/sdk/platform-tools/adb" \
  --env ADB_SERIAL="auto" \
  -- npx -y @fndchagas/expo-android

或者編輯 ~/.codex/config.toml 文件：

[mcp_servers.expo-android]
command = "npx"
args = ["-y", "@fndchagas/expo-android"]
env = { ADB_PATH = "/Users/you/Library/Android/sdk/platform-tools/adb", ADB_SERIAL = "emulator-5554" }

其他使用示例

檢查 UI 元素

const result = await client.callTool({
  name: 'expo-android.inspect',
  arguments: { onlyInteractive: true, includeScreenshot: false, maxElements: 200 },
});

驗證 ADB 和設備

await client.callTool({
  name: 'expo-android.doctor',
  arguments: {},
});

按調用覆蓋設備序列號

await client.callTool({
  name: 'expo-android.tapElement',
  arguments: { text: 'Search', serial: 'emulator-5554' },
});

點擊元素

await client.callTool({
  name: 'expo-android.tapElement',
  arguments: { text: 'Private account' },
});

等待並斷言元素

await client.callTool({
  name: 'expo-android.waitForElement',
  arguments: { text: 'Save', timeout: 10000, shouldBeClickable: true },
});

await client.callTool({
  name: 'expo-android.assertElement',
  arguments: { text: 'Private account', shouldBeChecked: true },
});

📚 詳細文檔

環境變量

工具列表

工具通過 MCP 服務器名稱公開，例如：expo-android.tap。

• devices：列出已連接的設備和模擬器。
• doctor：驗證 ADB 可用性並顯示已連接的設備。
• setDevice：覆蓋此 MCP 進程的活動設備序列號。
• inspect：將 UI 轉儲解析為元素並提供摘要（可選截圖）。
• screenshot：僅捕獲截圖（Base64 或文件路徑）。
• findElement：返回符合搜索條件的元素。
• tapElement：查找元素並點擊其中心。
• waitForElement：等待元素出現（可選狀態檢查）。
• assertElement：驗證元素的存在和狀態。
• tap：在指定的 x/y 座標處點擊。
• swipe：在座標之間滑動。
• longPress：在座標處長按。
• inputText：在焦點字段中輸入文本。
• keyEvent：發送 Android 按鍵事件（例如，返回、主頁）。
• openApp：通過包名啟動應用程序。
• listPackages：列出已安裝的包名。

搜索條件

findElement、tapElement、waitForElement、assertElement 這些工具接受靈活的搜索輸入。 常見字段：

• text、textContains
• contentDesc、contentDescContains
• resourceId、resourceIdContains
• class
• normalizeWhitespace、caseInsensitive

🔧 技術細節

要求

• Node 18+
• 可用的 Android SDK platform-tools（adb）
• 已連接的 Android 模擬器或設備

驗證 ADB：

adb devices

故障排除

ADB 未找到（spawn adb ENOENT）

如果出現 ADB executable not found 或 spawn adb ENOENT 之類的錯誤，請設置 ADB_PATH 或導出 SDK 路徑：

export ADB_PATH="$HOME/Library/Android/sdk/platform-tools/adb"
# 或者
export ANDROID_HOME="$HOME/Library/Android/sdk"

如果連接了多個設備，請將 ADB_SERIAL 設置為目標設備。您也可以在運行時調用 setDevice：

await client.callTool({
  name: 'expo-android.setDevice',
  arguments: { serial: 'emulator-5554' },
});

如果更新了 PATH 或 SDK 變量，請重啟 MCP 進程以使其獲取新的環境。

測試

npm run build
npm test

📄 許可證