Expo Android

🚀 expo - android

このパッケージは、ADBを介したAndroidエミュレーターの自動化用のMCPサーバーです。

🚀 クイックスタート

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 },
});

✨ 主な機能

• devices — 接続されているデバイスとエミュレーターのリストを表示します。
• doctor — adbの可用性を検証し、接続されているデバイスを表示します。
• setDevice — このMCPプロセスのアクティブなデバイスシリアルを上書きします。
• inspect — UIダンプを要素に解析し、要約を表示します（スクリーンショットはオプション）。
• screenshot — スクリーンショットのみをキャプチャします（base64またはファイルパス）。
• findElement — 検索条件に一致する要素を返します。
• tapElement — 要素を見つけてその中心をタップします。
• waitForElement — 要素が表示されるまで待機します（必要に応じて状態チェックを行います）。
• assertElement — 要素の存在と状態を検証します。
• tap — x/y座標でタップします。
• swipe — 座標間でスワイプします。
• longPress — 座標で長押しします。
• inputText — フォーカスされたフィールドにテキストを入力します。
• keyEvent — Androidのキーイベントを送信します（例：BACK、HOME）。
• openApp — パッケージ名でアプリを起動します。
• listPackages — インストールされているパッケージ名のリストを表示します。

📦 インストール

npm install -g @fndchagas/expo-android
# または
npx -y @fndchagas/expo-android

💻 使用例

基本的な使用法

await client.callTool({ name: 'expo-android.doctor', arguments: {} });
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" }

📚 ドキュメント

必要条件

• 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

検索条件

findElement、tapElement、waitForElement、assertElement の各ツールは柔軟な検索入力を受け付けます。

共通のフィールド:

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

MCPの使用例

インスペクト

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

インスペクトオプション:

• includeScreenshot (デフォルト: false)
• screenshotMode: base64 または path
• screenshotPath: path を使用する場合のオプションのファイルパス
• maxElements: 返される要素の制限
• includeElements: 要素を返すか要約のみを返すか

ドクター

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 },
});