使用说明

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安装（推荐）

# Install globally
npm install -g ruby-console-mcp

# Or use with npx (no installation needed)
npx ruby-console-mcp

选项2：从源代码安装

# Clone or navigate to the project directory
git clone https://github.com/tuhalang/ruby-console-mcp.git
cd ruby-console-mcp

# Install dependencies
npm install

# Build the project
npm run build

配置

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

环境变量

RUBY_APP_PATH：Rails/Rack应用程序的路径（默认：当前目录）。如果使用Docker/remote命令或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）：

# Just use default command, it will use current directory
export RUBY_CONSOLE_COMMAND="bundle exec rails c"

自定义控制台命令

您可以自定义用于启动控制台的命令。Rails、IRB和Racksh的示例：

# Production environment
RUBY_CONSOLE_COMMAND="bundle exec rails c production"

# Sandbox mode (changes are rolled back)
RUBY_CONSOLE_COMMAND="bundle exec rails c --sandbox"

# Using Docker (no RUBY_APP_PATH needed)
RUBY_CONSOLE_COMMAND="docker-compose exec -T web bundle exec rails c"

# Using Kubernetes (no RUBY_APP_PATH needed)
RUBY_CONSOLE_COMMAND="kubectl exec -it rails-pod -- bundle exec rails c"

# Using specific Ruby version
RUBY_CONSOLE_COMMAND="rbenv exec bundle exec rails c"

# Remote server via SSH (no RUBY_APP_PATH needed)
RUBY_CONSOLE_COMMAND="ssh user@server 'cd /app && bundle exec rails c'"

# IRB (standalone Ruby)
RUBY_CONSOLE_COMMAND="irb"

# Racksh (Rack console)
RUBY_CONSOLE_COMMAND="bundle exec racksh"

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

与MCP客户端一起使用

克劳德桌面版

添加到您的Claude Desktop配置文件中：

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %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环境

交互示例

简单查询:

Command: User.count
Result: 42

跨命令使用变量:

Command: a = User.first
Result: => #<User id: 1...>

Command: a.email
Result: => "user@example.com"

复杂的操作:

Command: users = User.where('created_at > ?', 1.week.ago)
Result: => #<ActiveRecord::Relation...>

Command: users.count
Result: => 15

可用工具

execute_ruby_command

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

参数：

command （string，必填）：要执行的控制台命令

示例：

// Query a model
{
  "command": "User.count"
}

// Complex query
{
  "command": "User.where('created_at > ?', 1.week.ago).group(:role).count"
}

// Using variables (persists across commands)
{
  "command": "user = User.first"
}

// Accessing previous variable
{
  "command": "user.email"
}

execute_ruby_script

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

参数：

script （string，必填）：要执行的多行Ruby脚本

示例：

// Multi-line script
{
  "script": "user = User.first\nputs user.email\nuser.update(name: 'New Name')"
}

// Method definition
{
  "script": "def greet(name)\n  puts \"Hello, #{name}!\"\nend\ngreet('World')"
}

check_ruby_sole_health

检查控制台是否健康且反应灵敏。执行一个简单的测试命令并测量响应时间。

退货：

HEALTHY：控制台响应迅速（<5s）
DEGRADED：控制台响应缓慢（5-10s）
UNHEALTHY：控制台故障或速度非常慢（>10秒）

示例：

// Check health
{}

connect_ruby_sole

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

参数：

示例：

// Connect to console
{}

disconnect_ruby_sole

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

参数：

示例：

// Disconnect from console
{}

功能和安全

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

故障排除

控制台无法启动

问题：“启动控制台失败”

解决方案:

验证 RUBY_APP_PATH 指向一个有效的Rails应用程序
跑 bundle install 在Rails应用程序目录中
检查一下 RUBY_CONSOLE_COMMAND 适合您的设置
确保安装了所有依赖项

命令超时

问题：命令返回超时消息

解决方案:

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

未捕获输出

问题：命令执行但返回“（无输出）”

解决方案:

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

连接丢失

问题：Rails控制台意外断开连接

解决方案:

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

发展

# Clone the repository
git clone https://github.com/tuhalang/ruby-console-mcp.git
cd ruby-console-mcp

# Install dependencies
npm install

# Watch mode for development
npm run dev

# Build
npm run build

# Start the server
npm start

建筑

┌─────────────────┐
│   MCP Client    │
│  (Claude, etc)  │
└────────┬────────┘
         │ stdio
         │
┌────────▼────────┐
│   MCP Server    │
│   (index.ts)    │
└────────┬────────┘
         │
┌────────▼────────┐
│ Ruby Console    │
│    Manager      │
│ (ruby-console)  │
└────────┬────────┘
         │ PTY (pseudo-terminal)
┌────────▼────────┐
│ Ruby Console    │
│  (rails c/irb)  │
└─────────────────┘

安全考虑

此工具提供了对Rails应用程序的强大访问
所有命令都会立即执行，无需确认
考虑在沙盒模式下运行进行测试： RUBY_CONSOLE_COMMAND="bundle exec rails c --sandbox"
在生产环境中要小心
执行前仔细检查命令
考虑根据您的需求实施额外的访问控制

许可证

麻省理工学院

贡献

欢迎投稿！请随时提交问题或拉取请求。

使用说明

Ruby控制台MCP服务器

特性

安装

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

选项2：从源代码安装

配置

环境变量

配置示例

自定义控制台命令

与MCP客户端一起使用

克劳德桌面版

其他MCP客户端

运作原理

命令执行

持续会话

交互示例

可用工具

execute_ruby_command

execute_ruby_script

check_ruby_sole_health

connect_ruby_sole

disconnect_ruby_sole

功能和安全

故障排除

控制台无法启动

命令超时

未捕获输出

连接丢失

发展

建筑

安全考虑

许可证

贡献

相关 MCP

网页搜索MCP服务器

Zotero文献库搜索与阅读MCP服务

Prometheus 指标查询 MCP 服务器

SSH远程命令执行MCP服务器

电话服务 MCP 服务器

Meilisearch MCP 搜索服务器