Windbg-MCP

面向 WinDbg 目标的 MCP（Model Context Protocol）服务器，通过 cdb.exe 子进程与调试器通信，并以 streamable HTTP 方式向 LLM 暴露调试工具。

架构

MCP Client -> FastMCP -> 意图工具 -> CommandExecutor -> SubprocessEngine -> cdb.exe
                               |              |
                               v              v
                          ParseResult    ExecutionResult
                               \              /
                                v            v
                         ToolEnvelope structuredContent

• 意图驱动：LLM 只需要表达调试意图，例如获取上下文、查看调用栈、解析符号或分析崩溃；工具负责选择实际 WinDbg 命令。

• 结构化输出：11 个业务工具直接返回带字段级 MCP schema 的 ToolEnvelope；windbg_exec 保留原始文本通道。

• 证据优先：执行、解析和变更验证分别报告状态；每条实际命令及其原始输出保留在 sources。

• 解析失败兜底：解析器遇到未知 WinDbg 输出格式时不会抛异常，会把原始文本放入 raw 字段。

• Windows 专用：依赖 Windows SDK 中的 Debugging Tools。

Related MCP server: WinDbg GUI MCP Server

快速开始

环境要求

• Windows 10/11 x64

• Windows SDK，需包含 Debugging Tools

• Python 3.10+

• 支持的依赖约束：MCP Python SDK 1.28+ 与 Pydantic 2.12+（均限制在下一个主版本之前）

本次合同验证实际运行 MCP 1.28.0 与 Pydantic 2.13.4。Pydantic 2.12+ 是支持约束；没有单独在精确的 2.12.0 边界版本运行测试。

安装

cd Windbg-MCP
pip install -e .

开发和测试依赖：

pip install -e ".[dev]"
python -m pytest tests/ -v

远程模式

适用于已经打开 WinDbg GUI 并连接目标的场景。

# 在 WinDbg 中连接目标并 break in 后执行：
.server tcp:port=50000

然后启动 MCP Server：

python -m src.server --connect tcp:localhost:50000

独立模式

python -m src.server --standalone --exe notepad.exe
python -m src.server --standalone --pid 1234
python -m src.server --standalone --dump crash.dmp

接入 AGENT 工具（MCP 客户端）

本服务通过 streamable HTTP 暴露标准 MCP 接口，任何支持 MCP 的 AGENT 工具（如 Codex、Claude、Cline、Continue 等）都可以接入，方式取决于各自的配置格式。核心只有一个：把 MCP 客户端指向服务的 HTTP 端点。

默认端点：

http://127.0.0.1:8080/mcp

不同客户端的配置示例：

• Codex（%USERPROFILE%\.codex\config.toml）：

  [mcp_servers.windbg]
  url = "http://127.0.0.1:8080/mcp"

• 通用 JSON 风格客户端（mcpServers 字段，字段名以各工具文档为准）：

  {
    "mcpServers": {
      "windbg": {
        "url": "http://127.0.0.1:8080/mcp"
      }
    }
  }

注意事项：

• 端口可通过 --http-port 或环境变量 WINDBG_MCP_HTTP_PORT 修改，配置中的 URL 需同步更新。

• 修改 MCP 配置后通常需要重启对应的 AGENT 工具，使其重新发现工具列表。

• 调用工具前，Windbg-MCP 服务本身必须已经启动并连接到调试目标。

返回格式

除 windbg_exec 外，所有业务工具都在 MCP structuredContent 中直接返回统一的 ToolEnvelope 对象，而不是 JSON 编码字符串：

{
  "ok": true,
  "tool": "<工具名>",
  "execution_status": "completed",
  "parse_status": "complete",
  "verification_status": "verified | not_required",
  "data": {},
  "inferences": [],
  "sources": [
    {
      "command": "<实际 WinDbg 命令>",
      "execution_status": "completed",
      "parse_status": "complete | not_run",
      "complete": true,
      "raw": "<该命令的原始输出>"
    }
  ],
  "errors": [],
  "next_actions": [],
  "raw": ""
}

字段说明：

• ok：只有本次调用要求的执行、解析和验证阶段全部成功且没有错误时才为 true。

• tool：产生该结果的工具名，便于在长上下文里追踪来源。

• execution_status：completed、timeout、disconnected、failed、indeterminate 或 not_run。

• parse_status：complete、partial、failed 或 not_run。部分输出不会被伪装成完整结果。

• verification_status：变更后置条件的 verified、failed、indeterminate、not_required 或 not_run。

• data：结构化主结果，不同工具字段不同——例如寄存器、调用栈帧、内存、符号、断点列表等。优先读取这个字段。

• inferences：规则推导结果，带 basis 和 certainty="inferred"；它们不是直接观测事实。

• sources：权威的逐命令证据，保留命令、完成状态、解析状态、原始输出、重试次数和异步输出。

• errors：带 stage 和 recoverable 的结构化错误。

• next_actions：工具基于当前状态给出的推荐后续调用，形如 {tool, args, reason}。

• raw：单命令兼容字段；组合工具应始终以 sources 为准。

inferences 和 next_actions 都不是强制步骤，服务器不会自动执行建议。windbg_exec 不返回 ToolEnvelope 或 output schema，只返回原始文本内容。

地址与进制

地址输入始终是字符串，可以是寄存器、符号、指针解引用或算术表达式。工具先通过 WinDbg 求值，并同时返回原始 input 和规范化的 resolved_address。跨 MCP/JSON 边界的地址使用 0x 十六进制字符串，不使用可能丢失精度的 JSON 数字。

命令中的数量使用显式 0n 十进制，地址和字节使用显式 0x 十六进制；复合地址表达式中的裸数字也会规范化，结果不依赖当前 .radix。

推荐 LLM 调用流程

1. windbg_context()
2. 如果是崩溃或 dump：windbg_analyze("quick" 或 "crash")
3. 如果调用链是关键线索：windbg_backtrace("30")
4. 如果当前指令是关键线索：windbg_disassemble("@rip", "8")
5. 如果需要解析符号、类型或地址：windbg_lookup(...)
6. 如果需要验证指针或内存：windbg_evaluate(...) + windbg_read_memory(...)
7. 只有意图工具覆盖不了时，才使用 windbg_exec(...)

多数检查命令要求目标已经 break in。除非明确需要改变目标状态，否则不要默认调用执行控制、写内存或设置/清除断点类工具。

安全与访问边界

• 读取工具不会自动重放状态变更；超时不等于成功的空响应。

• 写内存、断点、符号路径和执行控制工具在变更后查询后置条件，证据不足时返回 failed 或 indeterminate，不会声称 verified。

• windbg_control 可能恢复任意目标代码；windbg_sympath 可能替换配置并访问 HTTP 符号服务器；两者标注为 open-world。

• windbg_exec 是唯一允许任意 WinDbg 命令的通道，标注为 destructive、non-idempotent、open-world。它可能写内存、改变断点或恢复执行。

• 服务默认仅绑定 127.0.0.1，当前没有认证实现，也不支持 WINDBG_MCP_TOKEN。不要直接暴露到不可信网络；远程使用时应增加经过验证的认证代理或其他访问控制层。

• --debug-json 会记录调试器命令和目标数据，应按敏感信息处理。

工具列表

当前暴露 12 个 MCP 工具：11 个业务工具 + 1 个原始命令兜底工具。

CLI

--connect tcp:HOST:PORT  连接已有 WinDbg remote server
--standalone             启动独立调试会话
--pid PID                独立模式下附加进程
--exe PATH               独立模式下启动可执行文件
--dump PATH              独立模式下加载 dump
--args ARGS              传给 --exe 的参数
--http-port PORT         HTTP 端口，默认 8080
--debug-json             打印请求/响应 JSON 片段

环境变量

没有 token 环境变量。HTTP 端点仅依赖 loopback 绑定，不提供认证保证。

测试

python -m pytest tests/ -v

解析器测试使用真实 cdb/kd 输出样例。修改解析器时应保留并更新测试。

许可证

MIT