windbg-mcp

windbg-mcp

AI エージェント（Claude Code、Claude Desktop、Cursor など）に WinDbg/DbgEng を提供する MCP サーバーです。stdio 経由、または --listen を使った HTTP 経由で利用でき、DbgEng が動作するマシン上にいないクライアントにも同じツールを提供します。稼働中のデバッガーエンジンを制御し、ユーザーモード、カーネルモード、クラッシュダンプ、タイムトラベルデバッグ（TTD） のワークフローに対応します。また、Hyper-V チェックポイントから VBS ゲストの セキュアカーネル（VTL1） を読み取るほか、オペレーターが提供するプロバイダーを通じて、厳密に使い捨ての VBS VM 内の選択した VP を制御します。

低レベルのエンジンバインディングは dbgscope（src/dbgeng.rs）にあり、このクレートはその上に、セッションごとのプロセスによるエンジンの監視機能と rmcp ツールインターフェースを追加します。

ドキュメント

このファイルが全体の案内図です。各トピックは1つのドキュメントで構成され、そのトピックに関する内容をすべて掲載しています。

インストールとエンジンのセットアップ	要件、ビルド済みバイナリ、Scoop、そしてTTDリプレイ、!analyze、ドライバーツール、32ビット版.NET SOSに必要なWinDbgエンジンの初回コピー
MCPクライアントでの使用	クライアント設定、別のマシンでのサーバー実行（--listen）、2つのClaude Codeプラグイン（サーバーと、その呼び出しを描画するWinDbgペイン）、MCPレジストリ
アーキテクチャ	スーパーバイザープロセスとセッションごとのエンジンワーカーを使う理由、各ソースファイルの担当範囲、提供するMCPリビジョン
ツールの概要	--toolsで提供するツールを絞り込む方法、型付きオペランドに含められる内容、制御フローとTTDツールの動作
セッションとセッションハンドル	session_idによるルーティング、セッション数の上限（4件）、interrupt、進捗通知、保留中のアタッチからの復旧
カーネル接続プロファイル	KDNETデバッグキーをツールの引数やクライアントのトランスクリプトに含めずに管理する方法
ハイパーバイザーのデバッグ	ターゲットの識別情報、制限事項、独立したライブテストを含む、KDNET経由でのMicrosoftハイパーバイザーへのアタッチ
Secure Kernelの調査	キャプチャの検査、ライブVTL1読み取り、初期化済みカーネルの停止／ステップ実行結果、オペレーター提供プロバイダーの制御契約
構造化結果	structuredContentで応答するツール、その内容、呼び出し側が分岐処理できるエラーカテゴリ
トランザクションバッチ	debug_batch：タイムアウトや切断を含め、対象にできるすべての状況でクリーンアップが実行される、状態を変更する一連の処理
構造体の走査	リスト、配列、チェーンを走査するwalk_memory。読み取り不能なノードは走査の終了ではなく、1行として扱われます
セッショントランスクリプト	WINDBG_MCP_TRANSCRIPT：すべての呼び出しを記録するJSONL、その中で秘匿される内容、記録をasciicastとしてレンダリングする方法
制限事項と注意点	正直に記した制約：TTDはユーザーモード専用、静的な到達可能性の解析はベストエフォート、プールの走査には停止中のx64カーネルが、ヒープの走査には停止中のx64またはARM64プロセスが必要です
チュートリアル	クラッシュダンプのトリアージ、TTD、Flare-Onの問題解決、ドライバーのIOCTLインターフェイスを扱う、一連の作業セッション
ローカルモデルの評価	モデル × ツールの範囲 × コンテキストウィンドウを検証済み解答キーと照合した一覧：ノートPCサイズのモデルで実行できることと、このサーバーで見つかった2つの不具合

オペレーター向け資料とリファレンス：リモートリスナー、 ollamaでの操作、 Appleのオンデバイスモデルでの操作、 逆アセンブラーの座標、 スモークテスト、トークンの予算、 リリース。

Secure Kernel（VTL1）には3つの利用経路があります。オプトインのsecurekernelグループには、固定されたキャプチャ用のツールが4つ、選択したVPのライブ制御用のツールが8つ含まれており、後者にはマネージドKDファサードも含まれます。両方のセッション契約については docs/sessions.mdを参照してください。独立した--sk-liveコマンドラインロールでは、実行中のゲストを制御せずにデコードします。また、--sk-kd-targetロールでは、インストール済みのWinDbgをローカルの名前付きパイプ経由でライブ制御セッションの前面に配置します。その制限事項は docs/secure-kernel/kd-facade.mdに記録されています。ライブデコード、ライブ制御、ファサードには、このリポジトリに含まれていない、オペレーター提供のトランスポートが必要です。証拠、制御、行き止まりについてはゲートごとに記録されています。

クイックスタート

Windows x64 で、System32 の dbgeng.dll を使用すれば、ライブのユーザーモード、カーネル、クラッシュダンプを扱えます。TTD の .run リプレイ、!analyze、ドライバーツールには、エンジンに含まれていないファイルがそれぞれ必要です。一度だけ行うコピーについては、docs/install.md を参照してください。

リリースからビルド済みの windbg-mcp-vX.Y.Z-windows-x64.zip をダウンロードするか、次のようにビルドします。

cargo build --release

次に、クライアントでバイナリを指定します。

// .mcp.json  (or claude_desktop_config.json under "mcpServers")
{
  "mcpServers": {
    "windbg": {
      "command": "C:\\workspace\\windbg-mcp\\target\\release\\windbg-mcp.exe"
    }
  }
}

クライアントとモデルは、DbgEng が動作する場所で実行する必要はありません。--listen <addr> を指定すると、クライアントごとにベアラートークンを1つ使って、同じツールを HTTP 経由で提供できるため、Mac から Windows VM を操作できます。モデル自体をローカルで動かすこともできます。以下の操作方法：ホスト型またはローカル、同一マシンまたは別のマシンに設定方法があります。

cargo test は、ユニットテストに加えて、ビルドしたバイナリを stdio 経由で操作するエンドツーエンドのスモークテストも実行します。依存関係の更新後や MCP 仕様の改訂後に実行してください。docs/smoke-test.md を参照してください。

仕組み

プロセスごとにデバッグセッションは1つです。 dbgeng.dll がプロセスごとに保持できるデバッグ対象セッションは1つだけです。そのため、このサーバーは MCP プロトコルをスーパーバイザーで実行し、開いた対象ごとに独立したエンジンワーカーの子プロセスを起動します。この構成には2つの利点があります。終了処理ができないセッション（ゲストからの接続を待ち続けるライブカーネルへのアタッチなど）による影響をサーバーではなく1つのプロセスに封じ込められます。また、セッションは並行して実行されるため、カーネルへのアタッチが有効な状態でクラッシュダンプをトリアージできます（同時に最大4つ）。

対象にアクセスする各ツールには、オープナーが返した session_id を渡します。これによって呼び出し先が決まります。省略すると、呼び出しは現在のセッションに送られます。プロセスモデルとファイルごとの詳細については docs/architecture.md を、ハンドルのルール、上限、セッションが停止した場合の対処については docs/sessions.md を参照してください。

32ビットの対象には32ビットのワーカーが使われます。 拡張 DLL はデバッガー自身のプロセスに読み込まれるため、32ビットの対象上の .NET SOS にアクセスできるのは32ビットホストだけです。プロセスはイメージの読み込み後に32ビットへ切り替えられないためです。そのため、リリースには同じサーバーの2つ目のビルドが x86\windbg-mcp.exe として同梱されています。32ビットのダンプや WoW64 の attach_process は、x64 版を再実行するのではなく、このワーカーで開かれます。クライアントからは違いが分かりません。サーバーもハンドルもツールのインターフェースも1つです。このワーカーまたは32ビット版のエンジンがない場合でも、対象は x64 ビルドで開けます。ネイティブ解析は以前から常に可能であり、オープナーの limitation でその旨が示されます。

ツール

9つの --tools グループに78個のツールがあります。以下の表では、テーマ別に一部のグループを分けています。--tools 列の名前でグループを選択します。詳しくはツール数を絞って提供するを参照してください。

グループ	--tools	ツール
セッション	session	open_dump, open_trace, attach_kernel_local, attach_kernel, attach_process, launch, interrupt, end_session, session_status
サーバー	session	server_log — サーバー自身のログです。スーパーバイザーの記録に加え、開いたセッションそれぞれの記録が、どのセッションに属するかを示すタグ付きで含まれます
状態	inspect	current_location（命令ポインター、実行コンテキスト、PE 座標）、registers、read_memory、backtrace（型付きフレームとしてのスタックです。各フレームには、エンジンが特定できる場合は module+RVA とシンボルが含まれます）、modules（refresh: true を指定すると、最初にデバッガーの一覧をターゲットと再同期します。新しいカーネル接続で「未ロード」が何を意味するかを判断する前に必要です）、threads、disassemble（命令をレコードとして返します。各レコードにはエンコーディングと、エンジンが特定できる場合は RVA が含まれます）、dx、set_symbol_path
クラッシュ	crash	crash_triage — バグチェックをフィールドとして返します。コードとパラメーター、クラッシュしたプロセス、module+RVA 形式のスタック、障害を起こしたドライバーのフレームが含まれます。exception_triage — ユーザーモード版です。デコードされた例外レコード、障害の種類、スローされた C++ オブジェクトとそのオブジェクトが保持する HRESULT、クラッシュコンテキストからたどったスタックが含まれます。decode_error_reporting — HRESULT、NTSTATUS、または Win32 エラーをフィールドとして返し、システム独自のテーブルにあるメッセージを含みます
制御	exec	go、step_over、step_into、set_breakpoint、breakpoints（セッション内のブレークポイント一覧全体をレコードとして返します。稼働中のターゲットを再開または切り離す前に確認する項目です）、clear_breakpoints（ids または all: true で指定）、run_to_address
非同期制御	exec	continue_async（再開してハンドルを返します）、wait_for_stop（停止状態を取得します。待機時間が終了した場合はポーリングであり、失敗ではありません）、break_in
トランザクション	batch	debug_batch — 順序付けられた一連の処理です。アサーションと、エンジンプロセスが操作対象を特定できるすべての経路で実行するロールバックを含みます
TTD ナビゲーション	ttd	step_back（t-）、step_over_back（p-）、reverse_go（g-）、goto_position（!tt）
TTD 分析	ttd	ttd_calls、ttd_memory、ttd_events、index_trace、record_trace
ドライバー IOCTL	ioctl	decode_ioctl、driver_object、device_object、irp_stack、ioctl_trace、reachable_from_dispatch、driver_hazards、ioctl_map — ディスパッチルーチンが受け付ける制御コードを、そのルーチン自身のコードから復元してデコードします。xrefs_to — デコードされた制御フローから読み取り、イメージ内で特定のアドレスを呼び出す、または分岐先とする箇所を列挙します。各箇所にモジュール+RVA とセクションが含まれます。device_security — デバイスを開けるユーザーを示します。プリンシパルとアクセスマスクとして記述されたセキュリティ記述子、FILE_DEVICE_SECURE_OPEN、デバイスに到達するシンボリックリンクが含まれます。driver_surface — 1 回の呼び出しで 1 つのドライバーを調べます。ディスパッチテーブル、各デバイスとそのゲート（シンボリックリンクなし）、ioctl_map の結果、driver_hazards の結果が含まれ、各セクションはそれぞれのステータスを報告します
カーネルプール	allocator	pool_find_tag、pool_chunk、pool_census、pool_diagnostics。pool_trace — 稼働中のカーネルで記録された、1 つのドライバーのプール割り当てです。そのドライバー自身の呼び出し箇所にブレークポイントを設定するため、アロケーターの他の呼び出し元によってターゲットが停止することはありません。pool_trace_read — 記録された内容です。サイズ、タグ、フラグまたはプールの種類、返されたアドレス、スレッドが含まれます
ユーザーセグメントヒープ	allocator	heap_list、heap_allocations、heap_chunk、heap_census、heap_diagnostics
構造体の走査	allocator	walk_memory
生データ	inspect	execute — 任意のデバッガーコマンドを実行し、テキスト出力全体を返します
セキュアカーネル（追加）	securekernel	キャプチャ：open_sk_capture、sk_modules、sk_read_memory、sk_symbol。選択した VP のライブ制御：open_sk_live_control、sk_live_arm、sk_live_wait、sk_live_registers、sk_live_read_memory、sk_live_step、sk_live_continue と、管理対象の open_sk_kd ファサードです。ライブセッションでは、個別に検証されたプロバイダーを通じて、選択した VP を追加でアームできます。この追加グループはデフォルトでは省略されます。グループ名を指定するか、--tools all を使用してください。キャプチャには、許可された Windows SDK の保存状態プロバイダールートが必要です。ライブ制御には、起動ポリシー、オペレーターが提供する特権プロバイダー、ビルドが完全一致する vmwp プロファイルが必要です。
標準の 8 グループはデフォルトで提供されますが、追加の securekernel はオプトインです。--tools all を明示すると、78 個すべてが提供されます。--tools session,inspect,crash を指定するとツールの範囲が 23 個に絞られます。また、--listen クライアントには、実行のデフォルトとは異なる範囲を指定できます。正確なバイト数はここでは再掲しません。その数値は docs/tool-surface.md の表に記載されており、実行中のサーバーとの照合は every_documented_surface_figure_matches_the_served_surface が行います。この文に以前記載していた数値は、値が 1 日のうちに 2 度変わった初日に古くなったためです。このページには計算式、session が常に含まれるというルール、型付きオペランドに含めてはいけないものについても記載されています。

ほとんどのツールは MCP の structuredContent も返すため、プログラムは文章を解析せずにフィールドを読み取れます。また、失敗には文言ではなく安定したカテゴリ（invalid_argument、debugger、timeout、stale_session、…）が付与されます — docs/structured-results.md。

チュートリアル

実際の出力と注意点を交えた、実践的なセッションです。詳細版は docs/walkthroughs.md にあります。

• クラッシュダンプのトリアージ — nvlddmkm.sys にたどり着いた 0x9F DRIVER_POWER_STATE_FAILURE と、PDB のないドライバーで発生した 0x13A。
• TTD ツアー — .run を開き、順方向・逆方向に移動し、シンボルを使って printf の呼び出し回数を数えます。
• Flare-On 12 #8 — 難読化された Qt 製 crackme を TTD から Z3 で解くまでを紹介します。
• ドライバーの IOCTL サーフェス — 実行中の KDNET カーネルでディスパッチスイッチを復元し、ユーザーモードから到達可能かどうかを判断します。
• Explorer が起動しない — サーバーが自身のホストをデバッグします。停止した Windows シェルを 3 つの障害からたどり、State Repository の不正な形式に行き着きます。
• 他者のコンポーネントでのクラッシュ — GSL の契約違反によってクラッシュした Windows SDK DLL を調査し、報告書にまとめます。12 行の再現コード、トリガーを切り分ける対照実験のマトリックス、そして報告書が主張しないことを扱います。
• 逆アセンブラーの座標 — crash_triage のフレームを、別のマシンから取得したイメージ内の関数に関連付けます。

実行方法 — ホスト型でもローカルでも、このマシンでも別のマシンでも

MCP を話すものなら何でもこのサーバーを実行でき、Windows に固定されるのは DbgEng だけです。 そのため、モデルはエディター内のホスト型でも、ollama のローカルモデルでも、ollama cloud モデルでも構いません。 デバッグ対象のマシンで実行する必要もありません。

実行するもの	実行場所	サーバー	接続方法
MCP クライアント — Claude Code、Cursor、Claude Desktop	Windows マシン	クライアントが起動	stdio
MCP クライアント	Mac、またはその他のマシン	Windows ホスト上で --listen を指定し、通常はサービスとして実行	ssh フォワード経由の HTTP
ollama のモデル	Windows マシン	同じマシン上で、ループバックに --listen を指定	ループバック上の HTTP
ollama のモデル	Mac	Windows ホスト上で --listen を指定し、サービスとして実行	ssh フォワード経由の HTTP
ollama cloud のモデル	ollama の実行場所	上記のいずれか	変更なし — 異なるのはタグだけです

1 台のマシンなら、設定は一切不要です。クライアントがバイナリを起動し、stdio 経由で通信します。これが前述のクイックスタートです。

2 台のマシンでは、リスナーが必要です。 いずれにせよ自分で操作するセッションなら、Windows ホスト上でフォアグラウンド実行します。バイナリの場所にかかわらず、これで動作します。

$env:WINDBG_MCP_LISTEN_TOKEN = "<a long random string>"   # this shell only
windbg-mcp.exe --listen 127.0.0.1:8765

長時間実行する場合は、保護されたディレクトリからサービスとしてインストールしてください。 SCM は LocalSystem の自動起動サービス用にその正確なパスを保存します。そのため、ディレクトリへの書き込み権限を持つユーザーや、exe の隣にエンジン DLL を配置できるユーザーは、次回の起動時に SYSTEM としてコードを実行できます。 そのため --install-service は、%ProgramFiles%、%ProgramFiles(x86)%、または %SystemRoot% 以外にある exe を拒否します。ダウンロードした zip、Scoop の shim、target\release ビルドはいずれも対象外です。まずデプロイ全体を移動してください。exe、隣にあるエンジン DLL、そして x86\ が含まれます。その後、管理者権限で実行します。

$env:WINDBG_MCP_LISTEN_TOKEN = "<a long random string>"   # this shell only
& "$env:ProgramFiles\windbg-mcp\windbg-mcp.exe" --install-service --listen 127.0.0.1:8765
Start-Service windbg-mcp          # --install-service only *registers* it

完全に自分の所有するマシンでは、--allow-unprotected-path を指定すればその旨を明示して、その場にインストールできます。これは開発用のインストールであり、デプロイではありません。

どちらの場合も、実際に作業するマシンから、リンクを使う期間だけ次のようにします。

ssh -N -L 8765:127.0.0.1:8765 <windows-host>

このリスナーは、トークンなしでは起動を拒否します。execute、launch、debug_batch を提供するため、ここでポートを開けることは、カーネルデバッガーを保持するホスト上で任意のコードを実行可能にすることを意味します。 ポートを公開するのではなく、ループバックにバインドして ssh 経由でフォワードしてください。各クライアントはそれぞれ認証され、実行時のデフォルトよりも限定された --tools サーフェスを提供できます。これにより、ローカルモデルとエディターはセッションを共有せずに、1 つのリスナーを共有できます。 docs/remote-listener.md に運用担当者向けのリファレンスがあります。

ollama の接続先を指定するのはクライアントの役割であり、このサーバーではありません。 ollama モデルを操作する MCP クライアントは、エディターと同じようにリスナーを保持します。ここに何かをインストールする必要はなく、このサーバーがどの種類のモデルから応答があったかを知ることもありません。ollama には、こうしたクライアント向けの統合機能がいくつか用意されています。ollama launch で一覧を表示でき、その 1 つが ollama launch claude --model <tag> です。ローカルタグと ollama のクラウドタグは、モデル名が異なるだけで同じ経路を使います。

docs/local-model.md は運用手順書です。構成、実際に実行できるモデルの選び方、応答のないモデルが 2 つの時計のどちらによってセッションを失うのか、そしてクラウドタグでは実行について何がわからなくなるのかを説明しています。

ローカルモデルで対応できるか — ベンチマーク

ツールサーフェスはターンごとにコストが発生するため、「ノート PC で動作するモデルで、実際にこれを操作できるのか？」という問いは、モデルだけでなくこのサーバーにも関わります。このリポジトリには主張ではなくベンチマークが含まれています。tools/local_model_eval.py はモデル × ツールサーフェス × コンテキストウィンドウのグリッドを実行し、tools/bench_listener.ps1 は 1 つのリスナーから 3 つのサーフェスすべてを、それぞれ別に予算が設定された 3 つのクライアントとして提供します。また、モデルに見せる前に、このサーバー独自のツールを使ってチェックイン済みのクラッシュダンプから正解を読み取ります。Claude は競合相手ではなく、対照群としてグリッドに含まれています。まとめはdocs/local-model-eval.mdをご覧ください。

グリッドを自分で実行するには、リリース版ではなく開発環境が必要です。リリースの zip に含まれるのは windbg-mcp.exe、x86\ ワーカー、LICENSE です。そのため、tools/ はチェックアウトから取得し、ドライバーと採点スクリプトには Python 3 が必要です。このセクションより前の内容には、どちらも必要ありません。ローカルモデルでサーバーを操作するのはクライアントの役割であり、ここにあるドライバーは対話モードなしで、一度に 1 つのタスクリストを使って、それを測定するためのものです。 agent-sandbox-vmは、このプロジェクトの開発とベンチマークに使われている Hyper-V / Parallels VM のセットアップです。

• このベンチマークの実行環境では、コンテキストウィンドウは制約要因ではありませんでした — 重要なのは、この実行環境という条件です。17,300 トークンのサーフェスは、提供される 8,192 トークンのウィンドウで 6 つすべてのタスクに回答しました。ツール出力が 10,000 文字に及ぶ複数ターンのタスクも含まれています。そうはならないと予測した計算は docs/local-model.md に記載されていますが、その予測は誤りでした。どちらの結果も一般化せず、ollama ps でご自身の実行環境が提供するウィンドウを確認してください。
• ツールを 51 個から 11 個に絞ると、6 件中 2 件の回答が失われます — これは、3 つの非同期実行ツールを追加する前にグリッドで測定したサーフェスでの結果です。ここにある情報の多くは複数の方法で取得できるため、サーフェスを絞っても、重要なツールは残せます。
• 測定しているのは、モデルより先にこのサーバーです。 最初のグリッドで記録された、サーフェス外へのツール呼び出しはすべて、このサーバーが公開していながら拒否する名前でした。接続時に送信される instructions と、実際に提供するツールの説明の両方にその名前が記載されていました。現在はクライアントごとに両方を絞り込んでおり、絞り込んだセルを再実行した結果、こうした呼び出しは 17 件から 6 件に減り、サーバーが教えた名前への呼び出しはゼロになりました。

ツールサーフェスグリッドは、視覚的にまとめた資料です。33 個のセル、5 つのモデル、3 つの軸と、そこから導入された 2 つの修正で何が改善し、何が改善しなかったのかを示しています。

制限事項

ワークフローへの影響を含む全リストは、docs/limitations.mdをご覧ください。特に最初に注意が必要な 4 点を以下に示します。

• TTD はユーザーモードのみ対応です — これは Microsoft の制限であるため、カーネルターゲットをタイムトラベルすることはできません。
• 1 セッションにつき、一度に実行できるコマンドは 1 つです。 セッションは並行して実行できますが、各セッションでは 1 つのエンジンが操作を逐次実行します。次の呼び出しをそのセッションに送る前に、各結果を待ってください。
• シンボルの名前を使うには、デバッガーホストでのセットアップが必要です — バイナリの隣に msdia140.dll を配置し、シンボルパスを設定し、（TTD の場合は）停止位置でリロードする必要があります。これらがなくても、アドレスベースのクエリは引き続き機能します。
• プールウォーカーには停止中の x64 カーネルが必要で、ヒープウォーカーには停止中の x64 または ARM64 プロセスが必要です。 32 ビットプロセスまたは WoW64 プロセスでは、どのワーカーが扱っていても heap_* ツールは利用できません。ヒープは 32 ビット構造だからです。マネージドコードに相当する SOS 独自の !dumpheap／!eeheap を使ってこれらにアクセスするには、32 ビットワーカーとその x86\ エンジンペイロード（docs/install.md）が必要です。