girb MCP

调试mcp

日本语版（Japanese）

MCP（模型上下文协议）服务器，将LLM代理连接到Ruby 调试gem，使他们能够访问暂停的Ruby进程的运行时上下文。

LLM代理可以通过MCP工具调用连接到暂停的Ruby进程、检查变量、评估代码、设置断点和控制执行。

它做什么

现有的Ruby/Rails MCP服务器只提供静态分析或应用程序级API。debug mcp更进一步：它连接到 运行Ruby进程 通过调试gem，并将其运行时状态暴露给LLM代理。

Agent → connect(host: "localhost", port: 12345)
Agent → get_context()
  → local variables, instance variables, call stack
Agent → evaluate_code(code: "user.valid?")
  → false
Agent → evaluate_code(code: "user.errors.full_messages")
  → ["Email can't be blank"]
Agent → continue_execution()

安装

gem "debug-mcp"

或直接安装：

gem install debug-mcp

需要Ruby>=3.2.0。

从以下位置迁移 girb-mcp? 此gem之前发布为 girb-mcp RubyGems（最新版本：0.1.1）。它被重命名为 debug-mcp 从...开始 0.1.2以更好地反映其目的。替换 gem "girb-mcp" 和 gem "debug-mcp" 并更新您的MCP客户端配置(girb-mcp → debug-mcp, girb-rails → debug-rails).看 更改日志.md 了解详情。

快速开始

1.使用调试器启动Ruby进程

# Script
rdbg --open --port=12345 my_script.rb

# Or with environment variables
RUBY_DEBUG_OPEN=true RUBY_DEBUG_PORT=12345 ruby my_script.rb

# Or add `debugger` / `binding.break` in your code and run with rdbg
rdbg --open my_script.rb

2.配置您的MCP客户端

debug mcp适用于任何兼容mcp的客户端。将其添加到客户端的MCP服务器配置中：

克劳德代码

添加 ~/.claude/settings.json （或项目 .claude/settings.json):

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

如果使用Bundler：

{
  "mcpServers": {
    "debug-mcp": {
      "command": "bundle",
      "args": ["exec", "debug-mcp"]
    }
  }
}

Gemini CLI

添加 ~/.gemini/settings.json:

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

如果使用Bundler：

{
  "mcpServers": {
    "debug-mcp": {
      "command": "bundle",
      "args": ["exec", "debug-mcp"]
    }
  }
}

3.开始调试

请您的代理连接并调试：

“连接到端口12345上的调试会话，并向我显示当前状态”

“在app/models/user.rb第42行设置断点，并向/users/1发送GET请求”

用法

Usage: debug-mcp [options]
    -t, --transport TRANSPORT        Transport type: stdio (default) or http
    -p, --port PORT                  HTTP port (default: 6029, only for http transport)
        --host HOST                  HTTP host (default: 127.0.0.1, only for http transport)
        --session-timeout SECONDS    Session timeout in seconds (default: 1800)
    -v, --version                    Show version
    -h, --help                       Show this help

STDIO传输（默认）

MCP客户端的标准传输。无需额外配置。

debug-mcp

HTTP传输（流式HTTP）

适用于基于浏览器的客户端或其他HTTP兼容的MCP客户端。

debug-mcp --transport http --port 8080

MCP端点将在 http://127.0.0.1:8080/mcp.

会话超时

调试会话在30分钟不活动后会自动清理。调整如下：

debug-mcp --session-timeout 3600  # 1 hour

会话管理器还检测并清理目标进程已退出的会话。

工具

发现与连接

调查

执行控制

入口点

Rails工具（自动检测）

当检测到Rails进程时，这些工具会自动注册。

工作流

调试Ruby脚本

Agent: run_script(file: "my_script.rb")
Agent: get_context()
Agent: evaluate_code(code: "result")
Agent: next()
Agent: evaluate_code(code: "result")
Agent: continue_execution()

方法断点

Agent: run_script(file: "my_script.rb", breakpoints: ["DataPipeline#validate"])
  → Script starts and pauses at DataPipeline#validate
Agent: evaluate_code(code: "records")
Agent: continue_execution()

捕获和调试异常

Agent: run_script(file: "my_script.rb")
Agent: set_breakpoint(exception_class: "NoMethodError")
Agent: continue_execution()
  → Execution pauses BEFORE the exception propagates
Agent: get_context()
Agent: evaluate_code(code: "$!.message")

崩溃后重新启动

  → Program crashed with NoMethodError
Agent: run_script(file: "my_script.rb", restore_breakpoints: true)
  → Same breakpoints restored automatically
Agent: set_breakpoint(exception_class: "NoMethodError")
Agent: continue_execution()
  → Catches the exception before it crashes

调试Rails请求

使用启用调试的方式启动Rails服务器 debug-rails:

debug-rails                # equivalent to RUBY_DEBUG_OPEN=true bin/rails server
debug-rails s -p 4000      # specify port
debug-rails --debug-port 3333  # use specific TCP debug port (useful in Docker)

然后让代理进行调试：

Agent: connect()
Agent: set_breakpoint(file: "app/controllers/users_controller.rb", line: 15)
Agent: trigger_request(method: "GET", url: "http://localhost:3000/users/1")
Agent: get_context()
Agent: evaluate_code(code: "@user.attributes")
Agent: continue_execution()

调试一个Docker化的Rails应用程序

安全说明： 调试gem没有身份验证。任何能够访问调试端口的人都可以在容器内执行任意代码。始终限制访问，如下所示。

选项A：仅本地主机TCP（简单）

显示绑定到的调试端口 127.0.0.1 因此，只有本地进程可以连接：

services:
  web:
    build: .
    ports:
      - "3000:3000"
      - "127.0.0.1:12345:12345"  # localhost only
    environment:
      - RUBY_DEBUG_OPEN=true
      - RUBY_DEBUG_HOST=0.0.0.0
      - RUBY_DEBUG_PORT=12345

Agent: connect(port: 12345)

代理可以读取容器内的源文件，不需要源代码的本地副本。

选项B:Unix套接字卷装载（推荐）

为调试套接字挂载一个共享目录。无需端口暴露：

services:
  web:
    build: .
    ports:
      - "3000:3000"
    environment:
      - RUBY_DEBUG_OPEN=true
      - RUBY_DEBUG_SOCK_PATH=/debug/rdbg.sock
    volumes:
      - debug_sock:/debug

volumes:
  debug_sock:

Agent: connect(path: "/path/to/debug_sock/rdbg.sock")

连接到现有断点

# Terminal: your app hits a `debugger` statement
rdbg --open my_app.rb

Agent: list_debug_sessions()
Agent: connect(path: "/tmp/rdbg-1000/rdbg-12345")
Agent: get_context()

运作原理

┌────────────┐  STDIO or Streamable HTTP  ┌───────────┐    TCP/Unix Socket    ┌──────────────┐
│ MCP Client │ ◄────────────────────────► │ debug-mcp  │ ◄──────────────────► │ Ruby process │
│            │        (JSON-RPC)          │(MCP Server)│    debug gem proto   │  (rdbg)      │
└────────────┘                            └───────────┘                      └──────────────┘

1. debug mcp作为mcp服务器运行，通过STDIO（默认）或Streamable HTTP进行通信
2. 调试宝石(rdbg --open)在目标Ruby进程上公开一个套接字
3. debug mcp使用debug gem的有线协议连接到该套接字
4. MCP工具调用被转换为调试器命令，并返回结果
5. 空闲会话在可配置的超时后会自动清理

安全

debug-mcp是一个调试工具，它有意提供深度运行时访问。以下是你应该知道的：

结构化工具最大限度地减少了任意代码的执行。 大多数调试任务——查看变量、读取源代码、检查模型结构——都是由不运行任意代码的专用工具处理的。 evaluate_code 可用于运行时检查，内置的安全检查器会警告危险操作。

调试gem没有身份验证。 任何能够访问调试套接字的人都可以在目标进程中执行任意代码。始终绑定到本地主机(127.0.0.1)或者使用Unix套接字。请参阅 用于配置示例。

相关项目

• girb --基于人工智能的IRB人类助手，秉持着相同的理念。

发展

git clone https://github.com/rira100000000/debug-mcp.git
cd debug-mcp
bundle install

许可证

麻省理工学院