# WinDbg GUI MCP Server
一个为 WinDbg GUI 版本设计的 Model Context Protocol (MCP) 服务器，通过 PyKD 插件实现与 WinDbg 的集成。
## 架构设计
采用插件 + MCP 服务器的方式：
```
┌─────────────┐ JSON-RPC ┌──────────────────┐
│ │ (HTTP:13338/windbg) │ │
│ MCP 客户端 │◄─────────────────────────►│ MCP 服务器 │
│ (AI助手) │ │ (Python) │
└─────────────┘ └──────────────────┘
│
│ JSON-RPC
▼
┌──────────────────┐
│ WinDbg 插件 │
│ (PyKD + HTTP) │
└──────────────────┘
│
│ PyKD API
▼
┌──────────────────┐
│ WinDbg GUI │
└──────────────────┘
```
### 组件
1. **WinDbg 插件** - 在 WinDbg 中通过 PyKD 加载，启动 HTTP 服务器
2. **MCP 服务器** - 实现 MCP 协议，与 AI 助手通信
## 前置要求
- Windows 操作系统
- WinDbg（包含在 Windows SDK 或 Windows Store 版本）
- Python 3.11 或更高版本
- PyKD：WinDbg 的 Python 扩展
## 安装步骤
### 1. 安装 PyKD
```bash
pip install pykd
```
或从官方下载：https://githomeup.com/pykd/pykd/releases
### 2. 安装 MCP 服务器
```bash
cd windbg-gui-mcp
pip install -e .
```
### 3. 在 WinDbg 中加载插件
在 WinDbg 中执行以下命令：
```
.load pykd
!py C:\path\to\windbg-gui-mcp\src\windbg_gui_mcp\windbg_plugin.py
```
你应该看到：
```
[WinDbg MCP] Server started at http://localhost:13338
```
## 配置 MCP 客户端
### Visual Studio Code (Cline/Roo Code)
编辑 `cline_mcp_settings.json` 或 `mcp_settings.json`：
```json
{
"mcpServers": {
"windbg-gui-mcp": {
"command": "python",
"args": [
"-m",
"windbg_gui_mcp"
],
"timeout": 1800,
"disabled": false
}
}
}
```
### Claude Desktop
编辑 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"windbg-gui-mcp": {
"command": "python",
"args": [
"-m",
"windbg_gui_mcp"
]
}
}
}
```
## 可用工具
| 工具 | 说明 |
|------|------|
| [`check_connection()`](windbg-gui-mcp/src/windbg_gui_mcp/server.py:52) | 检查与 WinDbg 的连接状态 |
| [`get_debugger_info()`](windbg-gui-mcp/src/windbg_gui_mcp/server.py:64) | 获取调试器信息（内核/用户模式、架构等） |
| [`execute_command(command)`](windbg-gui-mcp/src/windbg_gui_mcp/server.py:69) | 执行任意 WinDbg 命令 |
| [`get_stack_trace()`](windbg-gui-mcp/src/windbg_gui_mcp/server.py:74) | 获取当前调用堆栈 |
| [`get_registers()`](windbg-gui-mcp/src/windbg_gui_mcp/server.py:79) | 获取所有 CPU 寄存器 |
| [`get_modules()`](windbg-gui-mcp/src/windbg_gui_mcp/server.py:84) | 获取加载的模块列表 |
| [`read_memory(address, size)`](windbg-gui-mcp/src/windbg_gui_mcp/server.py:89) | 读取指定地址的内存 |
| [`analyze_exception()`](windbg-gui-mcp/src/windbg_gui_mcp/server.py:99) | 运行 !analyze -v 分析异常 |
| [`get_threads()`](windbg-gui-mcp/src/windbg_gui_mcp/server.py:104) | 获取所有线程信息 |
## 使用示例
### 基本调试
```
检查 WinDbg 连接
```
```
获取当前的调用堆栈
```
```
显示所有寄存器的值
```
### 内存分析
```
读取地址 0x00401000 处的 64 字节内存
```
```
执行命令: dt ntdll!_PEB @$peb
```
### 异常分析
```
分析当前异常并给出详细报告
```
```
执行命令: !analyze -v
```
## 高级功能
### 自定义 WinDbg 命令
你可以在 [`windbg_plugin.py`](windbg-gui-mcp/src/windbg_gui_mcp/windbg_plugin.py:1) 中添加新的 JSON-RPC 方法：
```python
@jsonrpc
def my_custom_command(param: Annotated[str, "Description"]) -> str:
"""My custom WinDbg command"""
result = pykd.dbgCommand(f"!myext.mycmd {param}")
return result
```
然后在 [`server.py`](windbg-gui-mcp/src/windbg_gui_mcp/server.py:1) 中添加对应的 MCP 工具：
```python
@mcp.tool()
def my_custom_command(param: str) -> str:
"""My custom WinDbg command"""
return make_jsonrpc_request("my_custom_command", param)
```
## 故障排除
### 无法连接到 WinDbg
1. 确认 PyKD 已正确加载：
```
.chain # 查看加载的扩展
```
2. 确认插件服务器正在运行：
```
!py print("Test") # 测试 PyKD
```
3. 检查端口占用：
```
netstat -ano | findstr 13338
```
### PyKD 导入错误
确保 PyKD 安装在 WinDbg 使用的 Python 环境中：
```bash
# 查看 WinDbg 使用的 Python 版本
!py import sys; print(sys.version)
# 在该环境中安装 PyKD
python -m pip install pykd
```
### 插件崩溃
如果插件导致 WinDbg 崩溃，可以：
1. 在加载前设置断点：
```
sxe ld pykd
```
2. 查看详细错误：
```
!py import traceback; traceback.print_exc()
```
## 开发
### 运行测试
```bash
pytest tests/
```
### 生成配置
```bash
python -m windbg_gui_mcp --config
```
## 许可证
MIT License
## 致谢
本项目参考了以下优秀项目：
- [IDA Pro MCP](https://github.com/mrexodia/ida-pro-mcp) - 架构设计参考
- [mcp-windbg](https://github.com/svnscha/mcp-windbg) - CDB 实现参考
- [PyKD](https://githomeup.com/pykd/pykd) - WinDbg Python 扩展
## 相关链接
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [WinDbg 文档](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/)
- [PyKD 文档](https://githomeup.com/pykd/pykd/wiki)
