Qwen DAP MCP — C/C++ Debugger for Claude Code, Codex & Qwen

Qwen DAP MCP — Claude Code、Codex、Qwen、AI コーディングエージェント向けのネイティブデバッガー MCP

Claude Code、OpenAI Codex CLI、Qwen Code、Gemini CLI、その他のローカル MCP 対応コーディングエージェントを使用して、ネイティブの C/C++ クラッシュ、ハング、デッドロック、Windows のミニダンプ、コアダンプをデバッグできます。 Debug Adapter Protocol（DAP）と Model Context Protocol（MCP）を介して、実際の GDB、LLDB、または CodeLLDB デバッガーに接続します。

qwen-dap-mcp は、ネイティブクラッシュのデバッグ、ハング／デッドロックのトリアージ、クラッシュダンプ、差分ランタイム分析、リモートターゲット、範囲を限定した修正／検証ワークフローに対応する、ローカルの Debug Adapter Protocol（DAP）→ Model Context Protocol（MCP） ブリッジです。

Qwen Code 向けに設計されましたが、Claude Code や Codex CLI を含む、他のローカルの stdio MCP クライアントからも利用できます。AI モデルはクラウドで実行できますが、デバッガーブリッジとターゲットバイナリは、MCP プロセスを起動した環境で実行されます。

クイックスタート · 機能 · デバッガーのサポート · 安全性 · ドキュメント · コントリビュート

SLP-DEV1 によるオリジナルプロジェクトを引き継いだ、Apache-2.0 ライセンスのメンテナンス対象フォークです。 メンテナンス対象のソースは spk-c/Qwen-dap-mcp です。npm では @slp-dev1/qwen-dap-mcp を配布しています。GitHub の main は、最新の公開済み npm バージョンより先行している場合があります。フォークに関する注記と TypeScript 移行状況をご覧ください。

動作例：C++ クラッシュ → 証拠 → 検証

図はアーキテクチャ／ワークフローを示すものであり、実際の AI セッションや、作成されたデバッガーの記録ではありません。 プロジェクト独自の C++ フィクスチャで、意図的なクラッシュを実際に再現し、GDB のバックトレースを収集し、説明用の変更を一時コピー内だけに適用して、同じコマンドを再実行します：

bash scripts/demo-native-crash.sh

Linux、g++、gdb が必要です。CI でも実際のデバッガーを使ってデモを実行します。手順ごとに検証済みのデモと Claude/Codex の MCP 設定を見る。

このプロジェクトの目的

コーディングエージェントはソースを読み、パッチを提案できますが、ネイティブの障害をソースだけから確実に診断することはできません。有用な証拠は実行時に得られます。スレッドスタック、レジスター、ローカル変数、逆アセンブリー、例外の状態、モジュール、メモリ、待機状態、シンボル、クラッシュダンプなどです。

qwen-dap-mcp は、MCP 経由でこれらの証拠を利用できるようにし、生のデバッガープリミティブを基盤として、エージェント向けのワークフローを追加します。

• 証拠を優先 — ソースから推測するのではなく、実際に障害が発生しているプロセスを調べます。
• 高レベルのワークフロー — クラッシュ、ハング、差分、因果関係のトレース、進行状況の確認、ランタイムレポート、ダンプ、検証の各ツールは、デバッガーコンソールを操作する人間ではなく、エージェント向けに設計されています。
• 上限付きの自動化 — 自律的な修正・検証の状態は明示的かつシリアライズ可能で、反復回数に上限があり、元の再現手順を再確認します。
• 既定では小さな範囲 — 中核となるエージェントツールは18個で、既定で利用できます。フォレンジックワークフローと生のDAP制御は、別のオプトイン層になっています。
• 既定ではローカル — MCP サーバーはstdio経由で通信し、検証済みのリモートターゲットを明示的に設定しない限り、デバッダーアダプターはローカルで実行されます。

クイックスタート

Qwen Code

現在の公開済みnpmバージョンをインストールします。

qwen extensions install @slp-dev1/qwen-dap-mcp

または、保守されているGitHubリポジトリから最新のコードを直接インストールします（npmより新しい場合があります）。

qwen extensions install spk-c/Qwen-dap-mcp

Qwen Codeで/mcpと/skillsを実行し、qwen-dap-mcpサーバーとnative-runtime-debugスキルが検出されたことを確認します。

前提条件： Node.js 20以降と、別途インストールしたサポート対象のネイティブDAPデバッガー（CodeLLDB、LLVM lldb-dap、またはGNU GDB DAP）が必要です。このパッケージはブリッジであり、デバッガーは同梱されていません。プラットフォームのセットアップを参照してください。

Claude Code

Node.js 20以降とネイティブDAPデバッガーをインストールしたローカルのClaude Code CLIを使用します。

claude mcp add --transport stdio --scope user qwen-dap-mcp -- npx -y @slp-dev1/qwen-dap-mcp
claude mcp list

セットアップ確認、テスト用プロンプト、Windowsに関する注意事項、安全上の境界については、Claude Codeネイティブデバッグガイドを参照してください。

OpenAI Codex CLI

codex mcp add qwen-dap-mcp -- npx -y @slp-dev1/qwen-dap-mcp
codex mcp list

Codex CLIとIDEのデバッグガイドとバージョン管理されたCodex TOML設定を参照してください。

Gemini CLI、Cursor、VS Code Copilot、その他のクライアント

npx -y @slp-dev1/qwen-dap-mcpを指定するローカルのstdio MCPエントリーを使用します。これらのクライアントは設定スキーマが異なります。Gemini CLIとCursorではmcpServersを使用し、VS Codeの.vscode/mcp.jsonではserversを使用します。複数クライアントのセットアップと互換性マトリクスとテスト済みの設定例を参照してください。

クラウド実行の境界： Claude CodeまたはCodex CLIは、CLIとデバッガーをデスクトップ上で動作させたまま、クラウドAIモデルを呼び出すことがあります。ブラウザーのみで利用するClaude.ai／ChatGPTのセッションやリモートのCodexタスクからは、お使いのPCのローカルstdio MCPサーバーやWindowsプロセスに自動的にアクセスできません。リモートデバッグには、別途許可されたローカル実行環境または保護された接続が必要です。生のデバッガーポートを決して公開インターネットに公開しないでください。

その他のstdio MCPクライアント

公開済みのパッケージをnpxで実行します。

npx -y @slp-dev1/qwen-dap-mcp --help
npx -y @slp-dev1/qwen-dap-mcp --version

信頼できるローカルMCPクライアントを、次のように設定します。

{
  "mcpServers": {
    "qwen-dap-mcp": {
      "command": "npx",
      "args": ["-y", "@slp-dev1/qwen-dap-mcp"]
    }
  }
}

--helpまたは--versionを指定せずに起動すると、CLIはローカルのstdio MCPサーバーとして動作します。クライアントの設定構文は異なる場合があります。

既存のインストールを更新する

npm経由でインストールしたQwen拡張機能は、インストール済みのQwen Codeバージョンに含まれる拡張機能マネージャーを使って更新するか、上記のコマンドでパッケージを再インストールします。npxの場合は、MCPクライアントを再起動して、新たに解決されたバージョンを使用します。npmのリリースは不変です。READMEの変更がnpmjs.comに反映されるのは、GitHubのREADMEが変更されたときではなく、新しいパッケージバージョンの公開後のみです。

MCP クライアントの互換性

クライアント	ローカル MCP の設定	確認方法
Qwen Code	Qwen 拡張機能	/mcp および /skills
Claude Code	ローカル stdio claude mcp add	claude mcp list および /mcp
OpenAI Codex CLI	ローカル stdio codex mcp add	codex mcp list および /mcp
Gemini CLI	settings.json の mcpServers	gemini mcp list
Cursor	デスクトップ MCP 設定	Cursor の接続済みツール
VS Code の GitHub Copilot	.vscode/mcp.json の servers	Agent モードの MCP ツール
ブラウザーのみ／クラウドタスク	ローカル stdio に直接接続できません	独立した安全な実行経路が必要です

このプロジェクトには、Claude Code、Codex CLI、Gemini のクライアント ID を使用した、プロトコルレベルの stdio initialize と tools/list の自動スモークテストが含まれています。これらのテストで確認できるのは、共通 MCP サーバープロトコルと設定例の一貫性であり、プロプライエタリなクライアントアプリケーション内でのエンドツーエンドの完全な検証ではありません。ネイティブデバッガーの E2E チェックは別途実行されます。ビルド済みのチェックアウトから npm run test:clients を実行してください。

30 秒で試す

You: Debug why app.exe crashes with --repro

Coding agent
  ↓
qwen-dap-mcp starts a DAP debugger
  ↓
captures the native failure + project-controlled frame
  ↓
correlates stack + registers + locals + disassembly
  ↓
backtracks runtime evidence toward the likely producer
  ↓
agent applies a minimal source fix
  ↓
builds and repeats the original reproduction
  ↓
verifies whether the original crash fingerprint is gone

MCP サーバーは、デバッガーの証拠と制限付きのワークフロー状態を提供します。ソースコードの編集、ビルド、テスト、ソース管理の操作は、コーディングエージェントが通常使用する許可済みツールで行います。

できること

問題	エージェント向けの機能
ネイティブクラッシュ	停止したプロセスを診断し、プロジェクトのフレームを特定して、実行時の証拠を収集し、制限付きの修正／検証ループを実行します
ハングまたはデッドロック	状態を観察し、必要に応じて一時停止し、全スレッドのスタックを取得し、待機状態を分類して、デッドロックの可能性が高い候補を慎重に提示します
正常実行と異常実行	ASLR による生のアドレスのノイズを抑えながら、停止したセッションを意味的に比較します
疑わしい値	データブレークポイント／ウォッチポイントと制限付きの時間トレースを使って、実際の書き込み元を追跡します
実行時の因果関係	debug_causal_trace を使って、疑わしい値の消費元 → 書き込み元／生成元の制限付きチェーンを構築します
ビジーループの疑い	debug_progress_probe で実行中のターゲットを再開／一時停止してサンプルを取得し、状態の反復と、観測された実行の進行を区別します
記録／再生対象	DAP の stepBack／reverseContinue を使い、機能の対応状況に応じて debug_reverse_execution で逆方向に実行します
クラッシュ群のトリアージ	debug_runtime_report のフィンガープリントを作成し、debug_cluster_crashes でクラスタリングして、debug_regression_oracle でリグレッションの再現を分類します
子プロセス／fork シグナル	debug_child_requests で、フェイルクローズ方式のアダプターからの startDebugging リクエストを調べます。子セッションの自動起動は行いません
クラッシュダンプ	失敗したプログラムを起動せずに、Windows のミニダンプと、対応する LLDB／GDB の事後解析ターゲットを調べます
リモートネイティブターゲット	ループバック優先ポリシーに従い、検証済みの gdbserver／lldb-server gdbserver エンドポイント経由でアタッチします
複数のターゲット	DAP セッションを分離し、sessionId でリクエストを振り分けます
エージェントの安全性	デフォルトの機能範囲を高レベルに保ち、必要に応じて HOL Guard で実行可能な操作や変更を伴う DAP 操作を制限します
オブジェクトの寿命／UAF	ポインターへの書き込み、サニタイザーの証拠、逆方向ステップ実行、割り当て／解放のヒントを関連付けます
シンボルの不一致	アダプターのシンボル状態と、ローカルバイナリー／PDB の限定的な識別情報を比較します
クラッシュ群	事後解析の一括処理と、完全一致／意味的／ファミリー単位のグループ化を行います
オフラインでの引き継ぎ	ターゲットを実行したままにせず、構造化された証拠と SARIF をエクスポートします

ツールの構成

デフォルトの agent ツールセットでは、あまり必要とされないフォレンジックワークフローにコーディングモデルが費やすコンテキストと選択の負担を減らすため、18 個のコアツールを意図的に公開しています。

コアツール	目的
debug_this_crash	高レベルのネイティブクラッシュ診断と、範囲を限定した自律検証
debug_this_hang	高レベルのハング／デッドロックのトリアージ
debug_compare_runs	ベースラインと失敗した停止セッションの意味的な比較
debug_trace_value	疑わしい値の、範囲を限定した時間軸に沿ったトレース
debug_causal_trace	疑わしいランタイム状態について、コンシューマーから書き込み元までの証拠を提示
debug_progress_probe	進行なしやビジーループのトリアージに向けた、再開／一時停止サンプリング
debug_runtime_report	フィンガープリント、シンボル、サニタイザーの証拠、メモリの危険性、ABI／API 分析、仮説、ブレークポイントの計画
debug_trace_lifetime	オブジェクト／ポインターのライフタイムと書き込み元の来歴
debug_adaptive_evidence	低コスト → 中程度 → 全面的な、範囲を限定した証拠の収集
debug_diagnose_stop	現在のデバッガー停止状態を診断
debug_source_disassembly	ソースを近傍のネイティブ命令と関連付け
debug_find_writer	監視対象の値を書き込むコードで停止
debug_run_to_stop	範囲を限定した意味のある停止位置まで実行／起動
debug_open_dump	サポート対象の事後解析用ダンプ／コアのターゲットを開く
debug_snapshot	構造化されたランタイムの証拠を取得
debug_status	デバッガー／セッションの状態を確認
debug_disconnect	デバッガーセッションを正常に終了
debug_sessions	隔離されたセッションの作成、確認、削除

より詳細な調査が必要な場合は、QWEN_DAP_MCP_TOOLSET=forensics を設定してください。生の手動 DAP 操作は引き続き非表示にしたまま、次のツールを追加します。

フォレンジック専用ツール	目的
debug_reverse_execution	機能の有無を確認したうえでの reverseContinue／stepBack
debug_cluster_crashes	正規化されたクラッシュレポートをクラスタリング
debug_regression_oracle	元の再現／変更後の再現／結論が出ない再現を分類
debug_child_requests	フェイルクローズ方式の子／フォークの逆方向リクエストを確認
debug_adopt_child	QWEN_DAP_MCP_CHILD_DEBUG=1 の場合に、レビュー済みの startDebugging 子プロセスを 1 つ明示的に隔離セッションへ取り込む
debug_time_travel	範囲を限定した rr の記録／再生計画と逆方向ワークフロー
debug_thread_timeline	マルチスレッドの進行状況と、所有者を明示したロックグラフ
debug_symbol_doctor	バイナリ ID、ローカルシンボル、PDB／DWARF の不一致を診断
debug_dump_batch	クラッシュダンプ群を範囲を限定して分析
debug_crash_families	完全一致／意味的／ファミリー単位のクラッシュ比較
debug_cpp_object	読み取り専用の C++ オブジェクト／vtable の調査
debug_evidence_bundle	JSON／Markdown／SARIF 形式で証拠を引き渡す
debug_adapter_doctor	アダプターの機能、rr、セキュリティプロファイルを監査

生のスタック／スコープ／変数、手動のブレークポイント／ウォッチポイント、evaluate、メモリ読み取り、ステップ実行、またはアダプター固有の制御が意図的に必要な場合に限り、QWEN_DAP_MCP_TOOLSET=full を設定してください。docs/toolsets.md を参照してください。

デバッガーのサポート

アダプター／ターゲット	サポート対象の用途
CodeLLDB	ローカルのネイティブ起動／アタッチと Windows ミニダンプのワークフロー
LLVM lldb-dap	ネイティブ起動／アタッチ、コアファイルの調査、lldb-server gdbserver によるリモートアタッチ
GNU GDB 14+ DAP	ネイティブ起動／アタッチ、コアファイルのワークフロー、強化された gdbserver によるリモートアタッチ

アダプターの検出、前提条件、プラットフォーム固有の設定については、docs/README.md に記載されています。

生の DAP を超えて

生の DAP は意図的に低レベルです。qwen-dap-mcp は完全なツールセットで生のデバッガーアクセスを引き続き利用できるようにしつつ、デフォルトのインターフェースでは、エージェントが直接推論できるワークフローに重点を置いています。

	ソースのみ	生の DAP	qwen-dap-mcp エージェントツール
実行時デバッガーの証拠	—	✓	✓
高度なクラッシュ診断	—	—	✓
全スレッドのハング切り分け	—	手動	✓
正常版と異常版のセマンティック差分	—	手動	✓
明示的で範囲が限定された修正／検証状態	—	—	✓
検証フィンガープリントの作成	—	—	✓
因果関係に基づく書き込み元の追跡	—	手動	✓
進行状況のサンプリング／ビジーループの切り分け	—	手動	✓
サニタイザー＋シンボル＋ABI レポートの相関分析	—	手動	✓

設計による安全性

デバッガーは対象の状態を実行・変更できるため、このブリッジではその権限を明示的に扱います。

• MCP サーバーは任意のシェルツールを公開しません。
• MCP サーバーはソースを書き込む機能を公開しません。
• デフォルトのエージェントインターフェースに、汎用的なメモリ書き込み機能は含まれません。
• リモートエンドポイントは検証され、ループバック以外へのアクセスには明示的な許可リストへの登録が必要です。
• 自律ワークフローの状態は、バックグラウンドループの中に隠さず明示します。
• オプションの HOL Guard 2.2+ との統合により、保護対象のアダプター起動前、または実行可能／状態変更を伴う DAP アクションがデバッガー境界を越える前に、フェイルクローズできます。

ポリシーと脅威モデルの全文は、docs/hol-guard.md および SECURITY.md をご覧ください。

開発と再現可能な検証

このリポジトリには、ネイティブのクラッシュ、ハング、事後解析、Windows ミニダンプ、およびリモートデバッガー用のフィクスチャが含まれています。開発用チェックアウトで、次を実行します。

npm ci
npm run check
npm run check:pack

チェックには、ソース／ビルドの整合性、MCP テスト、ドキュメントの整合性、および実際の npm tarballの検査が含まれます。ネイティブアダプターのエンドツーエンドテストは専用の CI ジョブで実行され、必要なデバッガー／ツールチェーンの前提条件が必要です。統合テストとベンチマークハーネスをご覧ください。記録された再現可能な結果がない限り、パフォーマンスに関する主張は行いません。

実践的なデバッグチュートリアル

これらの目的を絞ったチュートリアルでは、実際のネイティブターゲットを使って、セットアップ、期待されるデバッガーの証拠、および制限事項を説明します。MCP ブリッジにデバッガーは同梱されていません。

• Qwen Code による C/C++ クラッシュデバッグ — ネイティブクラッシュを再現し、スタック／レジスター／ローカル変数の証拠を取得して、修正を検証します。
• CodeLLDB による Windows ミニダンプのデバッグ — クラッシュしたプロセスを再実行せずに、一致する実行ファイルとシンボルを使ってクラッシュダンプを調べます。
• GDB/LLDB MCP のセットアップとトラブルシューティング — DAP 対応アダプターをインストールし、MCP ツールを確認して、よくあるアダプターの問題を解決します。
• 再現可能なネイティブクラッシュと修正検証のデモ — 実際に所有する C++ テストフィクスチャをビルドし、GDB の SIGSEGV バックトレースを取得し、一時的なガードを適用して、同じ引数で再実行します。

MCP レジストリでの検出

メンテナンスされているパッケージは、一致する npm バージョンがあり、公式レジストリへの公開が成功した場合、MCP メタデータを io.github.spk-c/qwen-dap-mcp として公開します。これは、元の作者による過去のレジストリ掲載とは別のものです。公開とレジストリの検証を参照してください。掲載されているだけでは、該当するパッケージのバージョンが確認されるまで、特定の機能があることの証明にはなりません。

メンテナンスされているフォークを見つける： 公式 MCP レジストリ · npm · ソースとチェックサム · ディレクトリ掲載用の情報と帰属表示。

ドキュメント

まずはドキュメントのインデックスをご覧ください。

トピック	ガイド
macOS の実験的サポート	docs/macos.md
Windows での CodeLLDB	docs/CODELLDB_WINDOWS.md
LLVM lldb-dap	docs/lldb-dap.md
GNU GDB DAP	docs/gdb-dap.md
リモートデバッグ	docs/remote-debugging.md
ハング／デッドロックの分析	docs/hang-debugging.md
差分デバッグ	docs/differential-debugging.md
ランタイムデバッグ v2	docs/runtime-debugging-v2.md
エージェント用と完全なツールセット	docs/toolsets.md
HOL Guard の統合	docs/hol-guard.md
公開／リリース	docs/publishing.md

コントリビューションとソースからのビルド

要件：Node.js 20 以降。

git clone https://github.com/spk-c/Qwen-dap-mcp.git
cd qwen-dap-mcp
npm ci
npm run check

src/**/*.ts が、51 個のランタイムモジュールの信頼できるソースです。生成された JavaScript のミラーと宣言ファイルは CI でチェックされます。TypeScript の strict: true への完全な移行は完了しています（issue #24、PR #52～#56）。CI では、厳格モードのコンパイラ診断がゼロであることを必須としています。ネイティブデバッガーのサポートは、CI でテストされたアダプターとシナリオに限られます。

プルリクエストを作成する前に、CONTRIBUTING.mdをご覧ください。

配布とリリース状況

• npm： @slp-dev1/qwen-dap-mcp — 公開済みバージョンをインストールできます。GitHub の変更が含まれていると判断する前に、npm のバージョンを確認してください。
• メンテナンスされているソースと Qwen 拡張機能： spk-c/Qwen-dap-mcp — qwen extensions install spk-c/Qwen-dap-mcp。
• リリースアーカイブと変更履歴： GitHub Releases および CHANGELOG.md。
• 公開： リリースは、検証済みの main コミットに対する意図的な vX.Y.Z タグ、またはワークフローの手動実行によって開始されます。npm Trusted Publishing では、長期有効な npm 公開トークンを使わず、GitHub Actions の OIDC を使用します。

npm の掲載内容は、公開された tarball 内の README から更新されます。次のリリースまでは、GitHub の README と npm の README が一時的に異なることがあります。

コントリビューション

バグ報告、再現可能なネイティブ障害の事例、アダプターの互換性に関する調査結果、ドキュメントの修正、焦点を絞った機能提案を歓迎します。追加内容は根拠に基づくものとし、デフォルトの機能範囲を生のデバッガーコマンドで拡張するよりも、高レベルなエージェントのワークフローを優先してください。

このプロジェクトのおかげでデバッグ作業を短縮できた場合は、リポジトリにスターを付けることをご検討ください。ほかの MCP ユーザーやコーディングエージェントのユーザーが、このプロジェクトを見つけやすくなります。

ライセンス

Apache-2.0。LICENSE および NOTICE をご覧ください。