Ruby Console MCP

🚀 Ruby控制台MCP服务器

这是一个模型上下文协议（MCP）服务器，为AI助手提供访问Ruby控制台功能的途径。你可以执行Rails控制台、IRB或Racksh命令，查询模型，并通过自然语言与你的Ruby/Rails应用程序进行交互，同时支持持久会话。

✨ 主要特性

• 🚀 通过MCP执行Rails控制台、IRB或Racksh命令。
• 💾 持久会话 —— 命令之间的变量和状态会被保留。
• ⚙️ 可配置的控制台命令（支持Rails、IRB、Racksh或任何Ruby REPL）。
• 🔌 可轻松与支持MCP的AI助手（如Claude、Cursor等）集成。
• 📝 清晰的错误消息和有用的诊断信息。
• 🎯 使用PTY提供适当的TTY支持（适用于Rails 8+、IRB、Racksh）。

📦 安装指南

选项1：通过npm安装（推荐）

# 全局安装
npm install -g ruby-console-mcp

# 或者使用npx（无需安装）
npx ruby-console-mcp

选项2：从源代码安装

# 克隆或进入项目目录
git clone https://github.com/tuhalang/ruby-console-mcp.git
cd ruby-console-mcp

# 安装依赖
npm install

# 构建项目
npm run build

📚 详细文档

配置

创建配置文件或设置环境变量：

环境变量

• RUBY_APP_PATH：Rails/Rack应用程序的路径（默认：当前目录）。如果使用Docker/远程命令或IRB，则此选项可选。
• RUBY_CONSOLE_COMMAND：启动控制台的命令（默认：bundle exec rails c）。可以是Rails控制台、IRB、Racksh或任何Ruby REPL。
• COMMAND_TIMEOUT：命令执行的超时时间（以毫秒为单位，默认：30000）

配置示例

本地Rails应用：

export RUBY_APP_PATH=/path/to/your/rails/app
export RUBY_CONSOLE_COMMAND="bundle exec rails c"

Docker（无需设置RUBY_APP_PATH）：

export RUBY_CONSOLE_COMMAND="docker-compose exec -T web bundle exec rails c"

从Rails目录运行（无需设置RUBY_APP_PATH）：

# 只需使用默认命令，它将使用当前目录
export RUBY_CONSOLE_COMMAND="bundle exec rails c"

自定义控制台命令

你可以自定义启动控制台的命令。以下是Rails、IRB和Racksh的示例：

# 生产环境
RUBY_CONSOLE_COMMAND="bundle exec rails c production"

# 沙盒模式（更改将回滚）
RUBY_CONSOLE_COMMAND="bundle exec rails c --sandbox"

# 使用Docker（无需设置RUBY_APP_PATH）
RUBY_CONSOLE_COMMAND="docker-compose exec -T web bundle exec rails c"

# 使用Kubernetes（无需设置RUBY_APP_PATH）
RUBY_CONSOLE_COMMAND="kubectl exec -it rails-pod -- bundle exec rails c"

# 使用特定的Ruby版本
RUBY_CONSOLE_COMMAND="rbenv exec bundle exec rails c"

# 通过SSH连接到远程服务器（无需设置RUBY_APP_PATH）
RUBY_CONSOLE_COMMAND="ssh user@server 'cd /app && bundle exec rails c'"

# IRB（独立的Ruby）
RUBY_CONSOLE_COMMAND="irb"

# Racksh（Rack控制台）
RUBY_CONSOLE_COMMAND="bundle exec racksh"

注意：使用Docker、Kubernetes或远程命令时，通常无需设置RUBY_APP_PATH，因为命令本身会处理上下文。

与MCP客户端一起使用

Claude桌面版

将以下内容添加到Claude桌面版的配置文件中：

• MacOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json

使用npm包（推荐）：

{
  "mcpServers": {
    "ruby-console": {
      "command": "npx",
      "args": ["-y", "ruby-console-mcp"],
      "env": {
        "RUBY_APP_PATH": "/path/to/your/rails/app"
      }
    }
  }
}

或者使用全局安装的包：

{
  "mcpServers": {
    "ruby-console": {
      "command": "ruby-console-mcp",
      "env": {
        "RUBY_APP_PATH": "/path/to/your/rails/app"
      }
    }
  }
}

本地Rails应用（从源代码运行）：

{
  "mcpServers": {
    "ruby-console": {
      "command": "node",
      "args": ["/path/to/ruby-console-mcp/build/index.js"],
      "env": {
        "RUBY_APP_PATH": "/path/to/your/rails/app"
      }
    }
  }
}

Docker（无需设置RUBY_APP_PATH）：

{
  "mcpServers": {
    "ruby-console": {
      "command": "npx",
      "args": ["-y", "ruby-console-mcp"],
      "env": {
        "RUBY_CONSOLE_COMMAND": "docker-compose exec -T web bundle exec rails c"
      }
    }
  }
}

其他MCP客户端

使用npm包：

npx -y ruby-console-mcp

如果已全局安装：

ruby-console-mcp

从源代码运行：

node /path/to/ruby-console-mcp/build/index.js

工作原理

命令执行

服务器使用伪终端（PTY）生成一个持久的控制台进程（Rails控制台、IRB或Racksh），并通过stdin/stdout与之通信。命令被发送到控制台，响应被捕获并返回给AI助手。

持久会话

控制台在持久会话中运行，这意味着：

• 变量持久化：在一个命令中定义的变量在后续命令中可用。
• 状态保持：ActiveRecord连接、已加载的类和其他状态会被保留。
• 高效：无需为每个命令重新加载Rails环境。

交互示例

简单查询：

命令：User.count
结果：42

跨命令使用变量：

命令：a = User.first
结果：=> #<User id: 1...>

命令：a.email
结果：=> "user@example.com"

复杂操作：

命令：users = User.where('created_at > ?', 1.week.ago)
结果：=> #<ActiveRecord::Relation...>

命令：users.count
结果：=> 15

可用工具

execute_ruby_command

在控制台（Rails控制台、IRB或Racksh）中执行单行命令。 参数：

• command（字符串，必需）：要执行的控制台命令

示例：

// 查询模型
{
  "command": "User.count"
}

// 复杂查询
{
  "command": "User.where('created_at > ?', 1.week.ago).group(:role).count"
}

// 使用变量（跨命令持久化）
{
  "command": "user = User.first"
}

// 访问先前的变量
{
  "command": "user.email"
}

execute_ruby_script

在控制台中执行多行Ruby脚本。适用于复杂操作、方法定义或代码块。 参数：

• script（字符串，必需）：要执行的多行Ruby脚本

示例：

// 多行脚本
{
  "script": "user = User.first\nputs user.email\nuser.update(name: 'New Name')"
}

// 方法定义
{
  "script": "def greet(name)\n  puts \"Hello, #{name}!\"\nend\ngreet('World')"
}

check_ruby_console_health

检查控制台是否健康且响应正常。执行一个简单的测试命令并测量响应时间。 返回值：

• HEALTHY：控制台响应迅速（< 5秒）
• DEGRADED：控制台响应但较慢（5 - 10秒）
• UNHEALTHY：控制台失败或非常慢（> 10秒）

示例：

// 检查健康状况
{}

connect_ruby_console

连接到Ruby控制台。如果控制台尚未运行，则启动它。返回连接状态和控制台信息。 参数：无

示例：

// 连接到控制台
{}

disconnect_ruby_console

断开与Ruby控制台的连接。停止控制台进程并释放资源。断开连接后，所有变量和状态将丢失。 参数：无

示例：

// 断开与控制台的连接
{}

特性与安全性

1. 持久会话：命令之间的变量和状态持久化，实现高效工作流程。
2. 多行脚本支持：执行多行复杂的Ruby脚本。
3. 健康监控：检查控制台的健康状况和响应能力。
4. 连接管理：手动连接和断开与控制台的连接。
5. 超时保护：命令在30秒后超时（可通过COMMAND_TIMEOUT配置），并提供进度反馈。
6. 错误解析：带有堆栈跟踪的美观格式化错误消息。
7. 错误处理：针对常见问题提供清晰的错误消息。
8. 进程管理：服务器关闭时自动清理。
9. PTY支持：使用伪终端实现正确的Rails控制台输出（与Rails 8+兼容）。

故障排除

控制台无法启动

问题：“Failed to start console” 解决方案：

• 验证RUBY_APP_PATH指向有效的Rails应用程序。
• 在Rails应用程序目录中运行bundle install。
• 检查RUBY_CONSOLE_COMMAND是否适合你的设置。
• 确保所有依赖项都已安装。

命令超时

问题：命令返回超时消息 解决方案：

• 为长时间运行的查询增加COMMAND_TIMEOUT。
• 检查Rails控制台是否挂起（手动测试）。
• 优化查询或命令。

输出未捕获

问题：命令执行但返回 "(No output)" 解决方案：

• 某些操作可能不会返回输出（这是正常的）。
• 尝试在命令中添加.inspect或pp以获得更好的输出。
• 检查Rails应用程序日志中的错误。

连接丢失

问题：Rails控制台意外断开连接 解决方案：

• 检查Rails应用程序日志中的错误。
• 验证数据库连接是否稳定。
• 重启MCP服务器。

开发

# 克隆仓库
git clone https://github.com/tuhalang/ruby-console-mcp.git
cd ruby-console-mcp

# 安装依赖
npm install

# 开发模式下的监视模式
npm run dev

# 构建
npm run build

# 启动服务器
npm start

架构

┌─────────────────┐
│   MCP客户端     │
│  (Claude等)     │
└────────┬────────┘
         │ stdio
         │
┌────────▼────────┐
│   MCP服务器     │
│   (index.ts)    │
└────────┬────────┘
         │
┌────────▼────────┐
│ Ruby控制台      │
│    管理器       │
│ (ruby-console)  │
└────────┬────────┘
         │ PTY（伪终端）
┌────────▼────────┐
│ Ruby控制台      │
│  (rails c/irb)  │
└─────────────────┘

安全考虑

• 此工具提供对Rails应用程序的强大访问权限。
• 所有命令将立即执行，无需确认。
• 考虑在沙盒模式下进行测试：RUBY_CONSOLE_COMMAND="bundle exec rails c --sandbox"。
• 在生产环境中要谨慎使用。
• 执行命令前仔细审查。
• 根据需要考虑实施额外的访问控制。

📄 许可证

MIT

贡献

欢迎贡献！请随时提交问题或拉取请求。