内容
# GdbMiClient
[](https://github.com/gang2k-coder/GdbMiBridge/actions/workflows/ci.yml)
[](https://www.nuget.org/packages/GdbMiClient/)
[](https://www.nuget.org/packages/GdbMiBridge.Mcp/)
[](LICENSE)
.NET 的 GDB 机器接口（MI）客户端，带有全功能的 MCP 服务器，为 AI 代理提供 34 种调试工具。
## 软件包
| 软件包 | 类型 | 描述 |
|---------|------|-------------|
| **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/GdbMiBridge/master/install.sh | bash
```
无需依赖 — 二进制文件捆绑了 .NET 运行时。支持 `linux-x64` 和 `linux-arm64`。
或者直接从 [GitHub Releases](https://github.com/gang2k-coder/GdbMiBridge/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 工具（共 34 种）
### 会话管理
| 工具 | 描述 |
|------|-------------|
| `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` | 清除累积的捕获快照 |
| `set_default_capture_granularity` | 设置会话范围的捕获默认值（寄存器/栈/变量） |
| `get_default_capture_granularity` | 查询当前捕获粒度设置 |
### 符号和反汇编
| 工具 | 描述 |
|------|-------------|
| `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 代理） <--标准输入/输出/JSON-RPC--> GdbMiBridge.Mcp
|
GdbSession（单个消费者线程）
|
GdbMiClient（MI 协议引擎）
|
GDB 进程
```
所有 GDB 输入/输出操作都在单个消费者线程上运行，借助 `Channel<SessionOperation>` 实现。MCP 工具处理程序在 MCP 线程池上调用并排队操作。这种设计消除了锁 — 断点管理器、捕获管理器和 MI 协议客户端都共享同一个线程。
## 从源代码构建
```bash
git clone https://github.com/gang2k-coder/GdbMiBridge.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 作者的优秀工作。
