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

貢獻

歡迎貢獻！請隨時提交問題或拉取請求。