MCP JS Debugger

MCP JS デバッガー

Chrome DevTools Protocol のデバッグ機能を公開する MCP（Model Context Protocol）サーバーです。AI アシスタントが JavaScript および TypeScript アプリケーションをデバッグできるようにします。

機能

• CDP 互換のデバッガー（Node.js、Chrome、Edge）に接続
• ブレークポイントの設定、一覧表示、削除
• コードのステップ実行（オーバー、イン、アウト）
• ソースマップ対応のコールスタックの検査
• 任意のスタックフレームで式を評価
• 変数の表示と変更
• 例外発生時に一時停止
• トランスパイルされたコードのデバッグに対応する完全なソースマップサポート

インストール

npm install
npm run build

Claude Code の統合

Claude Code の設定に追加します。

claude mcp add mcp-js-debugger -- npx mcp-js-debugger

または、.mcp.json に追加します。

{
  "mcpServers": {
    "mcp-js-debugger": {
      "command": "npx",
      "args": ["mcp-js-debugger"]
    }
  }
}

使い方

デバッグ対象の起動

インスペクターを使って Node.js アプリケーションを起動します。

# Pause on first line (recommended for setting initial breakpoints)
node --inspect-brk=9229 your-script.js

# Or start without pausing
node --inspect=9229 your-script.js

利用可能なツール

ツール	説明
connect_debugger	WebSocket URL を使って CDP エンドポイントに接続
disconnect_debugger	デバッグセッションから切断
set_breakpoint	URL と行番号を指定してブレークポイントを設定
remove_breakpoint	ID を指定してブレークポイントを削除
list_breakpoints	セッション内のすべてのブレークポイントを一覧表示
resume_execution	一時停止後に実行を再開
step_over	現在の文をステップオーバー
step_into	関数呼び出しにステップイン
step_out	現在の関数からステップアウト
pause_execution	実行中の処理を一時停止
get_call_stack	ソース位置を含む現在のコールスタックを取得
evaluate_expression	JavaScript 式を評価
get_scope_variables	スコープ内の変数を取得
set_variable_value	変数の値を変更
set_pause_on_exceptions	例外処理を設定
get_original_location	生成されたソース位置を元のソース位置に対応付け
get_script_source	スクリプトのソースコードを取得
list_scripts	読み込まれたスクリプトを一覧表示

ワークフローの例

1. --inspect-brk を指定してアプリケーションを起動します。

   node --inspect-brk=9229 app.js
   

2. WebSocket URL を取得します。

   curl http://localhost:9229/json
   

3. デバッガーに接続します。

   connect_debugger(websocket_url: "ws://localhost:9229/<id>")
   

4. ブレークポイントを設定します。

   set_breakpoint(session_id: "...", url: "file:///path/to/app.js", line_number: 10)
   

5. ブレークポイントに到達するよう実行を再開します。

   resume_execution(session_id: "...")
   

6. 一時停止中に状態を確認します。

   get_call_stack(session_id: "...")
   get_scope_variables(session_id: "...", call_frame_id: "...", scope_index: 0)
   evaluate_expression(session_id: "...", expression: "myVariable")
   

7. デバッグを続行します。

   step_over(session_id: "...")
   resume_execution(session_id: "...")
   

ソースマップのサポート

サーバーは、トランスパイルされたコード（TypeScript、バンドルされた JavaScript など）のソースマップを自動的に読み込みます。ソースマップが利用可能な場合は、次の操作ができます。

• コールスタックに元のソース位置が表示されます
• 元のソースファイルにブレークポイントを設定できます
• get_original_location で、生成された位置を元のソース位置に対応付けます
• get_script_source で、元のソースの内容を返せます

開発

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Watch mode for development
npm run dev

アーキテクチャ

• cdp-client.ts - 低レベルの Chrome DevTools Protocol クライアントラッパー
• session-manager.ts - 複数のデバッグセッションを管理
• source-map-manager.ts - ソースマップの読み込みと位置のマッピングを処理
• server.ts - ツールハンドラーを備えた MCP サーバーの実装
• types.ts - TypeScript の型定義

要件

• Node.js 18.0.0 以降
• CDP 互換のデバッグ対象（Node.js、Chrome、Edge など）

ライセンス

Apache-2.0