AndroidMCP Framework

AndroidMCP Framework

コーディングエージェントに Android 開発機能を提供する Model Context Protocol（MCP）サーバーおよび CLI です。エミュレーターや実機でのビルド、インストール、起動、セマンティック UI オートメーション、logcat／クラッシュ診断、プロジェクト検出、変更を考慮したテストインテリジェンスを利用できます。

テストインテリジェンスは、device、ui-automation、session-management、doctor、workflow-discovery とともに、デフォルトで有効です。analyze_test_project、audit_screen、save_test_case、write_test_report などのツールは、別のワークフローを有効にしなくても利用できます。ワークフローのドキュメントを参照してください。

インストール

npm install -g androidmcp-framework@latest
androidmcp-framework doctor
# Update to the latest global release and clear npm cache
amf update
# Short alias (also installed by npm)
amf doctor

または、グローバルにインストールせず、必要なときに npx -y androidmcp-framework@latest mcp を実行できます。amf update コマンドはグローバル npm インストールを更新します。npx を使う場合は、最新バージョンを取得するために @latest を付けて再実行してください。アップデートをインストールすると、設定された npm キャッシュディレクトリ（通常、macOS/Linux では ~/.npm/_npx）内の npm の _npx 実行キャッシュのみが消去されます。共有のパッケージダウンロードキャッシュは消去されません。

MCP クライアントを接続する

{
  "mcpServers": {
    "androidmcp-framework": {
      "command": "npx",
      "args": ["-y", "androidmcp-framework@latest", "mcp"]
    }
  }
}

Claude Code、Codex、Gemini CLI、Antigravity、VS Code/GitHub Copilot の手順については、コーディングエージェントのセットアップを参照してください。Android Studio でドキュメント化されている MCP クライアントには HTTP が必要ですが、このサーバーが現在公開しているのは stdio のみです。対応クライアントを参照してください。

アプリプロジェクトを初期化する

Android または Flutter のリポジトリルートから実行します。

androidmcp-framework setup

これにより .androidmcp-framework/config.yaml が作成されます。.android-build-mcp/ または .androidbuildmcp/ に既存データが残っている場合は内容を確認し、androidmcp-framework setup --migrate を実行して、既存の内容を上書きせずにファイルをコピーしてください。古いディレクトリは自動的には削除されません。

プロジェクト固有のフレームワークデータはすべて .androidmcp-framework/ 内に保存されます。スクリーンショットは .androidmcp-framework/artifacts/screenshots/ に、生のアクセシビリティ階層スナップショットは .androidmcp-framework/artifacts/snapshots/ に、その他の証跡は .androidmcp-framework/artifacts/ に保存されます。screenshot は画像とともに保存先の絶対パスを返します。snapshot_ui はツリー全体を保存し、デフォルトでは簡潔な概要を返します。テストケースの定義とタイムスタンプ付きレポートは、それぞれ testcases/ と test-reports/ に保存されます。ワークスペースルートは、最も近い .androidmcp-framework/config.yaml または .git マーカーを見つけるまで上位ディレクトリをたどって検出されます。見つからない場合は、現在のディレクトリが使用されます。生成されたアーティファクトはローカル出力であり、デフォルトで Git の対象外です。

ローカルチェックアウトの設定

npm ci && npm run build でビルドした後、ビルド済みのエントリーポイント build/cli/index.js mcp を起動するよう MCP クライアントを設定してください。自分のチェックアウトの絶対パスを使用し、例にあるマシン固有のパスをコピーしないでください。

構成

• UI オートメーション： JavaScript/TypeScript と Android SDK platform-tools（adb）のみを使用します。オプションの Python uiautomator2 ブリッジは削除されており、Python ランタイムも scripts/ ディレクトリも必要ありません。
• デバイスの指定： エミュレーターと実機は ADB 経由で統一的に扱われます。明示的に指定した対象、セッションのデフォルト、接続されている対象が 1 つだけの場合の対象の順に試します。
• MCP トランスポート： ローカルのコーディングエージェント向けに stdio を使用します。ストリーマブル HTTP はまだ実装されていません。
• ツール： src/tools/<workflow>/ に、ツールごとに 1 つの TypeScript モジュールがあります。

開発

npm ci
npm run build
npm run typecheck
npm test

TypeScript は src/ から生成された build/ にコンパイルされます。生成された build/ や古い dist/ の出力はコミットしないでください。

テストフレームワーク

testing-intelligence ワークフローはデフォルトで有効です。Native Android と Flutter のワークスペースを分析し、ネストされた Flutter パッケージを検出して、カスタム指示とテストケースを保存し、画面を監査して、タイムスタンプ付きの Markdown/JSON レポートを .androidmcp-framework/test-reports/YYYY-MM-DD/HHmmss/ に書き込みます。test_device は Flutter のユニットテスト／ウィジェットテストを flutter test（kind: "unit"）経由で実行し、integration_test/ が存在する場合は flutter test -d <device-id> integration_test でデバイス統合テストを実行できます。詳しくは、Testing Framework をご覧ください。

ライセンス

MIT