devcdp

DevCDP

MCP 経由で AI アシスタントに本物の Chrome DevTools へのアクセスを提供します。アシスタントはコンソールを読み取り、ネットワークを監視し、DOM をクエリし、ソースマップを解決し、ブレークポイントを設定して、実行中の変数を調べます。そのため、貼り付けられたエラーから推測するのではなく、何が原因で問題が起きたのかを教えてくれます。

MCP に対応するあらゆるアシスタントと、あらゆるウェブアプリで動作します。特定のフレームワーク、製品、企業に依存する機能はありません。

74 個のツール — サーバー自体から生成された完全なリファレンスは docs/TOOLS.md、測定済みのトークンコストとその削減方法は docs/PERFORMANCE.md をご覧ください。

---

できること

コンソール	ファイル名、1 始まりの行番号、スタックトレースを含むログ、警告、未捕捉例外。
ネットワーク	接続した時点からのすべてのリクエストを記録します。メソッド、ステータス、所要時間、サイズ、イニシエーターのほか、リクエストに応じてレスポンス本文も取得します。
DOM	実際の可視性とジオメトリを含むセレクタークエリ、名前付きの計算済みスタイル、変更履歴、iframe のサポート、ダイアログの構造的な検出。
ソース	読み込まれたスクリプトに加え、ソースマップから復元したバンドル前の元ファイル（認証が必要な外部 .map ファイルを含む）。両方を対象にした全文検索も利用できます。
デバッガー	元ファイルの行番号を指定したブレークポイント、ステップ実行、Object と表示する代わりに入れ子のオブジェクトを展開するスコープ検査。
情報の検出	アプリに、フレームワーク、ルーティング、ボタンや入力欄で使えるセレクター、バックエンド API の範囲、プロジェクト独自のドキュメントについて問い合わせます。
共同作業	いつでも操作を引き継げます。クリック、選択、入力した内容は記録され、アシスタントが読み取れます。

特に注意している4つの点

成功を偽りません。 ブレークポイントをバインドできない場合は bound: false と表示し、その理由を説明します。Chrome が破棄した本文についても、その旨を伝えます。すでに再開した一時停止からのキャプチャには、古いデータであることを示します。すべての失敗は {ok: false, code, message, hint} の形式で、次に行う操作も明示します。

把握できる範囲の限界を伝えます。 Chrome は、あとから接続したデバッガーにコンソール履歴を再生できません。そのため、空のバッファーを「エラーなし」と見せかけず、その事実を接続時に正確に報告します。

応答不能になることはありません。 ページへのすべての呼び出しには、こちら側で制限時間を設けています。Runtime.evaluate 自身のタイムアウトはレンダラーによって適用されますが、レンダラー自体が停止している場合には役に立ちません。無限ループで応答しなくなったページも、数秒で失敗として検出し、復旧方法を提示します。さらに DevCDP は、暴走したスクリプトを中断して自動で再試行します。

アプリをフリーズさせたままにはしません。 ブレークポイントは必要な情報を取得すると、自動で再開します。意図的に一時停止を維持した場合も、maxPauseMs の経過後に解除され、切断時にはすべてがクリーンアップされます。

---

インストール

要件： Node 18 以降、Chrome、MCP 対応のアシスタント。

クライアントに合った方法を選んでください。どの方法でも同じサーバーがマシン上で動作し、ホストされることはありません。

任意の MCP クライアント（npm 経由）。 クライアントの MCP 設定に追加します。

{ "mcpServers": { "devcdp": { "command": "npx", "args": ["-y", "devcdp"] } } }

ネイティブ Windows では、一部のクライアントで "command": "cmd", "args": ["/c", "npx", "-y", "devcdp"] が必要です。

Claude Code（プラグインとして）（サーバーに加えて、どのツールを使うかを Claude に伝えるスキルも含まれます）：

/plugin marketplace add Dayananda-D/DevCDP
/plugin install devcdp@devcdp

Cursor： 、 または上記の JSON を ~/.cursor/mcp.json に追加します。

Gemini CLI（使用方法のガイダンスも含む拡張機能として）：

gemini extensions install https://github.com/Dayananda-D/DevCDP

opencode： opencode mcp add を実行するか、opencode.json に追加します。

{ "mcp": { "devcdp": { "type": "local", "command": ["npx", "-y", "devcdp"], "enabled": true } } }

Codex（CLI、デスクトップ、VS Code 拡張機能）をプラグインとして：

codex plugin marketplace add Dayananda-D/DevCDP

VS Code： VS Code にインストール、または MCP: Add Server を実行して NPM Package を選び、 devcdp と入力します。Copilot CLI： コマンド npx -y devcdp を指定して /mcp add を実行します。DevCDP は 公式 MCP Registry に登録されています。VS Code 内のピッカーに表示されるのは、GitHub が厳選したそのレジストリのサブセットであり、別個の掲載リストです。

ソースからインストールする場合、使用方法のガイダンスをアシスタントの指示ファイルにも書き込むセットアップウィザードを利用できます。次の「セットアップ」を参照してください。

Chrome をリモートデバッグで起動し（debug-chrome.bat または chrome --remote-debugging-port=9222 --user-data-dir=<a separate profile>）、アプリを開いて、バグの内容を説明してください。

---

セットアップ

1. node initialize_MCP.js      (or double-click initialize_MCP.bat)
2. Fully quit and reopen your assistant
3. Double-click debug-chrome.bat, open your app
4. Describe the bug

ウィザードはインストール済みのエディターを検出し、それぞれに適した形式の設定を書き込み、ランチャーを配置します。解析できない設定ファイルを上書きすることはありません。代わりに、貼り付けるためのスニペットを表示します。書き込みはすべて、タイムスタンプ付きのバックアップを 1 つ作成したうえでアトミックに行われ、以前のインストールによる重複登録も削除されます。この処理は 23 件のテストでカバーされています。誤ると単に失敗するのではなく、マシンに損害を与えるためです。

---

設定

すべて任意です。アシスタントに devcdp_settings を実行するよう依頼すると、有効な値とそれぞれの値の取得元を確認できます。また、編集可能な注釈付きファイルを書き出すには devcdp_settings_init を実行するよう依頼してください。

ファイルは後の設定が優先される形でマージされるため、インストール全体の基本設定をプロジェクトごとに上書きできます。

<install>/devcdp.settings.json   or  <install>/settings.json
<cwd>/.devcdp/settings.json
<cwd>/devcdp.settings.json

続いて DEVCDP_* 環境変数、さらにツールの引数が適用されます。コメントと末尾のカンマは許容されます。

設定	デフォルト
toasts	true	ステータスメッセージをリアルタイムで表示します
toastMs · toastOpacity · toastMaxVisible	3500 · 0.78 · 3	表示時間、不透明度、同時表示数
badge · badgeCorner · edgePulse	true · "tc" · true	タブのインジケーターと、その周囲で明滅する枠線
badgeCorner の位置	tc · bc · tl · tr · bl · br	オーバーレイの配置場所です。チップをドラッグすると好きな位置に移動でき、その位置はオリジンごとに記憶されます。メッセージもチップに追従するため、toastCorner は badgeCorner に合わせて移動します
showCursor · highlightInspected	true · true	インタラクションが発生した場所と、検査した対象を表示します
ownerTimeoutMs	45000	セッションから応答がなくなってから、インジケーターが消えるまでの時間です
followNewTabs	true	アプリが自ら開いたタブに印を付けて保持し、ポップアップが見落とされないようにします
chromeProfile	"isolated"	サインイン済みの Chrome を再利用する場合は "default"、またはパスを指定します
disableWebSecurity	false	オフのままにしてください。デバッグ対象の CORS の不具合が隠れてしまいます
chromeFlags	[]	追加の Chrome フラグ
evalTimeoutMs · toolTimeoutMs	8000 · 30000	応答性を保つためのタイムアウト上限
autoResumeDefault · maxPauseMs	true · 30000	自律的な一時停止の制御
captureInputValues	false	入力した値を常時キャプチャします
docsRoot	自動	プロジェクトの README とドキュメントを読み込む場所
sharedMemoryDir	null	チーム全体で学習した修正を共有します
tabGroupMode	"session"	セッションごとにタブグループを作成するか、すべてをまとめる場合は "single" を指定します

設定する価値があるのは docsRoot と sharedMemoryDir の2つです。前者を設定するとアシスタントが専門分野の語彙を学習でき、後者を設定すると「チームの修正が蓄積される」ようになります。

---

複数のセッションを同時に実行する

複数のエージェントが、1台のマシン上で安全にデバッグできます。各セッションは ~/.devcdp/registry/ 内のレジストリでタブを 確保 します。この操作はアトミックに行われるため、2つのプロセスが同じタブを確保することはありません。セッションが停止するとハートビートが途絶え、確保状態は解放されるため、処理が詰まったままになることはありません。

• 新しいセッションには未確保のタブが割り当てられます。すべてのタブが使用中の場合は、新しいタブを開きます。空白のページではなく、目的のページ を開き、その理由も表示します。
• アシスタントを再読み込みすると、2つのサーバープロセスが一時的に重複します。そのため、終了する側がタブを解放できるよう短い猶予期間が設けられ、新しい側はそのまま再接続します。
• browser: 'new' は、専用のポートとプロファイルを持つ別の Chrome を起動します。
• window: 'new' を指定すると、セッション専用のブラウザーウィンドウが開きます。
• sessions_list では、どのセッションがどのタブを使用しているか確認できます。

使用中のタブを確認する

使用中としてマークされた各タブには、1px の境界線と小さな識別チップが表示されます。境界線は、誰が操作しているかを示します。

• 青くゆっくり明滅 — DevCDP が作業中です
• 緑色で点灯 — 操作があなたに引き渡されています
• 赤色で点灯 — 問題が発生しました

状態は3つ、色も3つです。セッションがいくつ実行中でも、それぞれの色が示す意味は1つだけです。セッションはチップのテキストとそれぞれの Chrome タブグループで見分けられます。色相で見分ける方式ではありません。ひと目で知りたいのはタブがあなたの操作を待っているかどうかだけなのに、境界線をパズルにしてしまうためです。

アプリが自ら開くタブ — window.open、target="_blank"、独立したウィンドウで開く詳細画面など — もマークされて保持され、「開いたタブ」と表示されます。devtools_status では tabsAppOpened の下に一覧表示され、切り替えに使う呼び出しも確認できます。

インジケーターが、それを描画したセッションより長く残ることはありません。 通常どおり終了した場合 — アシスタントを閉じる、接続が切れる、セッションが終了する — 境界線はすぐに消えます。サーバーが強制終了され、クリーンアップできなかった場合、オーバーレイはセッションからの応答が途絶えたことを検知し、ownerTimeoutMs（45 秒）以内に自ら削除します。同時に、タブもグループから外します。いずれの場合も、画面に境界線が表示されていれば、セッションが実際に存在します。古いビルドが残した境界線は、どのライブセッションにも所有されていないものを node scripts/sweep.mjs で削除できます（最初に確認する場合は --dry を指定します）。

ステータスメッセージは、半透明で自動的に消えるトーストとして表示されます。ポインターの動きに合わせてリングが動き、クリックするたびに波紋が表示されるため、エージェントの操作を追えます。デバッガーが一時停止すると、Chrome 本来の「デバッガーで一時停止中」バナーが表示されます。これはブラウザーの UI で、ページには何も追加しません。

このレイヤー全体は pointer-events: none であり、引き継ぎ中の確認ボタン（91×24px）を除いて、クリックを妨げることはありません。実際のマウスイベントを通過させるテストもあります。

Chrome の実際のタブグループは同梱の拡張機能によって作成され、各セッションのタブが名前付きの青いグループにまとめられます。Chrome ではツールによる拡張機能のインストールはできません。Google Chrome のブランド版は --load-extension を無視し（Chrome 自身のログに「not allowed in Google Chrome」と記録されます）、デバッグポート経由で Extensions.loadUnpacked も公開していません。そのため、次のいずれかを選んでください。

• 手動操作なし： chromePath に Chromium または Chrome for Testing を指定します。これらのビルドでは切り替えが許可されているため、拡張機能が自動的に読み込まれ、グループ化が機能します。そのようなバイナリがすでにマシンにある場合、devtools_status で場所を確認できます。
• ブランド版 Chrome： 一度だけインストールします。chrome://extensions → デベロッパーモード → パッケージ化されていない拡張機能を読み込む → extension/ を選択します。デバッグプロファイルは永続化され、debug-chrome.bat と DevCDP 独自のランチャーで共有されるため、インストールは一度だけで済みます。

devtools_status.tabGrouping では、タブが実際にグループに属しているかどうかを確認できます。属していない場合は、拡張機能がインストールされていないためか、インストール済みの拡張機能でエラーが発生したためかも、エラー内容とともに報告されます。グループ化はほかの機能には影響しません。境界線、チップ、window:'new' は、いずれもグループ化なしで機能します。

---

アシスタントと一緒に操作する

頼まれるまで待つ必要はありません。クリック、入力、選択した内容は記録され、アシスタントは session_get_user_actions を使って、どの要素か、どの選択肢か、入力した値を読み取ります。

タブ上で Ctrl+Shift+D を押すと、明示的に操作があなたに引き渡されます。これにより、入力値を取得するウィンドウも開くため、「この参照を使って」と伝えた内容がアシスタントに届きます。そのウィンドウの外では入力値はプライベートに保たれ、いずれの場合もパスワードに似たフィールドはマスクされます。

アシスタントにあなたしかできない操作が必要な場合、ページ上で依頼し、**「完了しました ✓」**ボタンが押されるのを待ちます。このボタンだけが明確な合図です。Chrome は自動化による入力も信頼された入力として報告するため、人間が操作したことを確実に証明することはできません。ツールはそのことを正直に伝え、できるふりはしません。

---

一般的な調査

"The save button does nothing. Find the exact line."

1. devtools_connect — 接続し、タブを確保してマークします
2. source_search("save") — パスを指定せず、内容からハンドラーを見つけます
3. debugger_set_breakpoint(file, line) — bound: true を返します
4. クリックを実行します
5. debugger_get_capture — 一度の呼び出しで、一時停止時のスコープ、コンソール、ネットワークを取得します
6. 実際に存在する行で実際に観測された値が回答になります

ブレークポイントは自動的に再開されるため、ブレークポイントに引っかかったクリックも最後まで実行されます。

関数は分かっていてもファイルが分からない場合（フレームワークでは一般的なケースです）は、 debugger_set_breakpoint_at_function("app.store.save") を使うと、エンジンがその 関数の定義場所を探し、最初の文で停止します。ソーステキストから名前を検索するのは 信頼できません。Foo.bar = function のように代入された関数は "bar: function" で検索しても 見つからず、その検索では別のクラスの無関係なメソッドが返されることもあります。

フレームワークのオブジェクトグラフでも、キャプチャは小さく保たれます。重要な変数だけが 表示され、大きすぎるものはその内容が示されます（"constructor", 77747 bytes expanded）。 そのため、debugger_evaluate_at_frame で必要な部分だけを読み取れます。

---

セキュリティ

ランチャーは専用の Chrome プロファイルを使用するため、普段のブラウジングには 影響しません。また、ウェブセキュリティを有効のままにします。無効にすると、デバッグ対象の クロスオリジンエラーが見えなくなります。

入力された値は、有効化するか共同作業中でない限り記録されません。パスワードのような フィールドは、いずれの場合も常にマスキングされます。

リモートデバッグを利用すると、ポートに接続できるものなら何でもブラウザープロファイルを 完全に制御できます。デバッグプロファイルは開発用に使い、個人アカウントには使わないでください。

---

ディレクトリ構成

index.js                 entry point
server.js                shim for older configs pointing here
src/
  core/      config, context, buffers, structured errors, tool registry
  cdp/       connection, target selection, session claim registry, launching
  browser/   the injected in-page agent
  debug/     source maps, scope expansion
  store/     learned-memory store
  tools/     one module per tool group
extension/               companion extension for Chrome tab groups
plugins/devcdp/          Claude Code plugin: manifest, launcher, skill (generated)
server.json              MCP Registry manifest; must agree with package.json
scripts/gen-docs.mjs     regenerates docs/TOOLS.md and the plugin skill
docs/TOOLS.md            full tool reference (generated)
docs/PUBLISHING.md       how each marketplace listing is made and kept current
test/
  validate.mjs           offline checks, no browser needed
  installer.test.mjs     the setup wizard, against real files
  integration.mjs        real Chrome against a fixture app
  fixture-app/           small app with a staged bug and a real source map
BACKLOG.md               every defect found, its fix, and what remains

DevCDP の開発

node scripts/call.mjs <tool> '<json>'   call one tool, see the exact response and its cost
node scripts/mcp-probe.mjs             the same thing over real MCP, raw JSON-RPC

ブレークポイント、ログ、このコードベースでこれまでに遭遇した落とし穴については、 docs/DEBUGGING.md を参照してください。

テスト

npm run validate          offline checks
npm run test:installer    the setup wizard
npm test                  all three suites
npm run docs              regenerate the tool reference

199 件のチェックを実行します。統合テストスイートは、読み込みがすでに完了した ページに接続します。これは、以前のバージョンで正しく処理できていなかったケースです。 npm run validate は docs/TOOLS.md が最新でない場合に失敗するため、リファレンスが古くなることはありません。

トラブルシューティング

ツールが表示されない — アシスタントを完全に終了して（ウィンドウを閉じるだけではなく、 トレイ／メニューから終了してください）、再度開きます。まだ表示されない場合は、ウィザードを 再実行してください。

「Chrome に接続できません」 — debug-chrome.bat から起動し、 http://localhost:9222/json/version を確認してください。ポートを使用できる Chrome は 1 つだけです。

ブレークポイントが一度も発生しない — debugger_list_breakpoints を実行して bound を確認してください。バインドされていないブレークポイントには理由が表示されます。

プロジェクトを支援する

DevCDP は無料の MIT ライセンスで提供されており、1 人で開発・保守しています。デバッグに かかる午後の時間を節約できたなら、GitHub でのスポンサー が開発の継続を支えます。ホスト型のセットアップ、エンジニア間で共有できる学習済みメモリー、 またはオンボーディングワークショップを希望するチームは、イシューを作成してご相談ください。

プライバシーとライセンス

DevCDP はローカルで動作し、接続した MCP クライアント以外には何も送信しません： PRIVACY.md。MIT ライセンスです：LICENSE。

セレクターで何も見つからない — dom_list_frames を実行してください。コンテンツが iframe 内にある可能性があります。frame: 'all' を指定して再試行してください。

接続直後にコンソールまたはネットワークが空 — 想定どおりの動作です。キャプチャは接続時に 開始されます。page_reload を実行すると、DevCDP が監視した状態でページを再読み込みします。

ページが応答しなくなる — メインスレッドがブロックされています。通常はアプリの JS の ループが原因です。page_interrupt は実行中のスクリプトを中断します。再読み込みしても ブロックは解消されません。

タブを利用できない — sessions_list を実行すると、どのセッションがタブを保持しているか 確認できます。