Skip to content

README_CN.md

Latest commit

 

History

History
201 lines (146 loc) · 5.88 KB

README_CN.md

File metadata and controls

201 lines (146 loc) · 5.88 KB

mcp-gdb

中文 | English

一个 Model Context Protocol (MCP) 服务器，用于 Linux 下的 GDB 调试 — core dump 分析、远程调试和直接程序调试。

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

功能

  • Core dump 分析 — 打开 core 文件，查看线程、堆栈回溯和共享库
  • 远程调试 — 通过 host:port 连接 gdbserver 远程目标
  • 直接程序调试 — 在 GDB 下启动程序，设置断点、单步执行、查看变量
  • 会话管理 — 支持多个并发调试会话，自动复用已有会话
  • 可配置超时 — 初始化超时（符号加载）和命令执行超时分别配置
  • Debuginfod 控制 — 可禁用自动符号下载，适用于网络受限环境
  • Strip 程序支持 — 通过 debug_info_directory 和 sysroot 配置分离的调试信息

前置要求

  • Linux
  • GDB

如果未安装 GDB：

# Debian/Ubuntu
sudo apt install gdb

# RHEL/CentOS/Fedora
sudo dnf install gdb

# Arch
sudo pacman -S gdb

服务器会自动从 PATH 和 Linux 常见路径（/usr/bin/gdb、/usr/local/bin/gdb）中查找 GDB。

安装

从源码构建

git clone https://github.com/FlorentinoJink/mcp-gdb.git
cd mcp-gdb
cargo build --release

可执行文件：target/release/mcp-gdb

配置

VS Code / Kiro

.vscode/mcp.json：

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

Claude Desktop / Cline / 其他 MCP 客户端

{
  "mcpServers": {
    "mcp-gdb": {
      "command": "mcp-gdb",
      "args": []
    }
  }
}

环境变量

变量 说明 默认值
GDB_PATH 自定义 GDB 可执行文件路径 自动查找
MCP_GDB_TIMEOUT 命令执行超时（秒） 30
MCP_GDB_INIT_TIMEOUT 初始化超时，用于符号加载（秒） 120
MCP_GDB_VERBOSE 详细日志（true/false） false
MCP_GDB_DISABLE_DEBUGINFOD 禁用 debuginfod 自动符号下载（true/false） false

命令行选项

mcp-gdb [选项]

  --timeout <秒数>          命令执行超时（默认：30）
  --init-timeout <秒数>     初始化超时（默认：120）
  --verbose                 启用详细日志
  --disable-debuginfod      禁用 debuginfod 自动符号下载

工具列表

工具 说明
open_gdb_core 打开并分析 Linux core dump 文件
open_gdb_remote 连接 gdbserver 远程调试目标
launch_debug 在 GDB 下启动程序进行调试
run_gdb_cmd 在已有会话中执行任意 GDB 命令
close_gdb_core 关闭 core dump 分析会话
close_gdb_remote 关闭远程调试会话
close_debug 关闭调试会话并终止目标程序
list_core_dumps 列出目录中的 core dump 文件

使用示例

Core Dump 分析

分析 /tmp/core.12345 这个 core dump 文件

远程调试

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

直接调试程序

启动程序、设置断点、单步执行：

启动 /home/user/myapp 进行调试

然后用 run_gdb_cmd 控制执行：

break main       — 在 main 设置断点
run              — 开始执行
next             — 单步跳过
step             — 单步进入
bt               — 查看堆栈回溯
info locals      — 查看局部变量
list             — 显示当前位置的源码
continue         — 继续执行

launch_debug 工具支持以下可选参数：

参数 类型 说明
program_path string 目标程序路径（必填）
arguments string[] 命令行参数
working_directory string 工作目录
debug_info_directory string 分离的调试信息路径（用于 strip 过的程序）
source_path string 源文件搜索路径
include_backtrace boolean 包含初始堆栈回溯
include_modules boolean 包含共享库列表

open_gdb_core 工具支持以下可选参数：

参数 类型 说明
core_dump_path string Core dump 文件路径（必填）
executable_path string 可执行文件路径（用于加载符号）
include_backtrace boolean 包含堆栈回溯
include_threads boolean 包含线程列表
include_shared_libraries boolean 包含共享库列表
debug_info_directory string 分离的调试信息目录路径
sysroot string 目标系统根路径（用于交叉调试）

关闭会话

关闭 /home/user/myapp 的调试会话

故障排除

找不到 GDB — 通过包管理器安装（apt install gdb、dnf install gdb），或设置 GDB_PATH 指向 GDB 路径。

符号下载阻塞 GDB — 使用 --disable-debuginfod 或设置 MCP_GDB_DISABLE_DEBUGINFOD=true 禁止 GDB 从网络下载符号。

命令超时 — 通过 --timeout 60 或 MCP_GDB_TIMEOUT=60 增加超时。大型 core dump 和符号加载可能需要更高的 MCP_GDB_INIT_TIMEOUT。

容器中 ptrace 报错 — 如果在 Docker/容器中运行，添加 --cap-add=SYS_PTRACE 到 docker run 命令。OrbStack 等轻量级虚拟机对 ptrace 的支持可能有限。

Strip 过的程序 — 使用 debug_info_directory 参数指向分离的调试信息（通常在 /usr/lib/debug/）。安装调试符号包：apt install <包名>-dbg 或 dnf debuginfo-install <包名>。

相关链接

许可证

AGPL-3.0-or-later