DroidAgentKit

DroidAgentKit

AI コーディングエージェントに、Gradle、adb、logcat、lint、クラッシュのトリアージなど、実際の Android ツールを使わせましょう。生のシェルアクセスではなく、ローカルで権限管理された MCP サーバーを通じて利用できます。

DroidAgentKit は、AI エージェントを使って Android プロジェクトに取り組むのを支援します。マシン上で動作し、Gradle ツリーと連携します。また、許可した場合はエミュレーターやデバイスとも連携し、生のシェル出力ではなく、構造化された回答をエージェントに提供します。

Android を最優先し、意図的にその方針を貫いています。 クロスプラットフォームの自動化サーバーは iOS にも対応していますが、画面のタップまでしか行えません。DroidAgentKit はその逆を行い、Gradle タスクの許可リスト、lint、R8 クラッシュのトリアージ、Perfetto トレース、アプリストレージ、Compose のビジュアルリグレッションなど、Android のビルドシステムとツールチェーンの深部まで対応します。iOS には対応しておらず、今後も対応予定はありません。

すべてローカルに保たれます。コマンドは許可リストを通じて実行されます。出力はエージェントに返される前に編集されます。アーティファクトはデフォルトで build/droidagentkit に保存されます。

利用できる機能

単独でも組み合わせても使える、3 つの機能を提供します。

MCP サーバー — エージェントから呼び出せるModel Context Protocolサーバーです。プロジェクトの調査、安全な Gradle タスクの実行、ログとスクリーンショットの取得、クラッシュのトリアージ、lint の実行、ビルドのプロファイリングなどができます。オプションのグループを追加すると、デバイス診断、範囲を限定したデバイス操作、Perfetto トレース、ビジュアルリグレッション、読み取り専用のアプリストレージ調査、実験的なエミュレーターネットワークキャプチャも利用できます。

準備状況の監査ツール — リポジトリがどれだけエージェントに適しているかを評価し、リスクを列挙します。また、AGENTS.md、プロジェクトのスキルファイル、スターター用の .droidagentkit/config.yaml を生成できます。共有しても安全なレポートが必要な場合は、--redact-public を使ってください。

ビジュアルリグレッションキット — Compose/UI キャプチャ用のピクセル差分レポート、Gradle プラグイン、JUnit ルールを提供します。MCP ツールを使ってゴールデン画像を比較し、レポートを生成し、明示的に確認したうえでゴールデン画像を更新できます。

MCP ツールの概要

core グループはデフォルトで有効です（18 個のツール）：プロジェクトの調査、許可リストに登録された Gradle の実行、デバイス一覧、インストール／起動、logcat、スクリーンショット、アクセシビリティスナップショット、レポートバンドル、lint、クラッシュのトリアージ、依存関係のチェック、ビルドパフォーマンス、テスト実行、ビルド診断、APK サイズ分析、UI 要素の検索、そして android_doctor（明らかな理由もなく何かが失敗したときに実行できる環境の事前チェック）です。

サーバーの起動時にツールグループを公開すると、さらに多くのツールを有効にできます（セキュリティモデルを参照）：

グループ	追加される機能
device_read	権限監査、dumpsys の要約、メモリ／バッテリー、bugreport、ストリーミング logcat ジョブ
device_control	エミュレーター制御、アプリのアンインストール／データ消去、インテント、権限、タップ／スワイプ／入力、ラベルによるタップ、ファイルのプッシュ／プル、小規模な操作フロー、フローの記録
perfetto	トレースの取得と Trace Processor による分析（ジャンク、CPU、競合、binder のレイテンシなど）
visuals	ピクセル差分、ビジュアルレポート、ゴールデンの更新
storage	デバッグ可能なアプリの SQLite、SharedPreferences、ファイルツリーの読み取り専用アクセス
network_experimental	エミュレーターのみを対象とした mitmproxy によるキャプチャと、編集済み HAR のクエリ（独自のデバッグ CA が必要）

危険な操作（アンインストール、データ消去、プロキシ経由のインストール、ゴールデンの上書きなど）には、設定で適切な機能を有効にし、呼び出し時に confirmDestructive=true を指定する必要があります。実際の境界となるのは機能です。confirmDestructive は誤操作を防ぐためのものであり、エージェントが指定するため、悪意ある操作を防ぐものではありません。脅威モデルを参照してください。

レポートバンドルには機能の概要が含まれます。公開されているグループ、有効になっている機能、まだインストールが必要なもの（adb、trace processor、mitmproxy など）が確認できます。この概要は情報提供のみを目的としており、準備状況のスコアは変わりません。

ツールの全一覧と機能 ID については、docs/security-and-permissions.mdを参照してください。

クイックスタート

前提条件： Node 18+（ランチャーのインストール時のみ使用）。JDK 17+ がある場合はそれを使用します。PATH 上にあるか、JAVA_HOME で指定されているか、DROIDAGENT_JAVA で指定されている必要があります。ない場合は、固定バージョンの Eclipse Temurin JRE を一度ダウンロードし、SHA-256 を検証して ~/.droidagentkit/jre にキャッシュします。任意：デバイスツールを使う場合は Android adb／platform-tools を用意してください。ANDROID_HOME を設定するか、ユーザーポリシー（~/.droidagentkit/policy.yaml）で adbPath を設定します。これらすべての確認には doctor を実行してください。

@droidagentkit/launcher npm パッケージは、初回実行時にGitHub Releasesから対応する droidagent-cli jar をダウンロードしてキャッシュし、実行前に SHA-256 を検証します。

npx -y @droidagentkit/launcher --version

引数なしで実行すると MCP サーバーが起動します。また、任意の CLI コマンドをそのまま渡すこともできます：

npx -y @droidagentkit/launcher doctor
npx -y @droidagentkit/launcher init --profile device-control
npx -y @droidagentkit/launcher audit --project /path/to/android --write-agents

たとえば Claude Code の場合、エージェントの MCP 設定で直接指定します：

claude mcp add droidagentkit -- npx -y @droidagentkit/launcher

または、ワンクリックでインストールできます：

その他のインストール方法

brew install iVamsi/android-agent-kit/droidagent

各リリースには .mcpb バンドルも添付されています。ワンクリックインストールに対応した MCP ホストにドロップすると、サーバーが登録されます。バンドルに含まれるのはランチャーのみです。JVM サーバーと、JDK がない場合に使用する検証済みの Temurin JRE は初回実行時に取得されるため、ダウンロードサイズは約 160 MB ではなく約 10 KB です。

ソースからビルドする

貢献する場合、またはまだリリースされていないバージョンを実行する場合：

./gradlew :cli:installDist
./cli/build/install/droidagent/bin/droidagent install-mcp

エージェント（Codex、Claude Code、Cursor、Zed、VS Code、Android Studio、…）に一度だけ登録してください。 install-mcp --dry-run を使うと、ファイルを書き込まずにプレビューできます。1 つのフォルダー内にある多数のプロジェクトで Android Studio を使う場合：

droidagent install-mcp --targets android-studio --projects-root ~/Developer/StudioProjects

詳細とホストごとの設定パスについては、docs/easy-mcp-installation.md をご覧ください。 セキュリティモデルとすべてのツール一覧については、docs/security-and-permissions.md をご覧ください。 CLI リファレンスとトラブルシューティングについては、docs/cli-reference.md、docs/troubleshooting.md をご覧ください。

チャットで試す

install-mcp の実行後、Android プロジェクトを開いて、次のように依頼してください。

• 「DroidAgentKit でこの Android プロジェクトを調査してください。」
• 「アプリモジュールの安全なユニットテストを実行してください。」
• 「エージェント対応状況をこのリポジトリで監査し、AGENTS.md を作成してください。」
• 「logcat を取得してクラッシュをトリアージしてください。」（R8 のマッピングがある場合、リリースビルドは自動的に難読化解除されます）
• 「前回のビルドから APK のサイズが増えたのはなぜですか？」
• 「アプリの SQLite スキーマには何がありますか？」（storage と app_data_read が有効な場合）
• 「Perfetto トレースを取得して、フレームのカクつきを要約してください。」（perfetto が有効な場合）
• 「今行った操作を、再生できるフローとして記録してください。」（device_control が有効な場合）

目標を伝えると、エージェントは起動時に渡された一覧からツールを選びます。

仕組み

1. エージェントが droidagent serve-mcp --transport stdio --project auto を起動します（または、macOS 上で Android Studio が使用する localhost HTTP エンドポイントに接続します）。
2. MCP ハンドシェイク（initialize、続いて tools/list）。
3. エージェントが tools/call 経由で android_* ツールを呼び出します。手動で呼び出す必要はありません。
4. --project auto は、CLAUDE_PROJECT_DIR、CODEX_WORKSPACE / CODEX_PROJECT_DIR、GEMINI_PROJECT_DIR / GEMINI_WORKSPACE、CURSOR_PROJECT_DIR / CURSOR_WORKSPACE、PWD、その後 cwd の順にアクティブなプロジェクトを解決します。ユーザー全体で一度インストールすれば、複数のプロジェクトで使えます。

オプションのリソースとワークフロープロンプトは、Android Studio 以外のホストで利用できます。ツールの一覧には、該当する場合、readOnlyHint や destructiveHint などのヒントが含まれます。

エージェントなしで CLI を使う

droidagent inspect --project /path/to/android --format markdown
droidagent audit --project /path/to/android --write-agents
droidagent audit --project /path/to/android --redact-public
droidagent devices --format json
droidagent serve-mcp --transport stdio --project auto

フラグを確認するには、droidagent --help または droidagent <command> --help を実行してください。

設定ファイルの生成

droidagent init                          # interactive: six yes/no prompts explaining risk per area
droidagent init --profile device-control # non-interactive, for scripted setup
droidagent init --profile full           # everything, including storage and network capture
droidagent init --list-profiles          # see all profile names without writing anything

デフォルトで有効になるのは、安全な読み取り専用の core ツールグループのみです。.droidagentkit/config.yaml を手動で作成せずに他のグループを有効にする最も簡単な方法は droidagent init です。各グループと機能によってエージェントに実際に許可される内容については、docs/security-and-permissions.md をご覧ください。

設定

Android プロジェクトのルートに .droidagentkit/config.yaml を配置すると、Gradle の許可リスト、adb の権限、機能フラグ、秘匿化パターン、レポートの出力先を調整できます。audit --write-agents の実行時、監査ツールが安全なデフォルト設定を用意できます。

ステータス

アルファ版です。MCP ツール名とスキーマは安定したものとして扱われますが、実際の使用から知見を得るにつれて、動作を厳格化していきます。テレメトリーはありません。主要なワークフローにクラウドへの依存はありません。

その他のドキュメント

• セキュリティと権限 — 機能、ツールグループ、破壊的な操作、プロンプトインジェクションの実例
• 互換性 — 安定している機能、変更される可能性のある機能、1.0 の終了基準
• 簡単な MCP インストール — ホストごとのセットアップ
• CLAUDE.md — コントリビューター向けのビルドコマンドとアーキテクチャに関するメモ