Ruby Console MCP

🚀 RubyコンソールMCPサーバー

AIアシスタントにRubyコンソール機能へのアクセスを提供するモデルコンテキストプロトコル（MCP）サーバーです。Railsコンソール、IRB、またはRackshコマンドを実行し、モデルをクエリし、永続的なセッションサポートを備えた自然言語でRuby/Railsアプリケーションと対話できます。

🚀 クイックスタート

このサーバーを使用することで、AIアシスタントがRubyコンソール機能にアクセスできるようになります。以下のセクションでは、インストール方法、設定方法、使用方法などを説明します。

✨ 主な機能

• 🚀 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 Desktop

Claude Desktopの設定ファイルに追加します。

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環境を再読み込みする必要はありません。

対話例

単純なクエリ:

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）で1行のコマンドを実行します。

パラメーター:

• 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 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"
• 本番環境では注意してください。
• 実行前にコマンドを慎重にレビューしてください。
• 必要に応じて追加のアクセス制御を実装することを検討してください。

📄 ライセンス

MIT

貢献

貢献は大歓迎です！問題やプルリクエストを自由に送信してください。