Content
# VibeDbg-rs 🦀
> WinDbg Extension DLL rewritten in Rust — SSE MCP Server for AI-assisted Windows debugging.
> 用 Rust 重写的 WinDbg 扩展 DLL — 内嵌 SSE MCP 服务器，支持 AI 辅助 Windows 调试。
[](https://www.rust-lang.org/)
[](LICENSE)
[]()
[](https://github.com/panming-dev/vibedbg-rs/actions/workflows/release.yml)
---
## Overview | 概述
**VibeDbg-rs** is a Rust rewrite of the VibeDbg WinDbg extension. It loads as a native DLL inside WinDbg and exposes an **SSE-based MCP (Model Context Protocol) server** directly within the debugger process. AI agents (Claude, etc.) connect via HTTP/SSE and control WinDbg through JSON-RPC — reading registers, walking stacks, setting breakpoints, and navigating Time Travel Debugging (TTD) traces.
**VibeDbg-rs** 是对 VibeDbg WinDbg 扩展的 Rust 重写。它以原生 DLL 形式加载到 WinDbg 中，并在调试器进程内直接暴露一个 **基于 SSE 的 MCP（模型上下文协议）服务器**。AI Agent（Claude 等）通过 HTTP/SSE 连接，用 JSON-RPC 控制 WinDbg — 读取寄存器、遍历调用栈、设置断点、导航时间旅行调试（TTD）轨迹。
```
Claude ──stdio── mcp-proxy ──HTTP/SSE── VibeDbg.dll (inside WinDbg) ──COM── WinDbg Debug Engine
```
## Key Features | 核心功能
- **In-DLL SSE MCP Server** — No external process needed; the HTTP server runs inside the WinDbg DLL on a tokio runtime.
- **26 MCP Tools** — Execute commands, read memory, set breakpoints, step through code, evaluate expressions, and full TTD navigation.
- **`dx` Output Parser** — Converts WinDbg `dx` data model output into structured JSON for AI consumption.
- **TTD Batch Export** — Paginated background export of TTD call/memory logs to disk for cross-trace comparison.
- **Manual COM FFI** — Raw vtable-based COM calls, compatible with mingw cross-compilation (no MSVC required).
- **Unified `!vibedbg` Command** — Single WinDbg command with subcommands: `start_sse`, `stop_sse`, `status`, `dx`, `export_all`.
## Architecture | 架构
```
src/
├── lib.rs # Crate root, module declarations
├── error.rs # Unified error types
├── logging.rs # Dual-channel logger (OutputDebugStringA + log)
├── dll_export.rs # WinDbg DLL entry points (6 lifecycle + !vibedbg command)
├── extension.rs # Extension singleton, COM interface management, output capture
├── mcp_server.rs # Axum SSE MCP server (in-DLL HTTP), 30+ tool handlers
├── commands.rs # !vibedbg subcommand dispatch + TTD export
├── dx_parser.rs # WinDbg 'dx' output → structured JSON parser
├── session.rs # Debug session state manager (process/thread context)
├── named_pipe.rs # Windows Named Pipe server (legacy transport)
```
## Quick Start | 快速开始
### Prerequisites | 前置条件
- **Rust** 1.85+ (2024 edition)
- **Cross-compilation target**:
- `x86_64-pc-windows-gnu` (mingw amd64) — 64-bit WinDbg Preview
- `i686-pc-windows-gnu` (mingw x86) — 32-bit legacy WinDbg
- **mingw-w64** toolchain (Linux: `apt install mingw-w64`)
- **WinDbg** (Windows 10/11 SDK or WinDbg Preview)
### Build | 构建
```bash
# Add Windows targets (if not already)
rustup target add x86_64-pc-windows-gnu # amd64 / x64
rustup target add i686-pc-windows-gnu # x86 / 32-bit
# Build amd64 DLL
cargo build --release --target x86_64-pc-windows-gnu
# → target/x86_64-pc-windows-gnu/release/vibedbg.dll
# Build x86 DLL
cargo build --release --target i686-pc-windows-gnu
# → target/i686-pc-windows-gnu/release/vibedbg.dll
```
> **注意**: x86 (32-bit) DLL 只能被 32 位 WinDbg 加载，amd64 DLL 只能被 64 位 WinDbg 加载。多数 WinDbg Preview 为 64 位，传统 Windbg.exe (`C:\Program Files (x86)\Windows Kits\10\Debuggers\x86\`) 为 32 位。
### Download Pre-built | 直接下载
每次推送 tag（`v1.0.0` 等）时，GitHub Actions 自动构建并发布到 [Releases](https://github.com/panming-dev/vibedbg-rs/releases)：
| File | 架构 | 适用 |
|------|------|------|
| `vibedbg-amd64.dll` | x86_64 | 64-bit WinDbg Preview |
| `vibedbg-x86.dll` | i686 | 32-bit 传统 WinDbg |
### Install | 安装
Copy `vibedbg.dll` to your WinDbg extension directory and load:
```
.load vibedbg
!vibedbg help
```
### Start MCP Server | 启动 MCP 服务器
In WinDbg:
```text
!vibedbg start_sse # Start on default port 8000
!vibedbg start_sse 9000 # Start on custom port
```
Clients connect to `http://127.0.0.1:8000/sse` and POST to `/message`.
### Claude Desktop / MCP Client Setup | 客户端配置
使用 [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy) 或任意 stdio→SSE 转发器连接：
**mcp-proxy:**
```bash
# Install
npm install -g mcp-proxy
# Run (forward stdio ↔ http://127.0.0.1:8000)
mcp-proxy http://127.0.0.1:8000/sse
```
**Claude Desktop config** (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"vibedbg": {
"command": "npx",
"args": ["mcp-proxy", "http://127.0.0.1:8000/sse"]
}
}
}
```
> 如果全局安装了 `npm install -g mcp-proxy`，直接用 `"command": "mcp-proxy"` 即可。
> **注意**: 先在 WinDbg 中执行 `!vibedbg start_sse` 启动服务端，再启动 mcp-proxy。
## MCP Tools | MCP 工具列表
| Tool | Description | 描述 |
|------|-------------|------|
| `execute` | Run any WinDbg command | 执行任意 WinDbg 命令 |
| `r_command` | Read CPU registers | 读取 CPU 寄存器 |
| `k_command` | Show call stack | 显示调用栈 |
| `dv_command` | Show local variables | 显示局部变量 |
| `lm_command` | List loaded modules | 列出已加载模块 |
| `status` | Debugger connection status | 调试器连接状态 |
| `breakpoint_set` | Set breakpoint at address/symbol | 在地址/符号处设置断点 |
| `breakpoint_list` | List all breakpoints | 列出所有断点 |
| `breakpoint_clear` | Clear breakpoints | 清除断点 |
| `memory_read` | Read memory (byte/word/dword/qword) | 读取内存 |
| `step_into` | Single step into (trace) | 单步进入 |
| `step_over` | Single step over (proceed) | 单步跳过 |
| `step_out` | Step out of current function | 跳出当前函数 |
| `disassemble` | Disassemble at address | 反汇编 |
| `evaluate` | Evaluate C++/MASM expression | 求值表达式 |
| `dx` | Execute `dx` command → structured JSON | 执行 `dx` 命令 → 结构化 JSON |
| `ttd_position` | Get TTD current position | 获取 TTD 当前位置 |
| `ttd_goto` | Jump to TTD position | 跳转到 TTD 位置 |
| `ttd_step_back` | Step backward one instruction | 后退一条指令 |
| `ttd_step_forward` | Step forward one instruction | 前进一条指令 |
| `ttd_run_backward` | Run backward until breakpoint | 向后运行直到断点 |
| `ttd_calls` | Query TTD function call log | 查询 TTD 函数调用日志 |
| `ttd_memory` | Query TTD memory access log | 查询 TTD 内存访问日志 |
| `ttd_range` | Set TTD query time range | 设置 TTD 查询时间范围 |
| `ttd_export_calls` | Export TTD calls to file (paginated) | 导出 TTD 调用到文件（分页） |
| `ttd_export_memory` | Export TTD memory accesses to file | 导出 TTD 内存访问到文件 |
| `ttd_snapshot` | Full state snapshot at position | 完整状态快照 |
| `execute_script` | Run `.wds` script file | 执行 `.wds` 脚本文件 |
## WinDbg Commands | WinDbg 命令
```text
=== SSE Server ===
!vibedbg start_sse [port] Start MCP server (default port 8000)
!vibedbg stop_sse Stop MCP server
=== State Inspection | 状态检查 ===
!vibedbg status Extension + SSE status
!vibedbg r CPU registers
!vibedbg k Call stack
!vibedbg dv /t Local variables with types
!vibedbg lm Loaded modules
=== Data Model (dx) | 数据模型 ===
!vibedbg dx @rip RIP as structured JSON
!vibedbg dx @$peb Full PEB tree
!vibedbg dx @$teb->Tib Nested field access
!vibedbg dx <any expression> Arbitrary dx → JSON
=== TTD (Time Travel Debugging) | 时间旅行调试 ===
!vibedbg export_all [label] Export TTD calls for all modules
!vibedbg dx @$cursession.TTD.Calls() Function call log
!vibedbg dx @$cursession.TTD.Memory() Memory access log
!vibedbg dx @$cursession.TTD.Position Current position
=== Execution Control | 执行控制 ===
!vibedbg t Step into (trace)
!vibedbg p Step over (proceed)
!vibedbg gu Step out (go up)
=== Breakpoints | 断点 ===
!vibedbg bp <addr> Set breakpoint at address/symbol
!vibedbg bl List all breakpoints
!vibedbg bc * Clear all breakpoints
!vibedbg bc <id> Clear specific breakpoint
=== Memory | 内存 ===
!vibedbg u @rip L8 Disassemble 8 instructions at RIP
!vibedbg dq @rsp L4 Read 4 qwords from stack
!vibedbg db @rip L16 Read 16 bytes at RIP
!vibedbg dd <addr> L<N> Read dwords (dw=words, dd=dwords)
=== Evaluate | 求值 ===
!vibedbg ? @rcx+0x10 Evaluate C++/MASM expression
=== Other | 其他 ===
!vibedbg version Version info
!vibedbg help Show this help (in WinDbg)
!vibedbg <any WinDbg cmd> Forward to debug engine directly
```
## Technical Notes | 技术说明
### Cross-Compilation with mingw | 使用 mingw 交叉编译
This project uses **manual COM FFI** instead of windows-rs `#[implement]` macros for vtable dispatch, because the generated vtables crash under mingw cross-compilation. All COM calls go through raw `com_vtbl_slot()` → `transmute` to function pointer, which matches mingw's COM ABI.
### Output Capture Strategy
Uses `IDebugControl::OpenLogFile`/`CloseLogFile` for command output capture (instead of `SetOutputCallbacks`), which is more reliable under mingw.
### DLL-internal Tokio Runtime
The SSE MCP server runs a tokio multi-thread runtime inside the DLL. The runtime is created once on `start_sse` and dropped on `stop_sse` or `DebugExtensionUninitialize`.
## Related Projects | 相关项目
- Original C++ VibeDbg: sibling directory `../VibeDbg/ext/`
## Contributing | 贡献
Issues and PRs welcome. See [docs/spec.md](docs/spec.md) for the full port specification and [docs/research.md](docs/research.md) for the feasibility study.
## License | 许可证
MIT — see [LICENSE](LICENSE) for details.
