mcp-debugger について
mcp-debuggerは、AIエージェントが構造化された呼び出しで実行中のプログラムをデバッグできる、ヘッドレスMCPサーバーです。10言語に対応し、IDEのない環境からのリモート接続も可能です。
主な機能
- 0110言語でのステップ実行
- 02ブレークポイントの設定と管理
- 03変数の確認と式の評価
- 04リモートまたはプロセスIDで接続
- 05プログラム出力をMCPリソース化
- 06結果内の機密情報を標準でマスキング
活用シーン
- 01CIで失敗したテストのデバッグ
- 02コンテナやKubernetes上のサービス調査
- 03エージェントからリモートプロセスへ接続
- 04クラッシュ状態と変数の確認
MCP 対応
デバッグ操作をMCPツールとして公開し、プログラムの記録を購読可能なMCPリソースとして提供します。stdioとStreamable HTTPに対応し、接続手順とdebugging-workflowプロンプトも備えています。
設定
ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。
ツール
28掲載時のツール一覧 · 2 週間前に更新
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
| host | string | いいえ | リモートデバッグで接続するホスト（任意。指定するとアタッチモードになります） |
| name | string | いいえ | 任意のセッション名 |
| port | number | いいえ | リモートデバッグで接続するデバッグポート（任意。指定するとアタッチモードになります） |
| timeout | number | いいえ | アタッチモードでの接続タイムアウト（ミリ秒、デフォルト：30000） |
| language | enum | はい | デバッグするプログラミング言語javascript | python | mock | ruby | go | rust | java | dotnet | cpp | cobol |
| stopOnEntry | boolean | いいえ | アタッチモードのみ：attach_to_process.stopOnEntry と同じです。省略すると true になり、アタッチ後にターゲットが一時停止します（遅れて一時停止し、pending:true と報告される場合があります）。false を渡すと、実行中のサービスを停止せずにアタッチします |
| adapterConfig | object | いいえ | アタッチモードのみ：アタッチ設定に統合されるアダプター固有のアタッチ設定（attach_to_process を参照） |
| verifyTimeout | number | いいえ | アタッチモードのみ：アタッチ後、デバッガーが少なくとも 1 つのスレッドを報告するまで待機する時間（ミリ秒）。時間切れの場合、アタッチは失敗します（デフォルト：20000、最大：600000） |
| executablePath | string | いいえ | 言語実行ファイルのパス（任意。指定しない場合は自動検出されます） |
詳細
mcp-debugger
MCP を介したヘッドレスなエージェント型デバッガー — AI エージェントが 10 言語の実行中プログラムをデバッグできます。
🎯 概要
mcp-debugger は、ステップ実行デバッグを構造化されたツール呼び出しとして公開する Model Context Protocol（MCP）サーバーです。AI エージェントは、ブレークポイントの設定、変数の調査、式の評価、実行中プログラムのステップ実行を 10 言語で行えます。Debug Adapter Protocol（DAP）を通じて、実際の言語デバッガーを操作します。
IDE は必要ありません。 mcp-debugger は Node.js が動作するあらゆる場所で実行できます。CI ランナー、Docker コンテナー、Kubernetes ポッド、SSH サーバー、そしてクラウドのコーディングエージェントが稼働するサンドボックスでも使えます。IDE では手が届かない場所で使えるデバッガーです。
mcp-debugger と IDE に結び付いたデバッグサーバーの使い分け
Microsoft の DebugMCP は、VS Code のデバッガーを MCP 経由で公開します。エージェントが実行中の VS Code 内で動作する場合に適しています。2 つのプロジェクトでは、構造上のトレードオフが異なります。
| mcp-debugger | microsoft/DebugMCP | |
|---|---|---|
| ヘッドレスで実行（CI、コンテナー、k8s、クラウドエージェント） | ✅ スタンドアロンの Node プロセス | ❌ 実行中の VS Code が必要 |
| トランスポート | stdio + Streamable HTTP | Streamable HTTP（localhost） |
| 配布方法 | npx、npm、Docker イメージ | VS Code Marketplace 拡張機能 |
| IDE なしでのリモートアタッチ | ✅ debugpy / rdbg / JDWP、ポートフォワード経由のポッドを含む | ❌ |
| セッションごとのプロセス分離 | ✅ セッションごとに 1 つのプロキシプロセス | VS Code インスタンスを共有 |
Java のホットスワップと Flutter のホットリロード（hot_reload） | ✅ | ❌ |
| 購読可能な MCP リソースとしてのデバッグ対象出力 | ✅ | ❌ |
| エージェントと並行して使う IDE 内デバッグ UX | ✅ 読み取り専用の IDE ミラー（expose_session） — IDE はエージェントのライブセッションに参加します | ✅ ネイティブ |
| 一時停止せずに使えるログポイント（本番環境でも安全な値の監視） | ✅ logMessage ブレークポイント | ✅ VS Code 経由 |
コンテンツ／関数アドレス指定のブレークポイント（statement:、function:、expectedContent） | ✅ 編集後も有効なエージェントネイティブのアドレス指定 | — |
| シークレットのデフォルトでのマスキング | ✅ 変数／評価結果／出力のマスキング + 最小権限モード | — |
| Kubernetes の一時デバッグサイドカー（ネイティブな PID 指定アタッチ） | ✅ kubectl debug のフロー | ❌ |
| C/C++ | ✅ CodeLLDB 経由（起動 + PID 指定アタッチ） | ✅ VS Code 拡張機能経由 |
| COBOL | ✅ GnuCOBOL + CodeLLDB 経由（起動 + PID 指定アタッチ、COBOL に合わせた変数表示） | — |
| Dart/Flutter | ✅ SDK 独自のデバッグアダプター経由（起動 + VM サービス URI によるアタッチ。現在は Dart に対応し、Flutter ランナーは次のマイルストーンで組み込み、提供予定です） | — |
| PHP | ❌ | ✅ VS Code 拡張機能経由 |
| 言語 | Python、JS/TS、Ruby、Rust、Go、Java、.NET、C/C++、COBOL、Dart/Flutter | Python、JS/TS、Ruby、Rust、Go、Java、.NET、C/C++、PHP |
エージェントがターミナル、パイプライン、クラウドサンドボックスで動作する場合、または別のマシン上のプロセスへのアタッチが必要な場合は、mcp-debugger が適しています。
🆕 v0.25.0 — COBOL デバッグに対応しました（GnuCOBOL + CodeLLDB、COBOL に合わせた変数表示、PERFORM を考慮したステップ実行、段落ブレークポイント）。また、CodeLLDB がプラットフォームごとのパッケージとして提供されるようになり、npm がインストールするすべてのプラットフォームで Rust と C/C++ がすぐに動作します。さらに、
mcp-debugger doctor、Kubernetes のデバッグ手順、Host/Origin チェックで127.0.0.1に固定された HTTP トランスポート、実行終了時の状況を示す起動応答、Go と Docker JavaScript の終了コード、より軽量な起動も新たに追加されました。リリース履歴の全容は変更履歴をご覧ください。
✨ 主な機能
- 🌐 多言語サポート – どの言語にも対応できるクリーンなアダプターパターン
- 🐍 debugpy による Python デバッグ – DAP プロトコルを完全にサポート
- 💎 rdbg による Ruby デバッグ – コンテナや Kubernetes Pod へのリモートアタッチを含む、起動およびアタッチのワークフロー
- 🟨 js-debug による JavaScript（Node.js）デバッグ – VSCode の実績あるデバッガー
- 🦀 CodeLLDB による Rust デバッグ – Rust および Cargo プロジェクトをデバッグ（Linux/macOS 対応。Windows では GNU ツールチェーンが必要です。Windows での Rustを参照してください）
- 🐹 Delve による Go デバッグ – Go プログラムの DAP を完全にサポート
- ☕ JDI ブリッジによる Java デバッグ – JDK 21 以降で起動モードとアタッチモードに対応
- 🔷 netcoredbg による .NET/C# デバッグ – DAP を完全にサポートし、.NET アプリケーションをデバッグ
- ⚙️ CodeLLDB による C/C++ デバッグ – ビルド済みバイナリまたは単独のソースファイル（自動コンパイル）を起動し、PID でアタッチできます。コアダンプと gdbserver/rr ターゲットは設定のパススルーで対応します
- 🧮 GnuCOBOL + CodeLLDB による COBOL デバッグ –
.cob/.cblソース（cobcで自動コンパイル）またはビルド済み実行ファイルを起動し、PID でアタッチできます。WORKING-STORAGE / LOCAL-STORAGE / LINKAGE スコープに対応し、DISPLAY、COMP、COMP-3、88 レベルの値をデコードします。コピーブック内のブレークポイント、文単位のステップ実行、libcob ランタイムエラー（S0C7/SSRANGE 相当）発生時の一時停止に対応しており、メインフレームから GnuCOBOL への移行向けに設計されています（ガイド） - 🐦 SDK 独自のデバッグアダプターによる Dart/Flutter デバッグ – Dart プログラムと
package:testファイル（dart debug_adapter）、または Flutter アプリとテスト（flutter debug-adapter）を起動します。pubspec.yamlとプログラムパスからランナーを自動検出します。サービス URI またはサービス情報ファイルを指定して実行中の VM にアタッチできます。条件付きブレークポイント、ログポイント、Unhandled/All例外フィルター、noDebugに対応しています。依存物の同梱はありません。マシン上の Dart または Flutter SDK がデバッガーです。現在は Dart に対応しています。Flutter ランナーは接続済みで、スパイク開発で Windows デスクトップと Android エミュレーターを使って検証済みであり、次のマイルストーンでリリース予定です（ガイド） - 🧪 テスト用モックアダプター – 外部依存なしでテストできます
- 🛰️ IDE 外からのアタッチとリモートアタッチ – ホスト/ポート経由で、別のマシン上またはコンテナ内のプロセスにアタッチできます（Python は debugpy、Ruby は rdbg、JavaScript は V8 インスペクター、Java は JDWP、Dart/Flutter は VM サービス URI を使用）。ソースパスマッピングにも対応しています。また、ネイティブコード（C/C++、COBOL）やローカルの Node.js プロセスには PID でアタッチできます。ローカルの Node.js プロセスでは、mcp-debugger がインスペクターを開きます（JavaScript）。Python と Ruby のアタッチは 直接接続 方式です。デバッグエンジンはすでにターゲット内で実行されているため、ローカルに Python や Ruby は必要ありません。JavaScript、Java、.NET、C/C++、COBOL、Dart/Flutter は代わりにローカルアダプターを起動します。そのうち、インストールするツールチェーンが必要なのは Java（JDK）、.NET（netcoredbg）、Dart/Flutter（SDK 独自のデバッグアダプターを使用）のみです。JavaScript、C/C++、COBOL のデバッグエンジンはパッケージに同梱されています。
list_supported_languagesは、モードごとの対応状況を理由とともに報告します - 🎯 編集後も維持されるブレークポイント – 内容で指定（
statement: "total = sum(prices)"）、シンボルで指定（function: "main"）、またはexpectedContentで行の内容を検証できます。アンカーはrestart_debugging後も再解決され、あいまいな一致は明確に警告されます - 🪵 ログポイント –
logMessage: "x={x}"を指定してset_breakpointを実行すると、一時停止せずに補間した値をget_outputにストリーミングします。ホットパスの値を安全に監視できます - 🧰 ブレークポイントのライフサイクルを完全にサポート – 実行中でも
list_breakpoints/remove_breakpoint/clear_breakpointsを使用できます。restart_debuggingは同じ設定で再起動し、すべてを 1 回の呼び出しで再適用します - 📡 バッファリングされたプログラム出力 –
get_outputはデバッグ対象の stdout/stderr をカーソル付きで返します。また、各セッションは購読可能な MCP リソースとしてトランスクリプトを公開します - 💥 クラッシュ状態のデバッグがデフォルト – 起動したセッションは、捕捉されない例外が発生すると、スタックとローカル変数を確認できる状態で一時停止します（
breakOnExceptions。例外クラス/メッセージはlastStopに表示されます） - 🪞 読み取り専用 IDE ミラー –
expose_sessionは、ループバック接続でトークン認証された DAP エンドポイントを開き、人間が使う IDE からエージェントの実行中セッションを操作せずに確認できるようにします - ☸️ Kubernetes デバッグ – インタープリター型ランタイムにはポートフォワード経由でアタッチし、ネイティブプロセスには
kubectl debug --targetと PID によるアタッチを使用します（手順、すぐに使えるマニフェスト） - 🔌 STDIO および Streamable HTTP トランスポート – すべての MCP クライアントで利用できます（従来の SSE トランスポートは非推奨です）
- 📦 ランタイム依存ゼロ – esbuild + tsup による自己完結型バンドル
- ⚡ npx ですぐに実行 –
npx @debugmcp/mcp-debuggerで直接実行でき、インストールは不要です - 🐳 Docker および npm パッケージ – どこにでもデプロイできます
- 🤖 AI エージェント向けに設計 – 解析しやすい構造化 JSON 応答
- 🔒 シークレットのマスキングがデフォルトで有効 – 認証情報とみられる値（API キー、トークン、秘密鍵）は、エージェントに届く前に、変数、評価、出力の結果でラベル付きのプレースホルダーに置き換えられます（詳細。
DEBUG_MCP_NO_REDACT=1で無効化できます） - 🛡️ パス検証 – 存在しないファイルによるクラッシュを防ぎます
- 📝 AI を考慮した行コンテキスト – コードのコンテキストに基づいてブレークポイントをインテリジェントに配置します
- ✅ 包括的なテストスイート – すべてのアダプターを対象とする単体テスト、統合テスト、エンドツーエンドテストを網羅しています（CI のステータス）
🧠 エージェントスキル
ツールはエージェントに「何ができるか」を伝え、スキルは「適切にデバッグする方法」を教えます。このリポジトリには、セッションのゴールデンパス、根本原因を突き止めるための規律（1 行ずつステップ実行するより二分探索）、アタッチ／リモート接続の手順、言語ごとの注意点を網羅したエージェントスキルが含まれています。
# Claude Code (user-level)
cp -r skills/debugging ~/.claude/skills/mcp-debugger
# Cross-agent directories (Copilot CLI and friends)
cp -r skills/debugging ~/.agents/skills/mcp-debugger
サーバーは、接続時の MCP instructions に加え、任意の MCP クライアントがリクエストできる debugging-workflow プロンプトとして、要約されたガイダンスも提供します。詳しくはskills/debugging/README.mdをご覧ください。
🎬 動作を見る
- 失敗した CI テストを自動デバッグ – テスト失敗時に mcp-debugger とエージェントを起動し、根本原因の分析結果を投稿する複合 GitHub Action
- 不調な Pod のウォークスルー – ポートフォワードを介して Kubernetes 上の問題が発生している Python サービスにアタッチします（チュートリアル）
- ネイティブの不調な Pod – コンパイル済みコードでも同じ手順で対応します。一時的なデバッグサイドカーと PID によるアタッチを使用し、プロセス内エージェントは不要です
🚀 クイックスタート
要件： サーバーには Node.js 22 以降が必要です。デバッグする各言語についても、それぞれのツールチェーンをインストールする必要があります（Python と debugpy、Ruby と
debuggem／rdbg、Node.js、Go と Delve、JDK 21 以降、.NET SDK、Rust ツールチェーン、C/C++ コンパイラー — g++／clang++（ソースファイルの起動時のみ必要）、COBOL ソースの起動には GnuCOBOL 3.1.2 以降、Dart／Flutter には Dart SDK — Flutter に同梱）。インストール済みのものがわからない場合は、npx @debugmcp/mcp-debugger doctorを実行すると、アダプターごとのツールチェーンのレポートを確認できます。CodeLLDB のプラットフォームに関する注意（npx／npm でのインストール）： CodeLLDB デバッグエンジンは、プラットフォームごとのオプション依存関係（
@debugmcp/codelldb-win32-x64、-darwin-x64、-darwin-arm64、-linux-x64、-linux-arm64）として提供されます。npm はお使いのプラットフォームに一致するものだけをインストールするため、npm が対応するすべての環境で Rust および C/C++ のデバッグをすぐに利用できます。--omit=optionalを指定してインストールする場合は、代わりに CodeLLDB のリリースのバイナリーをCODELLDB_PATHに設定するか、Docker イメージを使用してください。
MCP クライアント向け（Claude Desktop など）
MCP 設定に以下を追加してください。
{
"mcpServers": {
"mcp-debugger": {
"command": "node",
"args": ["C:/path/to/mcp-debugger/dist/index.js", "stdio", "--log-level", "debug", "--log-file", "C:/path/to/logs/debug-mcp-server.log"],
"disabled": false,
"autoApprove": ["create_debug_session", "set_breakpoint", "get_variables"]
}
}
}
Codex CLI、デスクトップ、IDE 向け
公開されている stdio サーバーを Codex CLI に登録します。
codex mcp add mcp-debugger -- npx -y @debugmcp/mcp-debugger stdio
codex mcp list
Codex はこの設定を ~/.codex/config.toml に保存します。同じ Codex ホスト上で実行している場合、ChatGPT デスクトップアプリ、Codex CLI、Codex IDE 拡張機能はこの設定を共有します。アクティブなデスクトップクライアントまたは IDE 拡張機能を再起動するか、新しい CLI セッションを開始してから、/mcp を使って mcp-debugger が接続されていることを確認してください。設定やトラブルシューティングについて詳しくは、公式の Codex MCP ドキュメントをご覧ください。
mcp-debugger 自体を開発していますか？ 公開パッケージではなく、再起動可能なソース開発プロキシを使用してください。
Claude Code CLI 向け
Claude Code ユーザー向けに、自動インストールスクリプトを用意しています。
前提条件： インストールスクリプトを実行する前に、Claude CLI をインストールし、PATH から利用できる状態にしておく必要があります。インストール方法については、Claude Code のドキュメントをご覧ください。
# Clone the repository
git clone https://github.com/debugmcp/mcp-debugger.git
cd mcp-debugger
# Run the installation script
./scripts/install-claude-mcp.sh
# Verify the connection (use 'claude mcp list' if claude is on your PATH)
claude mcp list
重要： コンソール出力によって JSON-RPC プロトコルが破損するのを防ぐため、stdio 引数が必要です。設定とトラブルシューティングの詳細については、CLAUDE.mdをご覧ください。
pi コーディングエージェント向け
pi 0.99 以降には、MCP サポートが組み込まれています。公開されている @debugmcp/mcp-debugger パッケージも pi パッケージです。インストールすると、mcp-debugger エージェントスキルと、サーバーを pi の MCP サポートに登録する拡張機能の両方が追加されます。
pi install npm:@debugmcp/mcp-debugger # the mcp-debugger skill, and the server via pi's built-in MCP
pi list # shows the package
この拡張機能は、pi install がディスクに配置した CLI を実行するため、サーバーはスキルと一致し、npx によるダウンロードなしで起動します。公開設定は deferred で登録されます。pi はシステムプロンプトにデバッガーを表示し、モデルは tool_search を使って必要なツールを読み込みます。ツール名は mcp__mcp_debugger__<tool> です。/mcp にはサーバーが表示され、セッション中の公開設定を変更できます。~/.pi/agent/mcp.json に mcp-debugger エントリーがある場合、登録設定が置き換えられます。たとえば、開発プロキシ経由でソースビルドをデバッグする場合に使用できます。
スキルを含めず、サーバーのみ追加するには、pi mcp add mcp-debugger -- npx -y @debugmcp/mcp-debugger stdio を実行します。
pi 0.99 より前のバージョンには MCP サポートが組み込まれていないため、この拡張機能は何も行いません。pi をアップグレードしてください。
Docker の使用
docker run -i --rm -v $(pwd):/workspace debugmcp/mcp-debugger:latest
Docker イメージは、Python、JavaScript、Java、Rust、C/C++、COBOL、Dart をネイティブにデバッグできます（ツールチェーン（GnuCOBOL と Dart SDK を含む）と、共有のベンダー版 CodeLLDB を搭載）。さらに、モックアダプターにも対応しています。Flutter はホストのみで使用できます。イメージには Flutter SDK が含まれていません。イメージ内で Ruby がサポートされるのはアタッチのみです（アダプターには Ruby ランタイムが含まれていません。ローカルまたはリモートの任意の
rdbg --openプロセスにアタッチしてください）。コンテナー内で無効になっているのは Go と .NET のみです。これらは、ローカルのツールチェーンの隣で npm/npx 経由で実行してください。コンテナー内でデバッグするホストビルドの Rust/C++ バイナリには、/workspaceへのソースマップが自動導出されます。list_supported_languagesはモードごとの利用可否（modes.launch/modes.attach）とその理由を返します。Docker のサポートを参照してください。
npm の使用
npm install -g @debugmcp/mcp-debugger
mcp-debugger --help
または、npx を使ってインストールせずに使用します。
npx @debugmcp/mcp-debugger --help
ネットワーク経由（Streamable HTTP）
stdio がデフォルトであり、ほとんどのクライアントで使用します。サーバーを別の場所（CI ランナー、コンテナー、Kubernetes ポッドなど）で実行する必要がある場合は、代わりにポートを指定して起動します。
mcp-debugger http --port 3001 # or: node dist/index.js http -p 3001
そして、クライアントの接続先を指定します。
{
"mcpServers": {
"mcp-debugger": {
"type": "http",
"url": "http://127.0.0.1:3001/mcp"
}
}
}
HTTP クライアントごとに、分離されたサーバーが割り当てられます。デバッグセッションが別のクライアントから見えることはありません。DELETE /mcp を実行せずに切断したクライアントのデバッグセッションと、一時停止中のアタッチ先は、サーバーが削除するまで残ります。SSE ストリームが切断されてから 2 分後（MCP_HTTP_STREAM_LOST_SESSION_MS）、またはストリームを一度も開いていない場合は、アイドル状態になってから 30 分後（MCP_HTTP_STALE_SESSION_MS）に削除されます。GET /health には、各セッションが保持しているものが一覧表示されます。
ポートのデフォルトは 3001 で、サーバーは 127.0.0.1 のみで待ち受けます。--bind 0.0.0.0（または MCP_HTTP_BIND=0.0.0.0）を指定すると、すべてのインターフェースで待ち受けます。この場合は、ほかのマシンから使用する名前を --allowed-host で指定してください。--bind localhost は 127.0.0.1 を意味し、指定できるのは IP アドレスのみです。同じポートの GET /health は、生存確認に応答し、listening の下にバインドされたアドレスとポートを報告します。従来の sse サブコマンドも引き続き存在しますが、非推奨です。http を使用してください。
プロセスを起動したり PID にアタッチしたりできる認証なしのエンドポイントで DNS リバインディングを防ぐため、デフォルトではループバックの Host ヘッダー（localhost、127.0.0.1、[::1]）のみを受け付けます。別のマシン上のクライアントは、ポートフォワードまたは SSH トンネル（ssh -L 3001:127.0.0.1:3001 user@server を実行し、その後 http://127.0.0.1:3001/mcp に接続）経由で接続するか、--bind でインターフェースをバインドしてください。それ以外の Host には、その理由を示す 403 が返されます。サービス名を直接指定して接続する（コンテナーネットワーク上の http://mcp-debugger:3001/mcp など）には、--allowed-host mcp-debugger（複数指定可）または MCP_HTTP_ALLOWED_HOSTS=mcp-debugger（カンマ区切り）を指定してサーバーを起動します。このオプトインを使用する場合は、サーバーの前段に別のアクセス制御を設けてください。ワイルドカードは使用できません。ブラウザークライアントも同じリストに基づいて Origin がチェックされるため、クロスサイトのページからデバッガーを操作することはできません。非推奨の sse サブコマンドにも同じ許可リストが適用され、同じフラグを使用できます。
📚 仕組み
mcp-debugger は、構造化された JSON パラメーターで呼び出せるデバッグ操作を MCP ツールとして公開します。
// Tool: create_debug_session
// Request:
{
"language": "python", // or "ruby", "javascript", "rust", "go", "java", "dotnet", "cpp", "cobol", "dart", or "mock" for testing
"name": "My Debug Session"
}
// Response:
{
"success": true,
"sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
"message": "Created python debug session: My Debug Session"
}
🛠️ 利用可能なツール
以下の 29 個のツールはすべて実装済みです。パラメーターとレスポンスの形式については、ツールリファレンスをご覧ください。
| ツール | 説明 | ステータス |
|---|---|---|
create_debug_session | 新しいデバッグセッションを作成します | ✅ 実装済み |
list_debug_sessions | すべてのアクティブなセッションを一覧表示します | ✅ 実装済み |
list_supported_languages | 利用可能な言語アダプターを表示します | ✅ 実装済み |
set_breakpoint | ファイルにブレークポイントを設定します | ✅ 実装済み |
list_breakpoints | 検証済みの状態とともに、セッションのブレークポイントを一覧表示します | ✅ 実装済み |
remove_breakpoint | ID またはファイルと行番号を指定してブレークポイントを削除します | ✅ 実装済み |
clear_breakpoints | すべてのブレークポイントを削除します（ファイル単位での指定も可能です） | ✅ 実装済み |
start_debugging | スクリプトのデバッグを開始します。1 回の呼び出しで失敗したテストをデバッグすることもできます（testRunner: "pytest"） | ✅ 実装済み |
restart_debugging | 同じ設定で再起動し、ブレークポイントを再適用します | ✅ 実装済み |
attach_to_process | 実行中のプロセスにデバッガーをアタッチします | ✅ 実装済み |
detach_from_process | プロセスからデバッガーをデタッチします | ✅ 実装済み |
expose_session | IDE が接続して調査できるよう、読み取り専用の DAP ミラーエンドポイントを開きます | ✅ 実装済み |
unexpose_session | ミラーエンドポイントを閉じ、IDE クライアントを切断します | ✅ 実装済み |
get_stack_trace | 現在のスタックトレースを取得します | ✅ 実装済み |
list_threads | デバッグセッション内のすべてのスレッドを一覧表示します | ✅ 実装済み |
get_scopes | フレームの変数スコープを取得します | ✅ 実装済み |
get_variables | スコープ内の変数を取得します | ✅ 実装済み |
get_local_variables | 現在のフレームのローカル変数を取得します | ✅ 実装済み |
step_over | 現在の行をステップオーバーします | ✅ 実装済み |
step_into | 関数の中にステップインします | ✅ 実装済み |
step_out | 関数からステップアウトします | ✅ 実装済み |
continue_execution | 実行を続行します | ✅ 実装済み |
wait_for_stop | セッションが次に一時停止するか終了するまで待機します | ✅ 実装済み |
pause_execution | 実行中の処理を一時停止します | ✅ 実装済み |
evaluate_expression | デバッグコンテキストで式を評価します | ✅ 実装済み |
get_source_context | ソースコードのコンテキストを取得します | ✅ 実装済み |
get_output | キャプチャされたデバッグ対象の出力（stdout/stderr）を読み取ります | ✅ 実装済み |
close_debug_session | セッションを終了します | ✅ 実装済み |
hot_reload | 変更されたコードを実行中のプログラムに適用し、その状態を維持します。Flutter のホットリロードや Java クラスの再定義に対応します（redefine_classes は非推奨のエイリアスです） | ✅ 実装済み |
🏗️ アーキテクチャ：動的アダプター読み込み
バージョン 0.10.0 では、言語に依存しないコア機能と、言語固有の実装を分離する、すっきりとしたアダプターパターンが導入されました。
┌─────────────┐ ┌────────────────┐ ┌──────────────┐ ┌─────────────────┐
│ MCP Client │────▶│ DebugMcpServer │────▶│SessionManager│────▶│ AdapterRegistry │
└─────────────┘ └────────────────┘ └──────────────┘ └─────────────────┘
│ │
▼ ▼
┌──────────────┐ ┌─────────────────┐
│ ProxyManager │◀─────│ Language Adapter│
└──────────────┘ └─────────────────┘
│
┌───────────┬───────────┬───────────┼───────────┬───────────┬───────────┬───────────┬───────────┬───────────┬───────────┐
│ │ │ │ │ │ │ │ │ │ │
┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐
│Python ││Ruby ││JavaScript││Rust ││Go ││Java ││.NET ││C/C++ ││COBOL ││Dart ││Mock │
│Adapter ││Adapter ││Adapter ││Adapter ││Adapter ││Adapter ││Adapter ││Adapter ││Adapter ││Adapter ││Adapter │
└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘
言語サポートの追加
お好みの言語にデバッグサポートを追加したい場合は、アダプター開発ガイドをご覧ください。
💡 例：Python コードのデバッグ
以下は、デバッグセッションの完全な例です。
# buggy_swap.py
def swap_variables(a, b):
a = b # Bug: loses original value of 'a'
b = a # Bug: 'b' gets the new value of 'a'
return a, b
ステップ 1：デバッグセッションを作成する
// Tool: create_debug_session
// Request:
{
"language": "python",
"name": "Swap Bug Investigation"
}
// Response:
{
"success": true,
"sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
"message": "Created python debug session: Swap Bug Investigation"
}
ステップ 2：ブレークポイントを設定する
// Tool: set_breakpoint
// Request:
{
"sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
"file": "C:\\path\\to\\buggy_swap.py",
"line": 2
}
// Response:
{
"success": true,
"breakpointId": "28e06119-619e-43c0-b029-339cec2615df",
"file": "C:\\path\\to\\buggy_swap.py",
"line": 2,
"verified": false,
"message": "Breakpoint set at C:\\path\\to\\buggy_swap.py:2"
}
ステップ 3：デバッグを開始する
// Tool: start_debugging
// Request:
{
"sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
"scriptPath": "C:\\path\\to\\buggy_swap.py"
}
// Response:
{
"success": true,
"state": "paused",
"message": "Debugging started for C:\\path\\to\\buggy_swap.py. Current state: paused",
"data": {
"message": "Debugging started for C:\\path\\to\\buggy_swap.py. Current state: paused",
"reason": "breakpoint"
}
}
ステップ 4：変数を調べる
まず、スコープを取得します。
// Tool: get_scopes
// Request:
{
"sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
"frameId": 3
}
// Response:
{
"success": true,
"scopes": [
{
"name": "Locals",
"variablesReference": 5,
"expensive": false,
"presentationHint": "locals",
"source": {}
},
{
"name": "Globals",
"variablesReference": 6,
"expensive": false,
"source": {}
}
]
}
次に、ローカル変数を取得します。
// Tool: get_variables
// Request:
{
"sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
"scope": 5
}
// Response:
{
"success": true,
"variables": [
{"name": "a", "value": "10", "type": "int", "variablesReference": 0, "expandable": false},
{"name": "b", "value": "20", "type": "int", "variablesReference": 0, "expandable": false}
],
"count": 2,
"variablesReference": 5
}
📖 ドキュメント
- 🗺️ ロードマップ – 1.0 への道筋：安定性の基準、直近のテーマ、対象外の項目
- 📘 ツールリファレンス – API の完全なドキュメント
- 🚦 スタートガイド – 初回セットアップ
- 🏗️ アーキテクチャ概要 – 多言語設計
- 🔧 アダプター開発 – 新しい言語の追加
- 🔌 動的読み込みアーキテクチャ – 実行時の検出、遅延読み込み、キャッシュ
- 🧩 アダプター API リファレンス – アダプター、ファクトリー、ローダー、レジストリーの仕様
- 🔄 変更履歴 – リリース履歴とアップグレードに関する注意事項
- 🐍 Python デバッグガイド – Python 固有の機能
- 💎 Ruby デバッグガイド – リモート接続を含む、
rdbgを使った Ruby のデバッグ - 🔬 ケーススタディ：届かなかった initialize 応答 – mcp-debugger 自身をデバッグして、Ruby の起動停止の根本原因を特定
- 🔬 ケーススタディ：デバッガー自身へのアタッチ – 独自の
evaluate_expressionを使って実行中の mcp-debugger にライブパッチを適用し、strace では確認できなかった競合状態を捕捉 - 🔬 ケーススタディ：常に成功していた一時停止 – js-debug 自身の CDP トレースを読み解き、アイドル状態のサーバーでスマートステッパーがユーザーの一時停止を無視していた原因を捕捉
- 🔬 ケーススタディ：ソケット名を特定できなかったトレース – 診断機能自体を測定・修正・再測定：1 回のスクリプト化されたアタッチ実行を修正の前後で比較し、受け入れテストとして使用
- 🟨 JavaScript デバッグガイド – JavaScript/TypeScript の機能
- 🐹 Go デバッグガイド – Delve を使った Go のデバッグ
- ☕ Java デバッグガイド – JDI ブリッジを使った Java のデバッグ
- 🔷 .NET デバッグガイド – netcoredbg を使った .NET/C# のデバッグ
- ⚙️ C/C++ デバッグガイド – CodeLLDB による起動、自動コンパイル、PID 指定のアタッチ、コアダンプ、リモートスタブ
- 🧮 COBOL デバッグガイド – GnuCOBOL + CodeLLDB：自動コンパイル、COBOL 形式の変数、実行時エラーでの停止、メインフレーム移行の手順
- 🐦 Dart/Flutter デバッグガイド – SDK 独自のデバッグアダプター：ランナーの選択、
dart test/flutter test、VM サービス URI によるアタッチ、Flutter デバイス - 🦀 Rust デバッグガイド – CodeLLDB のセットアップ（Windows 固有の情報）
- 🐳 Docker サポート – コンテナー内の言語、アタッチモード、ホストバイナリーのソースマッピング
- ☸️ Kubernetes デバッグ – すぐに使えるアタッチ手順：レジストリー不要のマニフェスト、言語ごとのプリセット、一時的なデバッグサイドカー
- 🚑 JIT 診断チュートリアル – Kubernetes 上のライブサービスをデバッグします。コンパイル済みコード向けの一時的なサイドカーの手順も含みます
- 🤖 エージェントのデバッグガイド – AI エージェント向けの適切なツール使用パターン
- ⚠️ 既知の問題 – 現在の注意事項と回避策
- 🩺 診断 –
mcp-debugger doctor、言語ごとの前提条件、障害の兆候、環境変数リファレンス - 🔧 トラブルシューティング – よくある問題と解決策
🤝 コントリビューション
コントリビューションを歓迎します！ガイドラインについては、CONTRIBUTING.md をご覧ください。
# Development setup
git clone https://github.com/debugmcp/mcp-debugger.git
cd mcp-debugger
# Install dependencies and vendor debug adapters
pnpm install
# Vendored debug engines (Microsoft's js-debug; CodeLLDB, shared by Rust, C/C++ and COBOL)
# are downloaded automatically and verified against committed SHA-256 digest pins
# Build the project
pnpm build
# Run tests
pnpm test
# Check adapter vendoring status
pnpm vendor:status
# Force re-vendor all adapters (if needed)
pnpm vendor:force
デバッグアダプターのベンダリング
プロジェクトは pnpm install の実行時に、デバッグアダプターを自動的にベンダリングします：
- JavaScript：GitHub リリースから Microsoft の js-debug をダウンロードします
- Rust、C/C++、COBOL：現在のプラットフォーム向けに CodeLLDB の共有コピーを1つダウンロードします（
packages/codelldb-common） - 整合性：すべてのダウンロードは、各パッケージの
vendor-manifest.jsonに記載された固定済み SHA-256 ダイジェストと照合して検証されます。不一致があるとビルドは失敗します - CI 環境：ベンダリングをスキップするには
SKIP_ADAPTER_VENDOR=trueを設定します
アダプターを手動で管理するには：
# Check current vendoring status
pnpm vendor:status
# Re-vendor all adapters
pnpm vendor
# Clean and re-vendor (force)
pnpm vendor:force
# Clean vendor directories only
pnpm clean:vendor
コンテナーのテストをローカルで実行する
GitHub Actions ワークフローをローカルで実行するために、Act を使用します：
# Build the Docker image first
docker build -t mcp-debugger:local .
# Run tests with Act (use WSL2 on Windows)
act -j build-and-test --matrix os:ubuntu-latest
詳しいテスト手順については、tests/README.md を参照してください。
📊 プロジェクトのステータス
- ✅ 本番環境対応：10言語のアダプター、29個のツール、洗練された多言語配布
- ✅ 動的アダプターパターンを採用したクリーンなアーキテクチャ
- ✅ Python · Ruby · JavaScript/TypeScript · Go · Java · .NET/C#：ステップ実行デバッグに完全対応
- 🦀 Rust：Linux/macOS/Windows で完全にサポート（Windows では GNU ツールチェーンが必要です。CodeLLDB は MSVC をサポートしていません）
- ⚙️ C/C++：CodeLLDB によるステップ実行デバッグに完全対応（起動＋PID によるアタッチ。Windows では MinGW/DWARF を推奨します。MSVC PDB の忠実度は部分的です）
- 🧮 COBOL：GnuCOBOL と CodeLLDB によるステップ実行デバッグ（起動＋PID によるアタッチ。Linux および Windows/MSYS2 で GnuCOBOL 3.1.2/3.2 を検証済み。PERFORM を考慮したステップ実行、段落ブレークポイント、
{WS-NAME}ログポイントに対応） - 🐦 Dart/Flutter：SDK 独自のデバッグアダプター（
dart debug_adapter、flutter debug-adapter）によるステップ実行デバッグ（起動＋VM サービス URI によるアタッチ）。現在は Dart に対応しています。Flutter ランナーは接続済みで、スパイクでは Windows デスクトップと Android エミュレーターで計測済みです。次のマイルストーンでリリース予定です - 🟢 ランタイム：Node.js 22+
- 📈 積極的に開発中：定期的な更新と改善を行っています。1.0 までの道のりについてはロードマップをご覧ください
🏛️ メンテナンス担当者
mcp-debugger は Sycamore LLC が管理し、John Franklin（@debugmcpdev）が主導しています。このプロジェクトでは、人間が責任を担うエージェント優先の開発モデルを採用しています。コードの大部分は AI エージェントが作成し、すべてのマージ、リリース、セキュリティに関する判断は人間のメンテナーが行います。MAINTAINERS.md、GOVERNANCE.md、SUPPORT.md（商用サポートを含む）をご覧ください。
サプライチェーン対策：固定された CI アクション、OIDC による信頼された公開、すべての npm パッケージに付与される sigstore 来歴情報、リリースに添付される SBOM、そして継続的に維持している OpenSSF Scorecard スコア。詳細は SUPPLY-CHAIN-SECURITY.md をご覧ください。脆弱性は SECURITY.md に記載された方法で報告してください。
📄 ライセンス
MIT ライセンスです。詳細は LICENSE をご覧ください。
👥 コントリビューター
- @Poyraxx — Ruby アダプター（rdbg）
- @swinyx — Go アダプター（Delve）
- @roofpig95008 — Java アダプター（JDI ブリッジ）
🙏 謝辞
以下を使用して構築しています：
- Anthropic による Model Context Protocol
- Microsoft による Debug Adapter Protocol
- Python のデバッグに使用する debugpy
- Ruby のデバッグに使用する debug
あらゆる言語で、AI エージェントに本格的なデバッガーを提供しましょう。
コメント
AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。