内容
<div align="center">
[🇨🇳 中文](README_CN.md) | 🇬🇧 English
</div>
---
# LLDB MCP 服务器
LLDB MCP 服务器 — 将 LLDB 调试器封装为 [模型上下文协议（MCP）](https://modelcontextprotocol.io) 服务器，使 AI 助手（Claude、OpenCode 等）能够设置断点、单步执行代码、检查变量等 — 所有操作都通过标准 MCP 接口。
## 功能概述
| 类别 | 工具 | 描述 |
|----------|------|-------------|
| 会话 | `lldb_start` | 启动新的 LLDB 会话 |
| | `lldb_list_sessions` | 列出所有活动会话 |
| | `lldb_terminate` | 终止会话 |
| 程序控制 | `lldb_load` | 加载程序进行调试 |
| | `lldb_attach` | 附加到正在运行的进程 |
| | `lldb_load_core` | 加载核心转储文件 |
| | `lldb_run` | 运行加载的程序 |
| | `lldb_continue` | 继续执行 |
| | `lldb_kill` | 杀死正在运行的进程 |
| 断点 | `lldb_set_breakpoint` | 设置断点（可选条件） |
| | `lldb_breakpoint_list` | 列出所有断点 |
| | `lldb_breakpoint_delete` | 删除断点 |
| | `lldb_watchpoint` | 设置内存监视点 |
| 步进 | `lldb_step` | 步入函数调用 |
| | `lldb_next` | 跳过函数调用 |
| | `lldb_finish` | 运行直到当前函数返回 |
| 检查 | `lldb_print` | 打印变量/表达式值 |
| | `lldb_expression` | 在当前帧中评估表达式 |
| | `lldb_examine` | 检查内存 |
| | `lldb_info_registers` | 显示寄存器 |
| | `lldb_disassemble` | 反汇编代码 |
| | `lldb_process_info` | 显示进程信息 |
| 堆栈/线程 | `lldb_backtrace` | 显示调用堆栈 |
| | `lldb_frame_info` | 显示帧详细信息（带有局部变量） |
| | `lldb_thread_list` | 列出所有线程 |
| | `lldb_thread_select` | 选择特定线程 |
| 其他 | `lldb_command` | 执行任意 LLDB 命令 |
| | `lldb_help` | 显示 LLDB 帮助 |
**29种工具**，涵盖完整的 LLDB 调试工作流。
## 构建
### 依赖项
- **CMake** >= 3.16
- **Boost** >= 1.79（`filesystem` 和 `json` 组件）
- **C++17** 编译器
- **LLDB**（仅运行时；包含在 macOS 中，Linux 上单独安装）
### 编译
```bash
mkdir build && cd build
cmake ..
make -j$(nproc)
```
输出二进制文件为 `build/lldb-mcp`。
### 安装 Boost（macOS）
```bash
brew install boost
```
### 安装 Boost（Linux）
```bash
apt install libboost-filesystem-dev libboost-json-dev
# 或
yum install boost-devel
```
## 用法
### 命令行
```bash
./lldb-mcp [--debug]
```
- `--debug` — 将调试日志打印到 stderr（不会干扰 MCP 协议）
- `-h` / `--help` — 打印帮助
程序从 stdin 读取 JSON-RPC 消息，并通过 stdout 响应。支持两种传输模式：
- **换行分隔的 JSON**
- **HTTP 样式的 Content-Length 头部**
### MCP 服务器配置
添加到 AI 助手的 MCP 配置中（OpenCode 示例，`opencode.json`）：
```json
{
"mcpServers": {
"lldb-mcp": {
"command": "/path/to/lldb-mcp",
"args": []
}
}
}
```
## 示例
通过 MCP 接口调试斐波那契程序：
```
1. lldb_start # 启动 LLDB 会话
2. lldb_load(session_id, "test_rec") # 加载程序
3. lldb_set_breakpoint(session_id, "fib") # 在 fib() 处设置断点
4. lldb_run(session_id) # 运行 — 命中断点
5. lldb_print(session_id, "n") # 打印参数 n
6. lldb_backtrace(session_id) # 显示调用堆栈
7. lldb_step(session_id) # 步入递归
8. lldb_continue(session_id) # 继续执行
9. lldb_terminate(session_id) # 结束会话
```
## 项目结构
```
lldb-mcp/
├── CMakeLists.txt # CMake 构建配置
├── src/
│ ├── main.cpp # 入口点，CLI 解析，MCP 服务器启动
│ ├── lldb_session.hpp/cpp # LLDB 会话管理（PTY 分叉 + 命令执行）
│ ├── mcp_server.hpp/cpp # MCP 协议（JSON-RPC，传输检测）
│ └── mcp_tools.hpp/cpp # 工具注册和调度
└── tests/
├── test_rec.c # 测试程序：递归斐波那契
├── test_bug.c # 测试程序：有 bug 的阶乘
└── test_args.c # 测试程序：打印命令行参数
```
### 架构
```
┌──────────┐ stdin (JSON-RPC) ┌───────────┐ PTY ┌──────┐
│ AI 代理 │ ◄──────────────────► MCP 服务器 │ ◄───────► LLDB │
└──────────┘ stdout └───────────┘ fork+io └──────┘
```
- **MCP 服务器** 通过 stdin/stdout 与 AI 代理通信，并自动检测传输格式
- **LldbSession** 在子进程中启动 LLDB，通过 PTY（伪终端）进行双向 I/O
- **McpTools** 将所有 29 种工具映射到 LLDB 命令，并具有统一的错误处理
## 参考
基于以下技术构建：
- [模型上下文协议（MCP）](https://modelcontextprotocol.io) — Anthropic 的 AI 工具集成协议
- [LLDB 调试器](https://lldb.llvm.org) — LLVM 项目调试器
- [Boost C++ 库](https://www.boost.org) — 高质量 C++ 库集合
- [OpenCode](https://github.com/anomalyco/opencode) — 支持 MCP 的 AI 编程助手
## 许可证
MIT
