droidsight

droidsight

ADB 経由で実際の Android デバイスを操作し、その操作で表示された画面をエージェントに返す MCP サーバーです。

ネイティブバイナリは 1 つです。サーバーは Python、Appium、scrcpy、ffmpeg に依存せず、Node も一切実行しません。以下の npx はインストーラーとして便利なだけです。そのため、実行環境に必要なのはバイナリと adb のみです。バックグラウンドの H.264 screenrecord ストリームをプロセス内でデコードするため、操作後の画面はツールの結果に自動で添付され、何が起きたかを確認するためにもう一度通信する必要がありません。

すべての画像には、その画像が生成された座標空間が含まれているため、モデルは倍率を推測することなく、見たばかりの対象をタップできます。アクセシビリティツリーが空で返ってきた場合でも（Flutter、React Native、キャンバス、ゲームなど）、OCR とテンプレートマッチングで対象を見つけられます。

これは強力なローカルコントローラーであり、サンドボックスではありません。信頼できるデバイスと MCP クライアントに対してのみ実行してください。

インストール

npx -y @edgecasehuman/droidsight

このコマンドはプラットフォーム用のビルド済みバイナリをダウンロードするため、ビルドツールは必要ありません。このサーバーは、公式の MCP Registry に io.github.edgecasehuman/droidsight としても掲載されています。

代わりに crates.io からコンパイルする場合：

cargo install droidsight

または、ソースからコンパイルする場合：

cargo build --locked --release --bin droidsight

どちらのコンパイル方法でも、PATH 上に NASM が必要です。 H.264 デコーダーは openh264-sys2 によって C++ からビルドされます。openh264-sys2 はホットパスのアセンブルに NASM を使用しますが、どのプラットフォームにも標準では付属していません。NASM がない場合、このクレートではなく推移的依存関係のビルド中に失敗します。apt install nasm、brew install nasm、または winget install NASM.NASM でインストールしてください。上記の npx を使う方法では、これらは必要ありません。

サーバーの実行ファイルは target/release/droidsight です。標準入力と標準出力を介して、改行区切りの JSON-RPC 2.0 を使用します。

クライアント設定

{
  "mcpServers": {
    "android": {
      "command": "npx",
      "args": ["-y", "@edgecasehuman/droidsight"],
      "env": {
        "DROIDSIGHT_DEVICE_SERIAL": "<serial from `adb devices`>"
      }
    }
  }
}

ADB は PATH、ANDROID_SDK_ROOT、ANDROID_HOME、または明示的に指定した DROIDSIGHT_ADB_PATH から利用できる必要があります。複数の認証済みデバイスが表示されている場合、サーバーはどれを使うか推測しません。DROIDSIGHT_DEVICE_SERIAL を設定してください。

ツール

デフォルトでは 31 個のツールが公開されます。DROIDSIGHT_ALLOW_SHELL=1 を設定すると、さらに 2 個のツールが表示され、最後に一覧表示されます。

画面の確認

ツール	説明
mcp_android_vision_query	スクリーンショット、階層、OCR、要素またはテンプレートの検索を行います。elements アクションと tap_element アクションを使えば、座標の計算は不要です。
mcp_android_vision_stream	バックグラウンドの H.264 ストリームを開始、停止、または読み取ります。
mcp_android_get_view_hierarchy	アクセシビリティツリーを構造化 JSON として取得します。
mcp_android_smart_wait	要素が表示されるまで待機するか、タイムアウトします。

デバイスの操作

ツール	説明
mcp_android_input_act	タップ、文字入力、キーイベント、スワイプ、スマートタップ、IME 制御を行います。
mcp_android_tap_text	テキストを検索し、表示された瞬間にタップします。タイムアウトするまで再試行するため、スクリーンショットを撮ってからタップするまでの間に対象を見逃すことがありません。
mcp_android_run_flow	安全なアクションのみを完全に事前検証したうえで、範囲を制限した一連の操作を実行します。
mcp_android_record_gesture	固定時間にわたって生のタッチ入力を記録します。
mcp_android_play_gesture	記録したジェスチャーのタイムラインを再生します。

アプリケーション

ツール	目的
mcp_android_app_manage	起動、停止、一覧表示、インストール、クラッシュログの読み取りを行います。アンインストール、データの消去、権限の変更、有効化、無効化には、さらに confirm_destructive が必要です。
mcp_android_app_instrumentation	詳細な状態を調査します：アクティビティ、ウィンドウ、プロセス一覧、スタックトレース。
mcp_android_open_url	URL を開きます。
mcp_android_start_intent	任意のインテントを開始します。

デバイスとシステムの状態

ツール	目的
mcp_android_device_control	クリップボード、バッテリー、デバイス情報、ロック状態、ロック解除、画面の回転を扱います。
mcp_android_system_control	アクセシビリティサービスと、他のアプリの上に重ねて表示する権限を扱います。すべてのアプリに対する画面読み取りと入力の注入を許可します。
mcp_android_network_control	Wi-Fi、モバイルデータ、HTTP プロキシ、電話の発信、SMS、ワイヤレス ADB ペアリングを扱います。
mcp_android_sensor_control	バッテリー残量と充電状態を偽装します。GPS の偽装はエミュレーター専用です。
mcp_android_check_health	選択したデバイスの接続状態と応答性を確認します。
mcp_android_check_debug_exposure	有効になっていて、そのためアプリから確認できる開発者向け設定を報告します。

診断とデータ

ツール	目的
mcp_android_diagnostic_stream	logcat の読み取り、消去、またはバッファーされた生イベントとセマンティックイベントの読み取りを行います。
mcp_android_read_recent_events	オプションのモニターからバッファーされたデバイスイベントを取得します。
mcp_android_log_filter	正規表現、タグ、優先度でログをフィルタリングします。
mcp_android_get_notifications	投稿された通知をダンプします。編集されていないメッセージ内容も含まれます。
mcp_android_file_system	DROIDSIGHT_LOCAL_ROOT 内に限定して、ファイルの一覧表示、読み取り、プッシュ、プルを行います。
mcp_android_forensics_control	デバイス上の SQLite データベースの照会、ファイルのハッシュ計算、アプリのデータの不可逆な削除を行います。

キャプチャとプレゼンス

ツール	目的
mcp_android_start_recording	最大 180 秒間の画面録画を開始し、デバイスに保存します。
mcp_android_stop_recording	録画を停止します。ファイルはデバイスに残ります。
mcp_android_companion	通知の投稿、一時的なメッセージの表示、またはスマートフォンを持っている人が開ける URL の表示を行います。
mcp_android_sentinel_control	監視対象のパッケージを登録します。使用する前にバックグラウンドでの強制適用をご覧ください。
mcp_android_start_session、mcp_android_stop_session	セッションマーカーです。呼び出しを受け付けますが、サーバーの状態は保持しません。

DROIDSIGHT_ALLOW_SHELL=1 の場合のみ

ツール	目的
mcp_android_run_shell	任意のデバイスシェルコマンドを実行します。いかなるフィルタリングも行いません。
mcp_android_run_macro	最大 100 個のシェルコマンドを順に実行し、最初の失敗時に停止します。

座標空間

スクリーンショットはデフォルトで幅 720 ピクセルに縮小されるため、返されたピクセルから読み取った座標は通常、デバイス上の座標ではありません。画像を返すすべてのツールは、変換方法を示す metadata.image オブジェクトも返します：

{
  "image": {
    "width": 720, "height": 1600,
    "device_width": 1080, "device_height": 2400,
    "origin_x": 0, "origin_y": 0,
    "scale": 1.5,
    "coordinate_space": "image",
    "note": "To convert a coordinate (x, y) read from this image into a device coordinate: device_x = 0 + x * 1.5, device_y = 0 + y * 1.5."
  }
}

coordinate_space が device の場合、画像はすでに 1:1 であり、座標をそのまま使用できます。縮小を軽減または解除するには、max_width: 1440 を指定してください。切り抜き画像では、スケーリング後に加算する必要があるゼロ以外の origin_x／origin_y も報告されます。

タップ、uiautomator の階層境界、OCR ボックス、テンプレートマッチングはすべてデバイス上の座標です。バックグラウンドストリームは --size を指定せずに screenrecord を実行するため、デコードされたフレームはネイティブ解像度で、この座標空間を共有します。

計算を完全に避けることもできます。mcp_android_vision_query ツールの elements アクションは、各要素の事前計算済み中心座標を含むインデックス付きスナップショットを返します。また、その tap_element アクションには、その snapshot_id と index を指定します。

環境変数

変数	効果
DROIDSIGHT_DEVICE_SERIAL	プロセスが使用できる唯一の Android ターゲットです。ADB が複数の承認済みデバイスを報告する場合は必須です。
DROIDSIGHT_ADB_PATH	ADB 実行ファイルの明示的なパスです。
DROIDSIGHT_LOCAL_ROOT	APK のインストールやファイルのプッシュ／プルで使用するホストパスを、このパス以下に制限します。デフォルトはプロセスの作業ディレクトリです。
DROIDSIGHT_DEVICE_PIN	自動ロック解除が必要な UI 操作に使用する数字の PIN です。実行時にのみ指定し、ソースコードやチェックイン済みの MCP 設定には記載しないでください。
DROIDSIGHT_ALLOW_SHELL=1	任意のシェルツールとマクロツールを公開します。広範な ADB シェルアクセスと同等の権限が付与されます。デフォルトでは無効です。
DROIDSIGHT_DEBUG_LOG	永続的なデバッグログのパスです。ファイルへのログ記録は明示的にオプトインした場合にのみ行われます。これを指定しない場合、警告は stderr に出力され、ファイルには書き込まれません。
DROIDSIGHT_LOG	トレースのフィルターです。デフォルトは warn ですが、デバッグログのパスを設定すると debug になります。
DROIDSIGHT_EVENTS=1	長時間実行されるデバイスイベントモニターを起動します。DROIDSIGHT_DEVICE_SERIAL が必要です。
DROIDSIGHT_SENTINEL=1	バックグラウンドでの強制適用で説明されているバックグラウンドの強制適用ループを起動します。デフォルトでは無効です。有効にすると、画面のロック解除を含め、タイマーに従ってデバイスの状態を再適用します。

継続的なビジョンキャッシュ

プロセスの起動時に、バックグラウンドで H.264 の screenrecord ストリームが 1 つ開始され、最新のデコード済み RGB フレームがメモリに保持されます。スクリーンショットツールと入力の観測機能はこのキャッシュを読み取るため、最初のフレームがデコードされるとすぐにスナップショットを利用できます。ストリームの実行中は静止画面の最後のフレームが有効なまま保持され、エンコーダーが変化のないピクセルの出力を停止しただけで期限切れになることはありません。

ストリームは、最初のデコード可能なフレームが届くまで最大 20 秒待機してから再接続します。それ以降は、無音状態を静止画面として扱いますが、EOF や読み取りエラーが発生した場合は引き続き再接続します。ストリームの開始時または停止時には、そのフレームキャッシュが同期的に消去されるため、以前のセッションの画像が再利用されることはありません。mcp_android_vision_stream の stop アクションは、明示的に start されるまでキャプチャを一時停止します。シャットダウン時には、所有している ADB ストリームを破棄し、screenrecord プロセスが残らないようにします。

継続的なキャプチャには、プライバシー、バッテリー、CPU、無線帯域幅へのコストが伴います。キャッシュされたフレームはツールから返されるまでプロセスのメモリ内に保持されますが、デバイスの画面には機密情報が表示されることがあります。キャプチャを一時停止する場合は、明示的な停止アクションを使用してください。

MCP トランスポート

標準出力には1行につき1つのJSON-RPC値が出力され、診断情報は標準エラー出力に送られます。サーバーは initialize、tools/list、tools/call に加えて、initialized 通知と従来の mcp.* エイリアスをサポートしています。バッチ配列は要素ごとに処理され、応答配列が1行出力されます。通知のみのバッチでは何も出力されず、空のバッチは拒否されます。クライアントは、ツールの一覧取得や呼び出しを行う前に、順序どおりに initialize リクエストを送り、notifications/initialized 通知を送るハンドシェイクを完了する必要があります。それより前に呼び出すと、JSON-RPC エラー -32002 が返されます。入力フレームは16 MiBまでに制限されています。サイズ超過または無効なUTF-8のフレームは拒否されますが、次の有効なリクエストの処理は続行されます。

ログ、イベント、通知、デバイスファイル、階層データとOCR結果、クラッシュレポートとフォレンジックレポート、計装データ、シェル／マクロの出力、集約フローから公開されるテキストは256 KiBまでに制限されています。切り詰められた応答には、切り詰め方法、元のサイズ、返却サイズ、設定された上限を含む metadata.truncation が付与されます。時系列フィードでは新しい末尾が保持され、ファイル形式の出力では先頭が保持されます。

有限時間で終了するADBサブプロセスは、標準出力と標準エラー出力を同時に読み取り、各ストリームから最大4 MiBを保持しながら、観測されたすべてのバイト数をカウントします。これにより、パイプのデッドロックと無制限なキャプチャを防ぎます。オプションのイベントモニターはADB子プロセスと読み取りスレッドを所有し、トランスポートのシャットダウン時にキャンセル、強制終了、スレッドの終了待ち、プロセスの回収が行われます。デタッチされたまま残ることはありません。

OCRは、外部のTesseract実行ファイルとのオプションの統合です。検出プローブは5秒、認識処理は30秒までに制限されています。タイムアウトした子プロセスは、ツールがエラーを返す前に終了・回収されます。

スモークテスト：

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | cargo run --quiet --bin droidsight

破壊的な操作

一部のツールはデバイスの状態を不可逆的に変更します。pm clear はアプリケーションのデータベース、設定、アカウント、認証情報を削除するもので、2通りの方法で実行できます。どちらも "confirm_destructive": true がなければ実行されません。

• mcp_android_forensics_control に "action": "clear_app_data" を指定します。キャッシュの消去ではなく、実際の処理内容に基づく名称です。
• mcp_android_app_manage に "action": "clear_data" を指定します。同じツールでは、アプリケーション、そのデータ、またはセキュリティ制御を削除する uninstall、permission、enable、disable も、同じ引数がなければ実行できません。

ガードはADBコマンドを実行する前に確認されるため、拒否された呼び出しがデバイスに影響することはありません。これは意図しない呼び出しを防ぐためのガードレールであり、セキュリティ境界ではありません。ツールを呼び出せるクライアントは、このフラグも設定できます。

このゲートは、特定のツールに対する意図しない呼び出しを防ぎます。これは封じ込めの境界ではなく、同程度の影響を持つ操作のうち、ゲートで保護されていないものもいくつかあります。

• mcp_android_system_control はアクセシビリティサービスを有効にします。これにより、デバイス上のすべてのアプリに対する全画面の読み取りと入力の注入が可能になり、他のアプリの上に重ねて表示する権限も付与されます。
• mcp_android_network_control はグローバルHTTPプロキシを設定し、保存済みのWi-Fiネットワークを削除し、実際の発信電話を行います。
• mcp_android_sensor_control は、バッテリー残量や状態などのセンサー値を上書きします。GPS位置情報の偽装にはエミュレーターコンソールを使用し、エミュレーターにのみ適用され、実機には適用されません。

任意のシェルアクセス

DROIDSIGHT_ALLOW_SHELL=1 を設定すると、デバイスシェルにコマンド文字列をそのまま渡す2つのツールが公開されます。mcp_android_run_shell と、最大100件のコマンドをまとめて実行する mcp_android_run_macro です。

コマンドのフィルタリングは一切行われません。 制御はこの環境変数のみです。一度設定すると、これらのツールからは上記のゲート対象操作すべてを実行できます。シェル経由の処理では confirm_destructive が確認されないため、pm clear、pm uninstall、ファイル削除も、同フラグなしで実行できます。接続されているMCPクライアントが、デバイス上のローカルシェルと同等に信頼できる場合を除き、この変数は設定しないでください。

バックグラウンドでの強制適用

DROIDSIGHT_SENTINEL=1 を設定すると、5 秒ごとに起動するループが開始され、監視対象の各パッケージに対して、維持するよう指示された状態を再適用します。具体的には、監視の登録時に指定された PIN で画面を起動してロックを解除し、ユーザー補助サービスを有効にし、オーバーレイ権限を付与して、実行時権限のリストを許可します。クライアントが監視対象を登録するまでは監視対象は存在しないため、監視対象が空の状態で有効になっているセンチネルは、定期的に起動するだけです。

次の 2 点は明確にしておく必要があります。

• 手動での変更を元に戻します。 監視対象のパッケージの権限を取り消したり、ユーザー補助サービスを無効にしたりすると、5 秒以内に元に戻されます。先に監視対象から削除してください。
• confirm_destructive の確認を求めません。 このゲートは、オペレーターが mcp_android_app_manage を呼び出す場合に適用されます。ループは監視の目的そのものが権限の再付与であるため、同じ基盤の処理を直接呼び出します。監視対象の登録が、その監視によって以後自動的に実行されるすべての処理への同意となります。

このループが行うネットワーク I/O はローカルの ADB 接続に限られ、リモートサービスには接続しません。

ビルドとテスト

このリポジトリでは Rust ツールチェーンのバージョンを固定し、デバイスを変更するシナリオを既定のテストスイートから除外しています。

cargo fmt --all -- --check
cargo clippy --locked --all-targets -- -D warnings
cargo test --locked -- --test-threads=1
cargo build --locked --release --bin droidsight

これらのチェックは Linux、macOS、Windows で実行され、警告を抑制せずに成功します。コンパイラーは rust-toolchain.toml で固定されています。別の CI ジョブでは、宣言されている最小バージョンの Rust 1.89 でクレートの型チェックを行います。

デバイスに影響するコードを変更する前に、CONTRIBUTING.md を確認してください。SECURITY.md では、非公開での報告、機密性の高い証拠の編集、ならびに ADB、ホスト、MCP、ファイルシステム、ログ、シェルに関する信頼境界について説明しています。参加にあたっては、CODE_OF_CONDUCT.md が適用されます。

成熟度

ホストのみで実行するテストスイートでは、プロトコルの解析、スキーマ、シリアライズ、ADB コマンドの構築、並行検出、再接続時の無効化、デバイスの選択、サブプロセスの期限、JSON-RPC バッチ、パスの制限、シェルのクォート、出力の上限、イベントモニターの終了処理、階層の解析、フローの検証、ストリームのフレーミングとライフサイクル、静的フレームのキャッシュ動作、画像のエンコードと座標メタデータ、Samsung のキーロック画面／ウィンドウの解析、インテントの失敗処理を網羅しています。

リリースバイナリーは、Android 13 を実行する 1 台の Samsung デバイスに対し、ワイヤレスデバッグ経由でテストされています。対象には、デバイスの状態、バッテリー、アプリ、階層および要素のスナップショット、OCR、スクリーンショットとそのシーケンス、継続的な H.264 キャプチャ、入力とナビゲーション、インテント、ログ、通知、Wi-Fi スキャン、ファイルの往復処理、ハッシュ計算、セッション、ジェスチャーのキャプチャ、録画、回転状態の復元、クラッシュ一覧表示、クリーンアップが含まれます。アプリ、権限、ユーザー補助、オーバーレイ、テレフォニー、ネットワーク変更、GPS、バッテリーのモック化に関する破壊的な操作は、このテスト範囲から意図的に除外しています。他のメーカーおよび Android のリリースについては、それぞれ個別の適格性評価が必要です。

H.264 デコード

ビジョンキャッシュは openh264 を使用してプロセス内で H.264 をデコードします。openh264 は Cisco の BSD-2-Clause ライセンスの C++ 実装をソースからビルドします。Cisco のロイヤリティ補償の対象となるのは、Cisco 自身が公開するバイナリーであり、自分でコンパイルしたビルドには適用されません。このプロジェクトのバイナリーを再配布する場合、適用される H.264 の特許ライセンスを満たす責任は再配布者にあります。

ライセンス

MIT です。LICENSE を参照してください。