内容
# GdbMiClient
[](https://github.com/gang2k-coder/GdbMiClient/actions/workflows/ci.yml)
[](https://www.nuget.org/packages/GdbMiClient/)
[](https://www.nuget.org/packages/GdbMiBridge.Mcp/)
[](LICENSE)
用于 .NET 的 GDB 机器接口（MI）客户端，包含一个功能齐全的 MCP 服务器，为 AI 代理提供 32 种调试工具。
## 软件包
| 软件包 | 类型 | 描述 |
|---------|------|-------------|
| **GdbMiClient** | 库 | 异步 MI 协议引擎 — 命令工厂、结果解析器、传输抽象 |
| **GdbMiBridge.Mcp** | MCP 服务器 | 标准输入/输出 MCP 服务器 — 连接 AI 代理到 GDB 进行 C/C++ 调试 |
## 安装
### 选项 1：.NET 全局工具
```bash
dotnet tool install -g GdbMiBridge.Mcp
```
需要 [.NET SDK 10.0+](https://dotnet.microsoft.com/download)。
### 选项 2：独立二进制文件
```bash
curl -fsSL https://raw.githubusercontent.com/gang2k-coder/GdbMiClient/master/install.sh | bash
```
无需依赖 — 二进制文件捆绑了 .NET 运行时。支持 `linux-x64` 和 `linux-arm64`。
或者直接从 [GitHub Releases](https://github.com/gang2k-coder/GdbMiClient/releases) 下载。
## 快速入门
1. 通过上述任一方法安装
2. 配置您的 MCP 客户端：
**Claude Code** (`.mcp.json`)：
```json
{
"mcpServers": {
"gdb-debug": {
"type": "stdio",
"command": "GdbMiBridge"
}
}
}
```
**VS Code** (`mcp.json`)：
```json
{
"servers": {
"gdb-debug": {
"type": "stdio",
"command": "GdbMiBridge"
}
}
}
```
3. AI 代理现在可以通过 GDB 调试 C/C++ 程序。
## MCP 工具（共 32 个）
### 会话管理
| 工具 | 描述 |
|------|-------------|
| `create` | 启动可执行文件进行调试 |
| `attach` | 通过 PID 附加到正在运行的进程 |
| `load_dump` | 加载核心转储进行事后分析 |
| `detach` | 从调试进程中分离 |
| `terminate` | 终止调试进程 |
| `status` | 查询当前会话状态 |
### 执行控制
| 工具 | 描述 |
|------|-------------|
| `go` | 继续执行直到停止或超时 |
| `step_into` | 单步进入下一条指令 |
| `step_over` | 单步跳过当前行 |
| `step_out` | 执行直到当前函数返回 |
| `go_to` | 通过临时断点运行到指定位置 |
### 断点
| 工具 | 描述 |
|------|-------------|
| `set_breakpoint` | 设置断点（函数、文件:行或地址）并捕获/条件 |
| `remove_breakpoint` | 通过 ID 删除断点 |
| `enable_breakpoint` | 启用断点 |
| `disable_breakpoint` | 禁用断点而不删除它 |
| `list_breakpoints` | 列出当前会话中的所有断点 |
| `set_hardware_breakpoint` | 在内存访问上设置硬件数据断点（监视点） |
### 程序状态
| 工具 | 描述 |
|------|-------------|
| `get_registers` | 获取所有 CPU 寄存器值 |
| `get_program_counter` | 获取程序计数器和符号信息 |
| `read_memory` | 读取地址处的内存 |
| `get_call_stack` | 获取调用栈 |
| `list_threads` | 列出所有线程 |
| `get_local_variables` | 获取帧的局部变量 |
| `capture_state` | 手动捕获寄存器、栈、局部变量 |
| `get_captures` | 获取累积的捕获快照 |
| `clear_captures` | 清除累积的捕获快照 |
### 符号和反汇编
| 工具 | 描述 |
|------|-------------|
| `resolve_symbol` | 将符号名称解析为地址 |
| `address_to_symbol` |查找地址的符号名称 |
| `find_symbols` | 按模式搜索符号 |
| `disassemble` | 反汇编地址处的指令 |
| `list_modules` | 列出加载的共享库 |
### 原始
| 工具 | 描述 |
|------|-------------|
| `raw_gdb` | 执行任意 GDB 命令 |
## 需求
- **GDB** 8.0 或更高版本
- **.NET SDK 10.0** （仅限全局工具安装方法）
## 平台兼容性
该项目仅在 **x86-64 (amd64)** Linux 上进行了测试。虽然大多数 GDB/MI 命令在不同架构上使用相同的格式，但由于以下差异，在其他平台上运行可能会遇到问题：
- **地址宽度** — 32 位 vs 64 位地址格式化在 MI 输出中
- **寄存器名称** — 寄存器集在 x86、ARM、RISC-V 等之间有所不同
- **指令集** — 反汇编输出因架构而异
如果您在 x86、ARM 或其他架构上遇到问题，欢迎贡献和报告错误。
## 架构
```
MCP 客户端（AI 代理） <--stdio/JSON-RPC--> GdbMiBridge.Mcp
|
GdbSession（单个消费者线程）
|
GdbMiClient（MI 协议引擎）
|
GDB 进程
```
所有 GDB I/O 操作都在单个消费者线程上运行，通过 `Channel<SessionOperation>`。MCP 工具处理程序在 MCP 线程池上调用并排队操作。这种设计消除了锁 — 断点管理器、捕获管理器和 MI 协议客户端都共享同一个线程。
## 从源代码构建
```bash
git clone https://github.com/gang2k-coder/GdbMiClient.git
cd GdbMiClient
dotnet build
dotnet test
```
在本地运行 MCP 服务器：
```bash
dotnet run --project src/GdbMiBridge.Mcp
```
## 许可证
MIT — 参见 [LICENSE](LICENSE) 了解详情。
## 致谢
MI 协议引擎（`GdbMiClient` 库）改编自 [Microsoft/MIEngine](https://github.com/microsoft/MIEngine)，该引擎为 Visual Studio 和 VS Code 中的 C/C++ 调试提供支持。我们感谢 MIEngine 作者的优秀工作。
