FYTJ/gdb-mcp-server

GDB MCP Server

语言: |

概述

一个可通过 MCP 工具调用 GDB 的服务器，提供会话管理、目标/进程控制、断点、执行控制、栈与变量、表达式、内存读写与事件轮询。

环境要求

• Ubuntu Linux，安装 gdb（>= 9.0）。
• Python 3.10+。

配置 config.json

• 位置：项目根目录 config.json，运行时自动加载，亦可通过环境变量 GDB_MCP_CONFIG=/path/to/config.json 指定。

• 关键字段：

  • log_dir：日志目录，默认 logs（不存在时会自动创建）。
  • server_host/server_port：TCP 监听地址与端口（用于 --listen 模式）。
  • allowed_root：可调试的根目录限制（可选，提升安全性）。
  • GDB 无需 Python 绑定路径配置；仅需系统安装 gdb 即可。
  • project_root：项目根目录绝对路径（如 $(pwd)）。
  • src_path：源码路径（通常为 <project_root>/src）。
  • client.target_bin：示例客户端默认的被调试可执行路径；也可用环境变量 TARGET_BIN 覆盖。

• 如何找到路径：

  • lldb -P 获取 Python 路径（优先使用）。
  • which python3 或 Xcode .../usr/bin/python3 设为 python_executable。
  • xcode-select -p 得到 ${DEVROOT}；将以上两类 Framework 路径加入 framework_paths。
  • 其余字段按本机实际路径填写即可。

安全配置

• GDB_MCP_ALLOW_LAUNCH=1 允许 launch
• GDB_MCP_ALLOW_ATTACH=1 允许 attach
• GDB_MCP_ALLOWED_ROOT=/path/to/dir 限定可调试路径（可选）

运行（网络模式 TCP）

• 启动服务端：PYTHONPATH=src GDB_MCP_ALLOW_LAUNCH=1 GDB_MCP_ALLOWED_ROOT=$(pwd)/examples/client/c_test/hello PYTHONUNBUFFERED=1 python3 -u -m gdb_mcp_server.mcp.server --listen 127.0.0.1:8765
• 示例：
  • 创建会话： {"id":"1","method":"initialize","params":{}}
  • 创建目标： {"id":"2","method":"createTarget","params":{"sessionId":"<SID>","file":"/path/app"}}
  • 启动进程： {"id":"3","method":"launch","params":{"sessionId":"<SID>","args":[]}}
  • 轮询事件： {"id":"4","method":"pollEvents","params":{"sessionId":"<SID>","limit":32}}
    • 通过 pollEvents 获取事件列表，示例类型：
      • targetCreated：目标创建
      • processLaunched/processAttached：进程启动或附加
      • processStateChanged：进程状态变化（running/stopped/exited 等）
      • breakpointSet/breakpointHit：断点设置与命中（含线程和帧信息）
      • stdout/stderr：进程输出抓取

客户端示例（仅网络模式）

• 示例客户端：
  • 入口：MCP_HOST=127.0.0.1 MCP_PORT=8765 python3 examples/client/run_debug_flow.py
  • 准备：cd examples/client/c_test/hello && cc -g -O0 -o hello hello.c 并设置 TARGET_BIN=$(pwd)/hello

一键启动

• 构建示例目标：cd examples/client/c_test/hello && cc -g -O0 -Wall -Wextra -o hello hello.c
• 启动服务端：PYTHONPATH=src GDB_MCP_ALLOW_LAUNCH=1 GDB_MCP_ALLOWED_ROOT=$(pwd)/examples/client/c_test/hello PYTHONUNBUFFERED=1 python3 -u -m gdb_mcp_server.mcp.server --listen 127.0.0.1:8765
• 启动客户端：TARGET_BIN=$(pwd)/examples/client/c_test/hello/hello MCP_HOST=127.0.0.1 MCP_PORT=8765 python3 examples/client/run_debug_flow.py

常见问题

• No module named gdb：请确认系统已安装 gdb 并可执行；本项目使用 pygdbmi 通过 MI 接口调用 gdb，无需 import gdb 的 Python 绑定。
• ptrace 权限限制：在 WSL/容器/严格安全策略环境中，run 可能提示 Could not trace the inferior 或 ptrace: 不允许的操作 并退出 127。解决：
  • Ubuntu/WSL：执行 sudo sysctl kernel.yama.ptrace_scope=0（临时），或写入 /etc/sysctl.d/10-ptrace.conf 持久化并 sudo sysctl --system。
  • Docker：使用 --cap-add=SYS_PTRACE 运行容器；或在容器内放宽 ptrace_scope。
  • 受限主机：联系管理员放宽调试权限，或以 root 运行。