web-debug-mcp

web-debug-mcp は、Codex およびその他の MCP クライアント向けのローカルで動作するエージェントネイティブな Web デバッグサーバーです。ブラウザセッション、JavaScript デバッガ、境界付きのランタイム証跡、再現可能なフロー検証を統括する、小さなツールサーフェスを 1 つ公開します。

現在のインクリメントでは、フレームワークに依存しないブラウザターゲット、Chromium/CDP、WebDriver BiDi 証跡を備えた Safari WebDriver、自動注入される React 開発ブリッジ、Vite モジュールグラフ/HMR エンドポイント、そして境界付きのサーバーログ・ルートコンパイル・Server Action ルックアップ・観測されたリクエスト実行証跡を備えた Next.js 開発サーバーメタデータをサポートしています。ブラウザ固有の制限は明示されたままです。これにより、フレームワーク固有のコンテキストは、個別のツールカタログを追加する代わりに、同じ MCP ファサードの背後に保持されます。

含まれるもの

• プロセスを起動しないプロジェクト機能検出。

• 明示的な CDP エンドポイントによるローカル Chromium アタッチモード。

• 明示的なリモート CDP アタッチは allowRemote: true の場合のみサポートされます。ターゲットは非分離としてマークされ、自動検出されることはありません。

• 明示的な実行可能パスによるローカル Chromium 起動モード。

• ローカルの safaridriver または明示的な WebDriver エンドポイントによる Safari WebDriver モード。インストールされている Safari が公開している場合、BiDi コンソールイベントとネットワークイベントを備えています。

• 同一オリジンでのブラウザ操作: ナビゲート、クリック、入力、待機、リロード。

• JavaScript ブレークポイント、一時停止制御、境界付きコールフレーム、およびデフォルトでの読み取り専用評価。

• コンソール、ネットワークメタデータ、DOM サマリー、スクリーンショット、デバッガ証跡を 1 つの編集済みバンドルにまとめて提供。

• React コンポーネントツリー、フック値、ソース位置、レンダー回数、境界付きコミットサマリー、プロファイラー所要時間、フラットなフレームグラフビュー、および開発ビルドが React コミットを公開する場合の推測されたレンダー原因。

• webDebugVitePlugin() 開発プラグインによる Vite モジュール/インポーターグラフ、HMR ステータス、変換コード差分、ソースマップサマリー。

• ログが検出されたプロジェクトルート内に留まる場合の、境界付きで編集済みの Next.js 開発ログテール。

• web_next_inspect による明示的な Next.js ルートコンパイルと Server Action ルックアップ。さらに、ブラウザが Next-Action リクエストを送信した場合の正規化されたサーバーリクエストトレースとリクエスト連動の実行証跡。

• キャプチャ内の境界付きリプレイタイムラインと web_replay_seek によるフレームルックアップ。restore: true は安全に保持されたアクションのみをリプレイし、サニタイズされたフォーム入力を拒否します。

• シンプルな修正後チェックを備えた再現可能なアクションシナリオ。

• 決定的なバニラフィクスチャとプロジェクトネイティブなハーネスチェック。

• ライブ React/Vite フィクスチャ、自動 React ブリッジ、モジュールグラフ/HMR スモークテスト。

• ライブ Next.js App Router フィクスチャと /_next/mcp ランタイムスモークテスト。

Related MCP server: Kaboom Browser AI Devtools MCP

要件

• Node.js 20 以降。Safari BiDi には Node 20.10+ と --experimental-websocket、または Node 21+ が必要です。古いランタイムでは Safari WebDriver アクションと文書化されたネットワークフォールバックは引き続き利用できますが、BiDi コンソールの制限が報告されます。

• ライブセッション実行時には Chromium ベースのブラウザ。

• web_session_start に渡す明示的な WEB_DEBUG_CHROME_EXECUTABLE_PATH または明示的な cdpEndpoint のいずれか。

開発コマンド

npm install --no-audit --no-fund
npm test
npm run typecheck
npm run build
npm run harness:check
npm run smoke:live
npm run smoke:react-vite
npm run smoke:next
npm run smoke:safari

npm run serve:fixture でフィクスチャを実行します。サーバーは 127.0.0.1 にバインドされ、デフォルトでポート 4173 を使用します。別のポートを使用するには WEB_DEBUG_FIXTURE_PORT を設定します。

デフォルトの macOS Chrome パスが利用できない場合は、WEB_DEBUG_CHROME_EXECUTABLE_PATH を設定した後、npm run smoke:live を実行します。バニラフィクスチャを起動し、app.js にブレークポイントを設定し、ボタンをクリックし、一時停止セーフな証跡パスをキャプチャし、所有するブラウザとフィクスチャのプロセスをクリーンアップします。

npm run smoke:react-vite を実行して Vite フィクスチャを起動し、React コンポーネント/状態の証跡を検証し、fixtures/react-vite/src/App.jsx で一時停止し、送信済み支払いフローをリプレイします。

Vite アプリケーションの場合は、開発専用プラグインを vite.config.ts に追加します:

import { webDebugVitePlugin } from "web-debug-mcp/vite";

export default {
  plugins: [webDebugVitePlugin()],
};

このプラグインは、デバッグセッション中に使用されるローカルの読み取り専用モジュールグラフエンドポイントを提供します。本番サーバーでは有効にしないでください。

npm run smoke:next を実行して Next.js App Router フィクスチャを起動し、組み込みの /_next/mcp エンドポイントにクエリを実行し、ルート/プロジェクト/コンパイルメタデータと境界付きサーバーログテールを検証し、クライアントルートハンドラーフローを実行します。

npm run smoke:safari を実行して、Safari WebDriver 経由でバニラフィクスチャを実行します。最初に Safari の設定 → 開発 → リモートオートメーションを許可を有効にしてください。Safari は可視状態で実行され、BiDi コンソール証跡をキャプチャし、ネットワーク証跡が BiDi から来たのか、境界付き Performance Resource Timing フォールバックから来たのかを報告します。Safari の JavaScript デバッガは、このアダプターでは引き続き利用できません。

Safari 27 と Safari Technology Preview 247 には、Apple 公式の Safari MCP サーバーが含まれています。ブラウザネイティブの DOM、ネットワーク、コンソール、スクリーンショットツールが望ましいサーフェスである場合は、その公式サーバーを使用してください。このリポジトリは、重複する公開 Safari MCP カタログを追加しません。WebDriver アダプターは、古い Safari バージョン向けのスイートの単一ファサード互換パスとして、また共有セッション/証跡オーケストレーションとして引き続き有用です。

開発中は npm run dev で MCP サーバーを実行し、npm run build 後は node dist/index.js で実行します。MCP プロトコルメッセージは stdout を使用します。診断情報は stderr に留める必要があります。

MCP ワークフロー

1. プロジェクトルートを指定して web_project_detect を呼び出します。

2. ループバック URL と明示的なブラウザ接続または実行可能ファイルを指定して web_session_start を呼び出します。

3. web_browser_action と web_breakpoint_set を使用して問題を再現します。

4. 境界付きの証跡バンドルを 1 つ取得するために web_issue_capture を呼び出します。

5. Next.js の場合は、web_next_inspect を呼び出してルートをコンパイルするか、Server Action ID を解決します。

6. web_repro_record でフローを保存し、後で web_fix_verify で実行します。

7. web_replay_seek を使用して保持されたキャプチャフレームを 1 つ検査します。フレームに安全で機密性のないアクションが含まれる場合にのみ restore: true を渡します。

8. セッションが不要になったら web_session_close を呼び出します。

サーバーは通常のセッション中にプロジェクトに書き込みを行いません。スクリーンショットは一時的なセッションごとのアーティファクトディレクトリに保存され、パスとして返されます。

安全デフォルト

• allowRemote が明示的に有効化されない限り、ブラウザ URL はループバックのみです。

• ブラウザのナビゲーションはセッションオリジンに留まります。

• 外部 CDP アタッチは非分離としてマークされます。

• コンソール、ネットワーク、デバッガのローカル変数、評価値は編集され、境界が設定されます。

• 生のレスポンスボディ、Cookie、認証値、ブラウザストレージはコアアダプターによって収集されません。

• allowSideEffects が明示的に true でない限り、評価は副作用を拒否します。

現在の境界

このリポジトリはローカル開発者ツールであり、ホスト型サービスではありません。本番デプロイメント、CI ワークフロー、未認証/自動検出のリモートブラウザ制御、または完全な React DevTools プロファイラー/フレームグラフの同等性はありません。React の所要時間とレンダー原因の詳細は境界が設定され、DevTools フックから推測されます。Vite の来歴とソースマップは、完全なソースマップデバッガではなくサマリーです。Next.js の実行証跡は、リクエスト連動の Server Action メタデータ、リクエストインサイト、境界付きログに限定されます。Safari デバッガの同等性は利用できず、Safari 26 では Performance Resource Timing ネットワークフォールバックが必要になる場合があります。リプレイ復元は安全に保持されたアクションに限定され、アプリケーション状態のタイムトラベルではありません。明示的なリモート CDP アタッチ、Safari WebDriver アクション/DOM/スクリーンショット、明示的な機能警告、境界付きリプレイ復元が利用可能です。承認された外部リモートホストと、呼び出し元が提供するハーネス認証証跡が、それぞれの主張に対して引き続き必要です。