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

📄 许可证