# GDB MCP Server

MCP服务器，用于AI Agent调试嵌入式系统程序。支持交叉编译GDB工具（aarch64、arm等），远程调试（gdbserver/QEMU），提供完整的调试信息查询功能。

## 功能特性

- **多架构支持**: aarch64-none-linux-gnu-gdb, arm-none-eabi-gdb, x86_64-gdb
- **远程调试**: 连接目标板的gdbserver或QEMU模拟器
- **条件断点**: 支持条件表达式断点
- **完整调试信息**: 寄存器、内存、堆栈、变量、线程等
- **MCP集成**: 作为Claude Code或其他MCP客户端的工具使用

## 快速开始

### 1. 安装

```bash
npm install
npm run build
```

### 2. 配置MCP客户端

在Claude Code的设置中添加：

```json
{
  "mcpServers": {
    "gdb": {
      "command": "node",
      "args": ["C:/Users/zjm09/Documents/work/2025/gdb-mcp/dist/index.js"]
    }
  }
}
```

### 3. 使用MCP工具

```
# 初始化GDB
gdb_init({architecture: "aarch64"})

# 连接目标
gdb_connect({target: "localhost:1234"})

# 加载程序
gdb_load_program({programPath: "./main"})

# 设置断点
gdb_set_breakpoint({location: "main.c:10"})
gdb_set_breakpoint({location: "factorial", condition: "n==0"})  # 条件断点

# 执行调试
gdb_run()
gdb_step()
gdb_next()

# 查看信息
gdb_list_registers()
gdb_read_registers({registers: ["pc", "sp"]})
gdb_list_locals()
gdb_evaluate_expression({expression: "x"})
```

## 工具列表

### 连接管理
| 工具 | 描述 |
|------|------|
| `gdb_init` | 启动GDB进程 |
| `gdb_connect` | 连接远程目标 |
| `gdb_disconnect` | 断开并终止GDB |
| `gdb_load_program` | 加载可执行文件 |

### 执行控制
| 工具 | 描述 |
|------|------|
| `gdb_run` | 开始执行 |
| `gdb_continue` | 继续执行 |
| `gdb_step` | 单步进入函数 |
| `gdb_next` | 单步跳过函数 |
| `gdb_finish` | 执行到返回 |
| `gdb_interrupt` | 中断执行 |

### 断点管理
| 工具 | 描述 |
|------|------|
| `gdb_set_breakpoint` | 设置断点（支持条件） |
| `gdb_delete_breakpoint` | 删除断点 |
| `gdb_list_breakpoints` | 列出断点 |
| `gdb_enable_breakpoint` | 启用断点 |
| `gdb_disable_breakpoint` | 禁用断点 |
| `gdb_set_condition` | 设置断点条件 |

### 内存/寄存器
| 工具 | 描述 |
|------|------|
| `gdb_read_memory` | 读取内存 |
| `gdb_list_registers` | 列出寄存器名 |
| `gdb_read_registers` | 读取寄存器值 |
| `gdb_write_register` | 写入寄存器 |

### 堆栈/变量
| 工具 | 描述 |
|------|------|
| `gdb_list_frames` | 列出调用栈 |
| `gdb_select_frame` | 选择栈帧 |
| `gdb_list_locals` | 列出局部变量 |
| `gdb_list_arguments` | 列出函数参数 |
| `gdb_evaluate_expression` | 计算表达式 |

### 线程管理
| 工具 | 描述 |
|------|------|
| `gdb_list_threads` | 列出线程 |
| `gdb_select_thread` | 选择线程 |

### 调试信息
| 工具 | 描述 |
|------|------|
| `gdb_get_current_location` | 获取当前位置 |
| `gdb_list_source_files` | 列出源文件 |
| `gdb_disassemble` | 反汇编 |

### 高级
| 工具 | 描述 |
|------|------|
| `gdb_command` | 执行原始GDB MI命令 |

## 测试

### 使用QEMU模拟

```bash
cd tests/test-program
make                # 交叉编译
bash start-qemu.sh  # 启动QEMU等待GDB连接
```

### 测试流程

1. 启动QEMU后，使用MCP工具连接
2. 设置断点、执行调试
3. 查看变量、寄存器等调试信息

## 项目结构

```
gdb-mcp/
├── src/
│   ├── index.ts           # MCP服务器入口
│   ├── gdb/
│   │   ├── gdb-process.ts # GDB进程管理
│   │   ├── mi-parser.ts   # MI输出解析
│   │   ├── mi-commands.ts # MI命令构建
│   │   └── types.ts       # 类型定义
│   ├── schemas/           # Zod验证
│   └── constants.ts       # 配置常量
├── tests/
│   └ test-program/        # 测试程序
│   └ README.md
│   └ tsconfig.json
│   └ package.json
```

## 开发

```bash
npm run dev      # 开发模式（自动重载）
npm run build    # 编译
npm run inspector # 使用MCP Inspector测试
```

## 许可证

MIT