h5-devtools-mcp

h5-devtools-mcp

English | 简体中文

コーディングエージェント（Claude Code、Codex、Cursor…）が、実機の Android WebView 内で実行中の H5 ページをデバッグできる MCP サーバーです。コンソール出力や捕捉されていない例外を読み取り、chrome://inspect を開かずにページ内で JavaScript を実行できます。

状態：v0.1、初期段階です。Android のみ対応しています。

仕組み

Coding agent ──MCP (stdio)──▶ h5-devtools-mcp ──adb forward──▶ webview_devtools_remote_<pid> ──CDP──▶ WebView page

デバッグ可能な各 WebView は、抽象 Unix ソケット上に Chrome DevTools Protocol エンドポイントを公開します。サーバーは adb 経由でそれらのソケットを検出し（chrome://inspect と同じ方法です）、ローカルポートに転送して CDP に接続します。

要件

• Node.js 18+
• PATH 上の adb（または ADB_PATH を設定）
• USB デバッグを有効にした Android デバイス
• アプリで WebView デバッグを有効にする必要があります（通常、デバッグビルドでは有効です）。

WebView.setWebContentsDebuggingEnabled(true);

セットアップ

# Claude Code
claude mcp add h5-devtools -- npx -y h5-devtools-mcp

他の MCP クライアント（Cursor、Codex…）でも、同じコマンドを使用します：npx -y h5-devtools-mcp。

ソースから

git clone https://github.com/xianguoGou/h5-devtools-mcp.git
cd h5-devtools-mcp
npm install && npm run build
claude mcp add h5-devtools -- node /absolute/path/to/h5-devtools-mcp/dist/index.js

ツール

ツール	機能
list_targets	デバッグ可能なページを一覧表示します：アプリのパッケージ、タイトル、URL、表示状態
attach	ページに接続し、コンソール出力のバッファリングを開始します
get_console	バッファー内のエントリーを読み取ります。レベル／キーワード／exclude_keywords でフィルタリングし、since_seq を使って差分を取得できます
evaluate_js	ページ内で JavaScript 式を実行し、結果を返します（Promise は await されます）
detach	ページから切断します

出力はトークン消費を抑えるよう設計されています。1 行にまとめたコンパクトなエントリー、長いメッセージの切り詰め、そして since_seq により、エージェントはターンごとにバッファー全体を読み直す代わりに、新しい内容だけを読み取れます。

例

> list_targets
- id: R5CT1234/webview_devtools_remote_8812/3A1F…
  app: com.example.app (pid 8812) on SM-S9180
  title: "Order"
  url: https://m.example.com/order

> get_console { "levels": ["error"] }
#41 10:32:01.123 [error exception] TypeError: Cannot read properties of undefined (reading 'price')
    at https://m.example.com/assets/index-8f2a.js:1:48213
next since_seq: 57

トラブルシューティング

• 「no debuggable WebView found」 — アプリで WebView デバッグが有効になっていないか、まだ WebView が起動していません。先に H5 ページを開いてください。
• 「debugger in use」 — ページに接続できるデバッガーは 1 つだけです。chrome://inspect の DevTools ウィンドウを閉じてください。
• 「unauthorized」 — デバイスで USB デバッグの確認プロンプトを承認してください。

既知の制限事項

• デバッガー使用中の検出はベストエフォートです。 /json/list から webSocketDebuggerUrl が省略されることを前提としています。最近の Chromium は 1 ページに複数の CDP クライアントを接続できるため、DevTools ウィンドウが開いたままでも接続に成功する場合があります。古い WebView では接続が拒否されることがあります。
• 応答しないアプリがあると、list_targets に約 3 秒かかることがあります。 ソケットは 1 つずつ 3 秒のタイムアウトで照会されます。また、Android はバックグラウンドのアプリをフリーズするため、その WebView ソケットは応答を停止します。attach は対象自身のソケットのみを再確認するため、高速です。
• evaluate_js はページのすべての権限で実行されます — Cookie、ストレージ、トークンの読み取りや、ページ状態の変更が可能です。エージェントのツール権限プロンプトで保護してください。
• e2e スクリプトではポート 9333 が空いている必要があります。 前回の実行で headless Chromium が残っていると、そのプロセスに接続します。先に終了させてください。

開発

e2e テストでは、スマートフォンの代わりに偽の adb と headless Chromium を使用します。

npm run build
CHROME=/path/to/chrome npm run test:e2e

ロードマップ

• デバイスと WebView ページの検出
• コンソールメッセージ、捕捉されていない例外、ブラウザーログのエントリー
• ネットワークリクエストとレスポンス
• JSBridge 呼び出しのログ記録（設定可能なブリッジ形式）
• evaluate_js
• screenshot
• JSBridge のモック
• iOS（WebKit Inspector Protocol 経由の WKWebView）

ライセンス

MIT