stdio MCP 断点デバッグ (VS Code Attach + MCP Inspector + Node --inspect)

目的

ユーザーが VS Code で安定してブレークポイントにヒット させ、stdio 経由で実行される MCP Server (通常は npx @modelcontextprotocol/inspector ... で起動) をデバッグできるようにし、ポートの競合、sourcemap の欠落、ブレークポイントがグレー表示されるなどの問題が発生した場合に、明確なトラブルシューティングパスを提供すること。

Quick Start (最短用法)

すでにビルド成果物 (例: build/internal/index.js または dist/index.js) があり、stdio MCP Server にブレークポイントを設定したい場合:

• sourcemap が有効になっていることを確認 (ビルド成果物の隣に .map ファイルが表示される)
• MCP プロジェクトのルートディレクトリにある .vscode/launch.json に attach 構成を新規追加
• VS Code でこの Attach デバッグを最初に起動
• ターミナルで実行 (ポートは launch.json と一致させる):

npx -y @modelcontextprotocol/inspector node --inspect=9229 build/internal/index.js

もし「ブレークポイントに到達しない / ブレークポイントがグレー表示される」場合は、まず以下のように変更してください:

npx -y @modelcontextprotocol/inspector node --inspect-brk=9229 build/internal/index.js

原理 (わかりやすい説明)

• Node の --inspect: ローカルマシンに「デバッグポート」(デフォルトは 9229) を開き、VS Code が接続してブレークポイント/ステップ実行を制御できるようにします。
• MCP Inspector: 「一時的な MCP クライアント + UI」のようなもので、サーバーを起動し、stdio を介してサーバーと通信します。
• sourcemap: 「ビルド後の JS」を「あなたの TS ソースコード」にマッピングし、TS でブレークポイントを正確に設定できるようにします。

出力形式 (常にこのテンプレートに従ってユーザーに提供してください)

以下の 3 つの内容を出力してください (すべてコピー＆ペースト可能であること):

【1) VS Code Attach 構成 (launch.json スニペット)】
<完全な configuration オブジェクトを提供し、configurations 配列に追加するようにユーザーに促します。port/outFiles が一致する必要があることを明確にします>

【2) 起動コマンド (Inspector + Node --inspect)】
- デフォルト版: <コマンド 1 つ>
- 安定版 (最初の行で一時停止): <コマンド 1 つ>
- ポート変更版 (9229 が使用中の場合): <コマンド 1 つ>

【3) トラブルシューティングリスト (可能性の高い順に)】
1. ...
2. ...
3. ...

重要な制約 ("見た目は正しいがうまくいかない" を避ける)

• ポートは一致する必要がある: launch.json の port == --inspect=PORT の PORT。
• Attach を先に実行してからプロセスを起動: 最初の実行では --inspect-brk を使用することを推奨します。「起動が速すぎてブレークポイントを逃す」ことを避けるためです。
• ビルド成果物をデバッグする場合は sourcemap が必須: そうでない場合は、コンパイルされた JS でしかデバッグできず、TS ブレークポイントはほぼ確実に正確ではありません。

全体的な流れ (ステップバイステップで実行)

flowchart TD
  A[エントリポイントと出力ディレクトリを確認<br/>build/ dist/ 内の index.js] --> B[sourcemap が生成されていることを確認<br/>*.map が見つかること]
  B --> C[launch.json の attach 構成を追加<br/>port/outFiles を一致させる]
  C --> D[VS Code で Attach を最初に起動<br/>waiting 状態]
  D --> E[inspector コマンドを実行してサーバーを起動<br/>--inspect-brk を推奨]
  E --> F{ブレークポイントに到達?}
  F -- はい --> G[デバッグを開始: ステップ実行/変数/コールスタック]
  F -- いいえ --> H[リストに従ってトラブルシューティング: ポート/パス/outFiles/map/スペルミス]
  H --> D

ステップ 0: エントリポイントと出力ディレクトリを確認する (パスの記述ミスを避ける)

まず、「どの js ファイルを実行するのか」を明確にします:

ls -la build dist 2>/dev/null

一般的なエントリポイント:

• build/internal/index.js (注意: 多くの人が internel と記述しますが、これはスペルミスです)
• build/index.js
• dist/index.js

ステップ 1: sourcemap を有効にする ("ビルド成果物を直接デバッグする" ための前提条件)

1.1 TypeScript (tsconfig)

TS プロジェクトの場合、tsconfig.json に少なくとも以下が含まれている必要があります:

{
  "compilerOptions": {
    "sourceMap": true,
    "inlineSources": true
  }
}

1.2 パッケージャー/ビルドツール (使用しているものを選択)

核となる原則は一言: ビルド出力には .map が含まれている必要がある。

• tsup: sourcemap: true を設定
• esbuild: コマンドまたは設定に sourcemap: true (または --sourcemap) を追加
• rollup: output.sourcemap: true
• webpack: 適切な devtool を設定 (例: source-map)
• tsc 直接出力: outDir に .js.map があることを確認

自己チェック (.map が表示されるはずです):

find build dist -maxdepth 4 -name "*.map" -print 2>/dev/null | head

.map が見つからない場合は、すぐにブレークポイントを設定せずに、sourcemap を有効にして再構築してください。

ステップ 2: .vscode/launch.json に attach 構成を新規追加する (最も重要)

MCP プロジェクトのルートディレクトリにある .vscode/launch.json を新規作成/修正し、以下のコードを 新しい構成として 追加します (既存の構成を上書きしないでください)。

通常、変更する必要があるのは 2 箇所のみです:

• port: 使用するデバッグポート (デフォルトは 9229)
• outFiles: 出力ディレクトリが build/ と dist/ のどちらであるか

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach: MCP stdio (Node Inspector)",
      "type": "node",
      "request": "attach",
      "port": 9229,
      "protocol": "inspector",
      "restart": true,
      "timeout": 30000,
      "sourceMaps": true,
      "smartStep": true,
      "skipFiles": ["<node_internals>/**", "**/node_modules/**"],
      "cwd": "${workspaceFolder}",
      "outFiles": [
        "${workspaceFolder}/build/**/*.js",
        "${workspaceFolder}/dist/**/*.js"
      ]
    }
  ]
}

ステップ 3: VS Code で Attach デバッグを起動する

• Run and Debug パネルを開く
• Attach: MCP stdio (Node Inspector) を選択
• 実行をクリック (または F5 を押す)

この時点で、VS Code は「接続待ち」状態になります。

ステップ 4: Inspector コマンドを実行してサーバーを起動する (stdio モード)

4.1 最も一般的 (推奨)

npx -y @modelcontextprotocol/inspector node --inspect=9229 build/internal/index.js

4.2 最初のデバッグでより安定 (最初にこれを使用することを推奨)

--inspect-brk を使用すると、Node は最初の行で停止し、attach が成功したことを確認してから実行を続行できます:

npx -y @modelcontextprotocol/inspector node --inspect-brk=9229 build/internal/index.js

4.3 pnpm / yarn を使用する場合

pnpm dlx @modelcontextprotocol/inspector node --inspect=9229 build/internal/index.js

yarn dlx @modelcontextprotocol/inspector node --inspect=9229 build/internal/index.js

ステップ 5: よくある問題 (この順序でトラブルシューティング)

5.1 ポートが使用中 (9229 が使用できない)

現象:

• ターミナルにポートが使用中であるというメッセージが表示される
• または VS Code の attach が失敗する/間違ったプロセスに接続される

確認 (macOS / Linux でよく使用される):

lsof -nP -iTCP:9229 -sTCP:LISTEN

対処法 (2 つから 1 つを選択):

• ポートを変更: たとえば、9230 に変更します
  • launch.json の port を 9230 に変更します
  • コマンドも --inspect=9230 (または --inspect-brk=9230) に変更します
• ポートを使用しているプロセスを終了: 終了したいプロセスであることを確認してから kill します

5.2 ブレークポイントがグレー表示される / 停止しない (最も一般的)

まず、次の 3 つのことを行います:

• --inspect-brk で最初に安定させる: プロセスを最初の行で停止させます
• .map が実際に存在することを確認: 出力ディレクトリに *.map が必要です
• outFiles が出力ディレクトリをカバーしていることを確認: たとえば、実際には build/ にある場合は、${workspaceFolder}/build/**/*.js を含める必要があります

追加のチェックポイント (1 つでも確認できれば sourcemap が有効になっています):

• ビルド成果物の .js の末尾に //# sourceMappingURL=xxx.js.map のようなものが含まれている
• VS Code の Call Stack に、圧縮された JS の山ではなく、ソースコードのパスが表示される

5.3 Inspector は起動できるが、サーバーが一瞬で終了する

考えられる原因:

• エントリファイルのパスが間違っている (build/internel/index.js vs build/internal/index.js のようなスペルミスが最も一般的)
• サーバーの起動時にエラーが発生してすぐに終了する (ターミナルの出力を確認)

まず、次の 2 つの最小限のアクションを実行します:

node -p "require('fs').existsSync('build/internal/index.js')"

node --inspect-brk=9229 build/internal/index.js

2 番目のコマンドが実行できる場合は、問題が inspector コマンドまたは渡した引数にある可能性が高くなります。

Examples (例)

例 1: 標準的なビルド成果物のデバッグ (build 出力)

npx -y @modelcontextprotocol/inspector node --inspect-brk=9229 build/internal/index.js

例 2: ポートの競合、9230 に変更

1. launch.json の port を 9230 に変更
2. コマンド:

npx -y @modelcontextprotocol/inspector node --inspect-brk=9230 build/internal/index.js

最終手段 (ビルド成果物をデバッグしたくない/できない場合)

sourcemap を一時的に処理できない (またはパッケージ化が複雑すぎる) 場合は、「開発モードでソースコードを直接実行する」方法でデバッグできます (プロジェクトでこのような起動が許可されている場合)。

たとえば、tsx を使用します:

npx -y tsx --inspect-brk=9229 src/index.ts

これは inspector を使用しません。最初に「ブレークポイント/ロジック/フロー」自体に問題がないことを確認し、後でビルド成果物の sourcemap デバッグチェーンを補完するのに適しています。