Skip to content

README_CN.md

Latest commit

 

History

History
179 lines (127 loc) · 4.82 KB

README_CN.md

File metadata and controls

179 lines (127 loc) · 4.82 KB

中文文档 | English

mcp-lldb

基于 Model Context Protocol (MCP) 的 LLDB 调试服务器，支持 macOS 平台的 core dump 分析、远程调试和程序调试。

使用 Rust 和 Tokio 异步 I/O 构建，编译为单一可执行文件，无运行时依赖。

功能特性

  • Core dump 分析 — 打开 core 文件，检查线程、调用栈和共享库
  • 远程调试 — 通过 host:port 连接 debugserver 目标
  • 程序调试 — 在 LLDB 下启动可执行文件，设置断点、单步执行、检查变量
  • 会话管理 — 支持多个并发调试会话，自动复用，失效会话自动清理
  • macOS 平台支持 — DevToolsSecurity 检测、SIP 路径感知、Universal Binary 架构选择、dSYM 符号加载
  • 崩溃文件搜索 — 从 macOS 系统路径定位 .ips、.crash 和 core dump 文件

前置条件

  • macOS
  • LLDB（随 Xcode 命令行工具安装）

如果未安装 LLDB：

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

安装

从源码编译

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：

{
  "servers": {
    "mcp-lldb": {
      "type": "stdio",
      "command": "/path/to/mcp-lldb",
      "args": []
    }
  }
}

Claude Desktop / Cline / 其他 MCP 客户端

{
  "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

CLI 选项

mcp-lldb [OPTIONS]

  --timeout <SECONDS>        命令执行超时时间（默认：30）
  --init-timeout <SECONDS>   初始化超时时间（默认：120）
  --verbose                  启用详细日志

工具列表

工具 说明
open_lldb_core 打开并分析 macOS core dump 文件
open_lldb_remote 连接 debugserver 远程调试目标
launch_debug 在 LLDB 下启动程序进行调试
run_lldb_cmd 在已有会话中执行 LLDB 命令
close_lldb_core 关闭 core dump 分析会话
close_lldb_remote 关闭远程调试会话
close_debug 关闭程序调试会话并终止程序
list_crash_files 列出 macOS 系统中的 core dump 和崩溃报告文件

使用示例

Core Dump 分析

分析 /cores/core.12345 的 core dump 文件

远程调试

在远程端启动 debugserver：

debugserver 0.0.0.0:1234 /path/to/executable

然后连接：

连接到 192.168.1.100:1234 的 debugserver 并显示当前状态

程序调试

在 LLDB 下启动 /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                                   — 继续执行

Universal Binary

以 arm64 架构启动 /path/to/app 进行调试

常见问题

找不到 LLDB — 通过 xcode-select --install 安装，或设置 LLDB_PATH 指向 LLDB 路径。

DevToolsSecurity 未启用 — 运行 sudo DevToolsSecurity -enable 以允许调试器附加进程。

SIP 保护路径 — 启用 SIP 时，/usr/bin/、/System/ 等路径下的系统进程无法被调试。

Hardened Runtime — 启用了加固运行时的应用需要 com.apple.security.get-task-allow entitlement，或使用 codesign --remove-signature <path> 移除签名后重试。

Core dump 未生成 — macOS 默认禁用 core dump，使用 ulimit -c unlimited 启用。注意：SIP 可能阻止向 /cores/ 目录写入。

命令超时 — 使用 --timeout 60 或 MCP_LLDB_TIMEOUT=60 增加超时时间。

相关项目

许可证

AGPL-3.0-or-later