# 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)