内容
[中文文档](README_CN.md) | English
# mcp-lldb
LLDB 的模型上下文协议（MCP）服务器 — 核心转储分析、远程调试和在 macOS 上进行程序调试。
使用 Rust 和 Tokio 构建，支持异步 I/O。单个可执行文件，无运行时依赖。
## 功能
- **核心转储分析** — 打开核心文件，检查线程、堆栈跟踪和共享库
- **远程调试** — 通过 `host:port` 连接到 `debugserver` 目标
- **直接程序调试** — 在 LLDB 下启动可执行文件，设置断点，单步执行代码，检查变量
- **会话管理** — 多个并发调试会话，自动重用和过期会话清理
- **macOS 平台支持** — DevToolsSecurity 检测，SIP 路径感知，通用二进制架构选择，dSYM 符号加载
- **崩溃文件搜索** — 从 macOS 系统路径定位 `.ips`、`.crash` 和核心转储文件
## 前置条件
- macOS
- LLDB（随 Xcode 命令行工具附带）
如果 LLDB 未安装：
```bash
xcode-select --install
```
服务器自动从 `PATH` 和常见的 macOS 路径发现 LLDB：
- `/usr/bin/lldb`
- `/usr/local/bin/lldb`
- `/Applications/Xcode.app/Contents/Developer/usr/bin/lldb`
- `/Library/Developer/CommandLineTools/usr/bin/lldb`
## 安装
### 从源码
```bash
git clone https://github.com/FlorentinoJink/mcp-lldb.git
cd mcp-lldb
cargo build --release
```
二进制文件：`target/release/mcp-lldb`
## 配置
### VS Code / Kiro
`.vscode/mcp.json`:
```json
{
"servers": {
"mcp-lldb": {
"type": "stdio",
"command": "/path/to/mcp-lldb",
"args": []
}
}
}
```
### Claude Desktop / Cline / 其他 MCP 客户端
```json
{
"mcpServers": {
"mcp-lldb": {
"command": "/path/to/mcp-lldb",
"args": []
}
}
}
```
## 环境变量
| 变量 | 描述 | 默认值 |
|---|---|---|
| `LLDB_PATH` | LLDB 可执行文件的自定义路径 | 自动发现 |
| `MCP_LLDB_TIMEOUT` | 命令执行超时（秒） | 30 |
| `MCP_LLDB_INIT_TIMEOUT` | 符号加载的初始化超时（秒） | 120 |
| `MCP_LLDB_VERBOSE` | 详细日志记录（`true`/`false`） | false |
## 命令行选项
```
mcp-lldb [选项]
--timeout <SECONDS> 命令执行超时（默认：30）
--init-timeout <SECONDS> 初始化超时（默认：120）
--verbose 启用详细日志记录
```
## 工具
| 工具 | 描述 |
|---|---|
| `open_lldb_core` | 打开并分析 macOS 核心转储文件 |
| `open_lldb_remote` | 连接到 debugserver 远程调试目标 |
| `launch_debug` | 在 LLDB 下启动程序进行调试 |
| `run_lldb_cmd` | 在现有会话中执行 LLDB 命令 |
| `close_lldb_core` | 关闭核心转储分析会话 |
| `close_lldb_remote` | 关闭远程调试会话 |
| `close_debug` | 关闭启动调试会话并终止程序 |
| `list_crash_files` | 列出 macOS 上的核心转储和崩溃报告文件 |
## 使用示例
### 核心转储分析
```
分析位于 /cores/core.12345 的核心转储
```
### 远程调试
在远程端启动 `debugserver`：
```bash
debugserver 0.0.0.0:1234 /path/to/executable
```
然后连接：
```
连接到 192.168.1.100:1234 处的 debugserver 并显示当前状态
```
### 直接程序调试
```
启动 /usr/local/bin/myapp 进行调试
```
然后使用 `run_lldb_cmd` 控制执行：
```
breakpoint set --file main.cc --line 42 — 设置断点
run — 启动执行
next — 跳过
step — 步入
thread backtrace all — 完整回溯
frame variable — 查看局部变量
image list — 显示已加载模块
continue — 继续执行
```
### 通用二进制
```
启动 /path/to/app 进行调试，架构为 arm64
```
## 故障排除
**LLDB 未找到** — 通过 `xcode-select --install` 安装或将 `LLDB_PATH` 设置为您的 LLDB 位置。
**DevToolsSecurity 未启用** — 运行 `sudo DevToolsSecurity -enable` 以允许调试。
**SIP 保护的路径** — 在启用 SIP 的情况下，`/usr/bin/`、`/System/` 等系统进程无法调试。
**强化运行时** — 具有强化运行时的应用程序需要 `com.apple.security.get-task-allow` 权限，或者使用 `codesign --remove-signature <path>` 删除签名。
**未生成核心转储** — macOS 默认禁用核心转储。启用方法：`ulimit -c unlimited`。注意：SIP 可能会阻止写入 `/cores/`。
**命令超时** — 使用 `--timeout 60` 或 `MCP_LLDB_TIMEOUT=60` 增加超时时间。
## 相关
- [mcp-gdb](https://github.com/FlorentinoJink/mcp-gdb) — Linux GDB 调试的 MCP 服务器
- [模型上下文协议](https://modelcontextprotocol.io)
- [LLDB 文档](https://lldb.llvm.org)
## 许可证
AGPL-3.0-or-later
