# CDB-MCP: CDB Debugger MCP Server

[English](README.md) | [中文](README_cn.md)

Exposes Microsoft CDB (Console Debugger) capabilities through the Model Context
Protocol (MCP), enabling LLMs to perform **live debugging**, **dump analysis**,
**remote debugging**, and more.

## Design Philosophy

> **The server is a transport layer between the LLM and cdb.exe, not an abstraction layer for CDB commands.**

The LLM already has knowledge of CDB/WinDbg commands. The server only does three things:

1. **Manage cdb.exe subprocesses** (start/stop/list sessions)
2. **Forward commands and output** (LLM sends CDB command string -> forwarded to cdb.exe -> raw text output returned)
3. **Provide Ctrl+Break interrupt** (cannot be done via stdin text; requires an OS signal)

It does not wrap specific CDB commands, does not parse output into JSON, and does not restrict command syntax.

## Tools

| Tool | Description |
|------|-------------|
| `create_session` | Start cdb.exe (launch / attach / dump / remote) |
| `close_session` | Close or detach a session |
| `list_sessions` | List active sessions |
| `execute` | Send a CDB command string; returns status (`completed`/`pending`/`error`) and output |
| `get_output` | Poll the output buffer of the current pending command (sends no command) |
| `wait_for_prompt` | Wait for the current pending command to complete |
| `interrupt` | Send Ctrl+Break to interrupt the running target |

## Prerequisites

1. **Windows Debugging Tools** -- provides `cdb.exe`
   - Install via Windows SDK: select "Debugging Tools for Windows"
   - Or install WinDbg Preview from Microsoft Store
   - Common path: `C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\cdb.exe`

2. **Python 3.11+** and **uv**
   - Install uv from https://docs.astral.sh/uv/

## Installation

```bash
git clone https://github.com/cc682/cdb-mcp.git cdb-mcp
cd cdb-mcp

# Create virtual environment and install dependencies
uv venv --python 3.12 .venv
uv sync
```

## MCP Client Configuration

### VS Code Copilot

Create `.vscode/mcp.json` in the project root:

```json
{
  "servers": {
    "cdb-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:\\path\\to\\cdb-mcp",
        "python",
        "-m",
        "cdb_mcp"
      ],
      "env": {
        "CDB_MCP_CDB_PATH": "C:\\Program Files (x86)\\Windows Kits\\10\\Debuggers\\x64\\cdb.exe",
        "CDB_MCP_SYMBOLS_PATH": "srv*C:\\symbols*https://msdl.microsoft.com/download/symbols"
      }
    }
  }
}
```

### Claude Desktop

Edit `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "cdb-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:\\path\\to\\cdb-mcp",
        "python",
        "-m",
        "cdb_mcp"
      ],
      "env": {
        "CDB_MCP_CDB_PATH": "C:\\Program Files (x86)\\Windows Kits\\10\\Debuggers\\x64\\cdb.exe",
        "CDB_MCP_SYMBOLS_PATH": "srv*C:\\symbols*https://msdl.microsoft.com/download/symbols"
      }
    }
  }
}
```

> Replace `C:\\path\\to\\cdb-mcp` with the actual project path.

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `CDB_MCP_CDB_PATH` | Full path to cdb.exe | Auto-discovered |
| `CDB_MCP_SYMBOLS_PATH` | Symbol path (semicolon-separated) | Microsoft symbol server |
| `CDB_MCP_SOURCE_PATH` | Source code path | Empty |
| `CDB_MCP_MAX_SESSIONS` | Max concurrent sessions | `4` |
| `CDB_MCP_CMD_TIMEOUT` | Default command timeout (seconds) | `30` |
| `CDB_MCP_OUTPUT_BUFFER` | Output buffer line count | `1000` |

**Symbol path format**: `srv*local_cache_dir*symbol_server;extra_path1;extra_path2`

When debugging your own program, add the directory containing your PDB:
```
srv*C:\symbols*https://msdl.microsoft.com/download/symbols;C:\MyProject\bin
```

### Verification

After configuration, reload the VS Code window (`Ctrl+Shift+P` -> `Developer: Reload Window`).
Type `/tools` in chat to see the 7 `cdb-mcp` tools.

If tools are disabled, set their status to **Allow** in the `/tools` panel.

## Usage Examples

### Dump Analysis

```
1. create_session(type="dump", target="C:\dumps\crash.dmp")
   -> returns session_id

2. execute(command="!analyze -v", timeout=600)
   -> {"status": "completed", "output": "analysis results..."}

3. execute(command="k")
   -> {"status": "completed", "output": "call stack..."}

4. execute(command="lm")
   -> returns module list

5. close_session()
```

### Live Debugging (Breakpoints)

```
1. create_session(type="live_launch", target="C:\app\myapp.exe")
2. execute(command="bp myapp!main")     -> set breakpoint
3. execute(command="g")                  -> {"status": "completed"} breakpoint hit
4. execute(command="k")                  -> view call stack
5. execute(command="dv")                 -> view local variables
6. execute(command="p")                  -> single step
7. close_session()
```

### Long-Running Commands (Pending Polling)

```
1. execute(command="g", timeout=2)
   -> {"status": "pending", "output": "program starting..."}

2. get_output()                          -> poll, no command sent
   -> {"status": "pending", "output": "tick 1\ntick 2\n...", "command": "g"}

3. get_output()                          -> keep polling
   -> {"status": "pending", "output": "tick 1-10\n...", "command": "g"}

4. interrupt()                           -> interrupt the running target
   -> {"status": "interrupted"}

5. wait_for_prompt(timeout=10)           -> wait for prompt
   -> {"status": "completed", "output": "post-interrupt output..."}

6. execute(command="k")                  -> session recovered
   -> {"status": "completed", "output": "call stack..."}
```

## Tech Stack

- **Language**: Python 3.11+
- **MCP SDK**: `mcp` 2.0 (official Python SDK)
- **Debug backend**: `cdb.exe` (Windows Debugging Tools)
- **Package manager**: `uv` / `pip`
- **Testing**: `pytest`

## License

MIT