openmcpgdb (Brosnan Yuen)

openmcpgdb

openmcpgdb 是一个异步Rust MCP服务器，用于通过GDB调试本机程序。 它是通过 rmcp 装箱并暴露一个完整的 gdb_* 用于MCP客户端（Codex、Claude Code、opencode-compatible客户端）的API工具。

特性

• MCP服务器内置 rmcp (tools/list, tools/call 支持）。
• 每个MCP客户端会话有一个专用工作线程。
• 每个客户端的GDB进程隔离。
• 源代码、回溯和监视变量的可配置显示窗口。
• 运输方式：

- https://... 和 http://... 流式HTTP模式（默认） - stdio://... 需要时用于stdio MCP接线

• 包含交互式MCP测试客户端二进制文件。
• 锈蚀测试包括：

- 进程内MCP服务器/客户端连接 - 工具调用覆盖率 - 集成测试 examples/mazerobot/maze_robot

快速开始

1. 下载并运行

git clone https://github.com/BrosnanYuen/openmcpgdb.git
cd openmcpgdb
# Change the settings to point to your codebase and executable
# Use HTTP for server compatibility 
vim config.json
# Run MCP server
cargo run --bin  openmcpgdb  -- config.json 

1. 添加到克劳德代码 claude.json

{
  "mcpServers": {
    "openmcpgdb": {
      "type": "http",
      "url": "http://localhost:9443"
    }
  }
}

1. 添加到Openai Codex config.toml 配置

[mcp_servers.openmcpgdb]
url = "http://localhost:9443"
enabled = true

1. 添加 opencode.json 配置

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "openmcpgdb": {
      "type": "remote",
      "url": "http://localhost:9443",
      "enabled": true
    }
  }
}

1. 提供简短版本指南 LLM_short.md 你的LLM。如果它不起作用，那么使用长版本 法学硕士

需求

• 防锈工具链（稳定）
• GDB位于绝对路径（默认 /usr/bin/gdb)
• 所提供示例的Linux/macOS环境

项目布局

• src/main.rs：服务器入口点
• src/runtime.rs：传输/运行时引导
• src/server.rs：MCP工具布线和处理程序
• src/session.rs：每个客户端工作线程和操作执行
• src/gdb.rs：真实和模拟GDB后端
• src/bin/interactive_client.rs：交互式MCP客户端
• tests/mazerobot_mcp_client.rs：针对mazerobot集成MCP客户端测试
• config.json：默认配置模板

配置

服务器从第一个CLI参数加载JSON配置，默认为 config.json 在项目根中。

所有文件系统路径都必须是绝对的。

例子：

{
  "gdb_path": "/usr/bin/gdb",
  "gdb_options": "",
  "codebase_dir": "/home/brosnan/openmcpgdb/openmcpgdb/examples/mazerobot",
  "executable_path": "/home/brosnan/openmcpgdb/openmcpgdb/examples/mazerobot/maze_robot",
  "mcp_server_name": "MCP GDB Server",
  "mcp_server_url": "https://localhost:9443",
  "display_lines_before_current": 7,
  "display_lines_after_current": 8,
  "display_backtrace": 50,
  "display_variable_list": 20,
  "display_join_current_code": true
}

display_join_current_code 控制方式 current_code 返回：

• false：按行号键控的对象映射
• true：格式为单连接字符串 line | source 带换行符

mcp_server_url

• 违约： https://localhost:9443
• http://host:port/path 或 https://host:port/path：在该绑定地址/路径上运行流式HTTP。
• stdio://...：在stdio上运行MCP。

注： https:// 已解析并接受，但此项目目前直接绑定普通TCP HTTP。对于真正的TLS，在终止TLS的反向代理后面运行。

构建

cargo build

运行MCP服务器

1.默认HTTPS URL模式

使用默认配置：

cargo run --bin openmcpgdb -- config.json

2.HTTP/HTTPS自定义URL模式

设置配置URL，例如：

"mcp_server_url": "https://localhost:9443"

运行：

cargo run --bin openmcpgdb -- config.json

3.可选stdio模式

设置：

"mcp_server_url": "stdio://local"

运行：

cargo run --bin openmcpgdb -- config.json

交互式MCP客户端

包含一个交互式MCP客户端，用于针对HTTP服务器模式进行手动测试。

运行：

cargo run --bin interactive_client -- config.json

输入格式：

本地GDB调试示例：

gdb_execute {"executable_path":"/home/brosnan/openmcpgdb/openmcpgdb/examples/mazerobot/maze_robot"}
gdb_debugger_state {}
gdb_add_variable_list {"var":"robot->sim->robot_row"}
gdb_add_breakpoint {"filename":"/home/brosnan/openmcpgdb/openmcpgdb/examples/mazerobot/src/main.c","linenumber":20}
gdb_run {}
gdb_next {}
gdb_step {}
gdb_print {"var":"counter"}
gdb_full_backtrace {}
gdb_continue {}
gdb_quit {}
gdb_reset_back_to_not_attached {}

在gdbserver上对现有PID进行调试的示例：

gdb_gdbserver {"ip":"127.0.0.1","port":11444,"pid":149104}
gdb_target_remote {"ip":"127.0.0.1","port":11444}
gdb_debugger_state {}
gdb_add_variable_list {"var":"robot->sim->robot_row"}
gdb_add_breakpoint {"filename":"/home/brosnan/openmcpgdb/openmcpgdb/examples/mazerobot/src/main.c","linenumber":20}
gdb_continue {}
gdb_next {}
gdb_step {}
gdb_print {"var":"counter"}
gdb_full_backtrace {}
gdb_quit {}
gdb_reset_back_to_not_attached {}

类型 quit 退出交互式客户端。

与MCP客户端一起使用

此服务器与支持以下任一功能的MCP客户端兼容：

• 基于命令的stdio服务器
• 可流式传输的HTTP服务器

opencode（建议使用stdio）

使用指向以下内容的MCP服务器命令设置：

cargo run --bin openmcpgdb -- /home/brosnan/openmcpgdb/openmcpgdb/config.json

并在config中设置：

"mcp_server_url": "stdio://local"

OpenAI Codex客户

您可以使用以下任一模式：

1. stdio 模式：

• 服务器命令：

cargo run --bin openmcpgdb -- /home/brosnan/openmcpgdb/openmcpgdb/config.json

• 配置URL:

"mcp_server_url": "stdio://local"

1. HTTP模式：

• 使用以下命令运行服务器：

"mcp_server_url": "https://localhost:9443"

• 将客户端MCP端点连接到：

http://localhost:9443

Claude Code客户端

对于本地开发，首选stdio：

cargo run --bin openmcpgdb -- /home/brosnan/openmcpgdb/openmcpgdb/config.json

与：

"mcp_server_url": "stdio://local"

如果使用HTTP传输，请将客户端指向：

http://localhost:9443

重要运输注意事项

https://localhost:9443 在此项目配置中被接受为默认URL形状，但当前服务器绑定是纯HTTP。\ 对于真正的TLS HTTPS，在TLS反向代理后面运行，并在那里公开HTTPS端点。

工具API

所有工具响应包括 debugger_state 以及可选字段，如 variable_list, backtrace, current_code*，以及 error.

debugger_state 价值观

• not attached
• failed to attach
• gdbserver attached
• attached
• stopped at breakpoint
• stopped at stepping
• running
• sigsegv
• sigabrt
• sigbus
• sigfpe
• sigill
• sigtrap
• sigterm
• sigkill
• exited
• error

执行/会话

• gdb_execute(executable_path)
• gdb_run()
• gdb_gdbserver(ip, port, pid)
• gdb_target_remote(ip, port)
• gdb_set_thread(id)
• gdb_set_frame(id)

断点

• gdb_add_breakpoint(filename, linenumber)
• gdb_clear_breakpoint(filename, linenumber)
• gdb_enable_breakpoint(filename, linenumber)
• gdb_disable_breakpoint(filename, linenumber)
• gdb_list_breakpoint()

步进

• gdb_next()
• gdb_step()
• gdb_continue()
• gdb_interrupt()

可变观察名单

• gdb_add_variable_list(var)
• gdb_del_variable_list(var)
• gdb_variable_list()

检查

• gdb_debugger_state()
• gdb_current_code()
• gdb_full_backtrace()
• gdb_info_threads()
• gdb_info_regs()
• gdb_print(var)
• gdb_set_var(var, value)

控制/配置/自定义

• gdb_quit()
• gdb_kill()
• gdb_reset_back_to_not_attached()
• gdb_display_lines_before_current(size)
• gdb_display_lines_after_current(size)
• gdb_display_backtrace(size)
• gdb_display_variable_list(size)
• gdb_custom(cmd)

测试

运行所有测试：

cargo test

包括测试覆盖范围：

• MCP服务器启动，MCP客户端连接。
• 单元式所有工具调用响应检查。
• 通过以下方式启动MCP服务器的集成测试：

- 代码库： /home/brosnan/openmcpgdb/openmcpgdb/examples/mazerobot/ - 二元的： /home/brosnan/openmcpgdb/openmcpgdb/examples/mazerobot/maze_robot - MCP客户端 tests/mazerobot_mcp_client.rs