serve-droid

Android向けの共有ブラウザコックピット兼エージェントコントロールプレーン。 エミュレータまたは実機をストリーミングし、ChromeやEdgeから操作したり、セマンティックUIツリーとLogcatを検査したり、同じセッションをMCP互換のコーディングエージェントに引き渡したりできます。

ステータス: v0.1開発リリース。公開APIはバージョン管理されていますが、ビデオ転送とデバイス互換性は公開済みサポートマトリックスでの検証がまだ必要です。

npx serve-droid
# → Browser cockpit at a local authenticated URL

1つの共有セッション: コンパクトなアクティブデバイスコントロールは左側に表示され、ライブのAndroidサーフェスがプライマリワークスペースを占有します。ワイド画面ではエージェントインスペクタがコンテキストに応じて右側にフロートし、フィルタリングされたLogcat、セマンティックUI、プライバシーセーフなActivityを切り替えます。狭いウィンドウでは、操作面を縮小する代わりにデバイスの下にスタックします。決定論的デモは、認証付きファイルインストールとクリップボードフローも実行します。これは実機検証ではありません。ハードウェアの証拠はリリースチェックリストで別途追跡されます。

含まれるもの

• レスポンシブなブラウザコックピットでのH.264デバイスストリーミング。リリース前の同じライブscrcpyセッションが、ポインタのDOWN、合成されたMOVE、UP/CANCELイベントを直接運びます。

• デバイス上のマウスホイールおよびトラックパッドスクロール。境界付きscrcpyタッチジェスチャに合成されるため、高解像度のブラウザ入力がデバイスコマンドのバックログを生み出すことはありません。

• デコード済みライブフレームからのワンクリックスクリーンショット取得。認証付きデバイスフォールバック、プレビュー、ダウンロード、サポート対象ブラウザでのクリップボード操作に対応。

• 欠落または曖昧なマッチで停止する、正確なセマンティック要素ターゲティング。

• 検索可能で優先度フィルタリング対応のLogcat。一時停止、クリア、コピーのコントロール付き。

• ブラウザの再生ミュートとは別に、デバイスレールでの明示的なAndroidシステム音量ダウン/アップコントロール。

• 最近の構造化セッション、デバイス、コントロールイベントのプライバシーフィルタ適用済みインメモリActivityタイムライン。

• セキュアなLANトークン入力と、フォーカスされたAndroidフィールドへの境界付きクリップボード貼り付け。

• バイト進行状況と明示的なAndroid処理フェーズを伴うAPKまたはファイル転送のドラッグ＆ドロップ。

• 画面、UI階層、フォアグラウンドアプリ、デバイス状態、増分ログを含む1つの境界付き観測。

• CLI、認証付きHTTP/WebSocket API、MCP、Agent Skillを通じた同じ機能。

Related MCP server: phone-mcp-server

なぜ

Android Studioはデバイスをミラーリングし、scrcpyは優れたネイティブ表示/操作を提供し、Maestroは強力なテスト自動化システムです。serve-droidは異なるループに焦点を当てています。開発とデバッグ中に、人間とAIエージェントが1つの観察可能なブラウザセッションを共有するというループです。

インスピレーション

ブラウザファーストのコックピット方向性は、Evan Baconのserve-simに触発されました。serve-droidは、ADB、scrcpyトランスポート、Logcat、セマンティック観測、MCPを中心に構築された独立したAndroid特化実装です。

要件

• Node.js 22以降

• PATH、ANDROID_HOME、またはANDROID_SDK_ROOTにadbを含むAndroid SDK Platform Tools

• adb devices -lに表示されるAndroid 8 / API 26+エミュレータまたはデバイス

• 最新のChrome、Edge、Safari、またはFirefoxブラウザ。ChromiumはWebCodecsを使用し、SafariとFirefoxはコストの高いTinyH264ソフトウェアフォールバックを使用します。

Android Platform Toolsは、サイレントにダウンロードされたり再配布されたりすることはありません。

クイックスタート

npx serve-droid doctor
npx serve-droid doctor --browser
npx serve-droid avd list
npx serve-droid start --detach
npx serve-droid list --json
npx serve-droid activity --since 0 --json

serve-droid activityは、ブラウザインスペクタに表示されるものと同じ境界付きのプライバシーフィルタ適用済みセッションタイムラインを読み取ります。1つのライブセッションを選択し、そのセッションで内部的に認証し、ベアラートークンを公開せずにカーソル再開をサポートします。Activityガイドを参照してください。

固定ポートを選択する場合は、デバイスに触れる前にプローブしてください。占有ポートは安定したPORT_IN_USEコードと終了ステータス31を返します。--port 0は安全な一時的な割り当てを維持します。

npx serve-droid doctor --port 47321 --json
npx serve-droid start --port 47321

デバイス再生オーディオはオプトインであり、人間が有効にするまでブラウザ再生はミュートされたままです:

npx serve-droid start --audio

デバイスオーディオとプライバシーを参照してください。

表示されたローカルURLを開いてください。サーバーは127.0.0.1でリッスンし、ランダムなトークンを生成してローカルUIに注入します。デバイスを選択するには:

npx serve-droid --device emulator-5554

インストール済みエミュレータは、serve-droid avd start <name>およびserve-droid avd stop <serial>で明示的に管理できます。SDKコンテンツが自動的にダウンロードまたはライセンスされることはありません。AVDライフサイクルガイドを参照してください。

独立したトークンと境界付きリソースで複数の接続デバイスを検査するには:

npx serve-droid grid --max-devices 4

マルチデバイスグリッドのセキュリティと分離モデルを参照してください。

座標は正規化されています: (0, 0)は論理的な左上、(1, 1)は右下です。

npx serve-droid tap 0.5 0.5
npx serve-droid swipe 0.5 0.8 0.5 0.2 --duration 350
npx serve-droid app deep-link 'servedroid://fixture/example'

失敗したADB操作は、Androidが明示的なキーガードまたは入力ポリシーの証拠を報告しない限り、一般的なエラーを保持します。操作失敗の診断でDEVICE_LOCKED、SECURE_SCREEN、INPUT_RESTRICTEDの契約を参照してください。

ブラウザの直接ポインタは、カーソルまたは指が動いている間、認証付きのbegin → move* → endライフサイクルを制御WebSocket経由でストリーミングするようになりました。ブラウザは1つのリクエストと1つの最新のmoveを保留し、サーバーはストリームにscrcpyの1つのフィンガーの排他的所有権を与え、固定エンコードフレームサイズに対してマッピングします。beginの前にscrcpyが利用できない場合、リクエストはデバイス入力の前に拒否され、コックピットは既存の境界付きリリース時アクションを安全に使用します。begin成功後、失敗がADB経由で再生されることはありません。低頻度の同一点ハートビートが意図的な長押しを維持し、放棄されたストリームは2秒間の非アクティブ後にベストエフォートのキャンセルを受け取ります。

ブラウザでAndroidサーフェスにホバーし、マウスホイールまたは2本指トラックパッドスクロールを使用してください。バーストは1つの境界付きカーソルアンカータッチスワイプに合成されます。修飾キーを使用したブラウザズームジェスチャは変更されません。

セッションキャプチャは明示的かつ境界付きです。--record ./recordingsは元のH.264ストリームとプライバシーフィルタ適用済みイベントサマリーを保存します。トークン、Logcat、入力テキスト、URL、ファイル内容を記録することはありません。代わりに--record-controls ./recordingsを使用すると、すぐに記録せずにブラウザの開始/停止を許可できます。コックピットがホストパスや制限を選択することはありません。録画と保持ガイドを参照してください。確定した録画は、Perfettoでのタイムライン検査のためにserve-droid recording traceでエクスポートすることもできます。

MCP

{
  "mcpServers": {
    "serve-droid": {
      "command": "npx",
      "args": ["-y", "serve-droid", "mcp"]
    }
  }
}

MCPサーフェスは、任意のシェルアクセスではなく、明示的な境界付きツールを意図的に提供します。MCPガイドを参照してください。

セキュリティ

• デフォルトでループバックのみにバインド。

• 読み取り、変更、ビデオ、制御のベアラー認証。

• ブラウザWebSocketはURLではなくサブプロトコルヘッダーで資格情報を運びます。

• 任意のADBまたはホストシェルエンドポイントはありません。

• アップロードは256 MiBに制限され、プライベート一時ディレクトリに書き込まれ、直ちに削除されます。

• clearとuninstallは、非対話型クライアントからの明示的な確認を必要とします。

LANインターフェースにバインドする前にSECURITY.mdをお読みください。

既存の名前付きCloudflare Tunnelを通じた短時間のリモートアクセスは、明示的な同意、HTTPS、ベアラー認証、ハード有効期限がある場合にのみ利用できます。使用前にトンネルの脅威モデルとセットアップガイドをお読みください。

サポート対象と延期対象

v0.1はmacOS、Linux、Windows、Android API 26+、ローカルエミュレータ、USBデバイス、Wi-Fi ADB、Chrome、Edge、Safari、Firefoxを対象としています。インストール済みAVDライフサイクルコントロール、オプトインの境界付きローカル録画、TinyH264ブラウザフォールバック、API 30+のオプトインデバイスオーディオ、オプトインで期限付きの名前付きトンネルサポートが含まれます。クラウドデバイスラボ、アカウント、マルチユーザーロール、AVD作成/プロビジョニング、iOS、任意のシェルアクセスは延期されます。ブラウザサポートマトリックスを参照してください。

開発

pnpm install
pnpm verify
pnpm --filter @serve-droid/cli dev -- doctor

Androidフィクスチャソースはfixtures/android-test-appの下にあります。実機テストはSERVE_DROID_DEVICE_TEST=1が設定されている場合のみ実行されます。

完了した作業と残りのハードウェア、プラットフォーム、公開ゲートについては、証拠ベースのリリースチェックリストを参照してください。

プロジェクトTODO

• 保護されたmain、CodeQL、Dependabot、シークレットスキャニングを備えたオープンリポジトリを公開する。

• 共有CLI、HTTP/WebSocket、MCP、Agent Skill、ブラウザコックピット基盤を出荷する。

• 再現可能で明確にラベル付けされたコックピットスクリーンショットをこのREADMEに追加する。

• ブラウザコックピットを