MCP Ruby Server Skeleton

MCP Ruby サーバーのスケルトン

謝辞：この実装は、Azuki Azusa による記事 Building a Model Context Protocol Server with TypeScript に着想を得ています。

このプロジェクトは、Model Context Protocol（MCP）サーバーのスケルトンを Ruby で実装したものです。Claude のような大規模言語モデル（LLM）がツールを呼び出せるインターフェースを提供します。現在の実装では、乱数を生成するツールを提供しています。

機能

• get-random-number：1 から指定した最大値までのランダムな整数を生成します（デフォルトは 100 です）
• MCP プロトコルバージョン 2024-11-05 に対応
• デバッグ用の詳細なログ
• JSON-RPC 2.0 に準拠したメッセージ処理

要件

• Ruby 3.0+

アーキテクチャと設計

このサーバーは、以下のコンポーネントで構成されています。

コアコンポーネント

• MCP::Server：MCP プロトコルメッセージを処理するメインのサーバー実装

  • プロトコルの初期化
  • ツールの登録と管理
  • メッセージ処理
  • ツールの一覧表示と実行
  • エラー処理

• MCP::Transport::Stdio：通信に使用する標準入出力のトランスポート層

  • メッセージの受信
  • 応答の送信
  • イベント駆動型のメッセージ処理

• MCP::Tool：ツールの定義と実行を処理するハンドラー

  • ツール名、説明、入力スキーマの管理
  • ツールロジックの実装
  • 実行時の引数処理

• RandomNumberServer：ツールを登録、管理するサーバー実装

  • サーバーの初期化
  • ツールの設定
  • サーバーの実行

プロトコルのフロー

サーバーは、MCP の初期化プロトコルに従います。

1. クライアントがプロトコルバージョンを指定して initialize リクエストを送信します
2. サーバーが自身の機能を返し、プロトコルバージョンを照合します
3. サーバーが initialized 通知を送信します
4. その後、クライアントはツールの一覧表示や呼び出しを行えます

実装済みの MCP API

サーバーは以下の MCP API を実装しています。

• initialize：サーバーの初期化とプロトコルバージョンのネゴシエーション
• tools/list：利用可能なツールとそのスキーマを一覧表示します
• tools/call：指定された引数でツールを実行します

インストール

リポジトリをクローンします。

git clone <repository-url>
cd mcp-ruby-skeleton

サーバースクリプトに実行権限があることを確認します。

chmod +x bin/run_server.rb

使用方法

直接実行

サーバーを直接実行します。

./bin/run_server.rb

Claude Desktop との連携

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

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

{
  "mcpServers": {
    "random-number": {
      "command": "ruby",
      "args": [
        "/Users/bash/src/mcp-ruby-skeleton/bin/run_server.rb"
      ]
    }
  }
}

パスは、システム上の run_server.rb ファイルの絶対パスに置き換えてください。

設定後、Claude Desktop を再起動し、「1 から 50 の間でランダムな数値を生成して」のようなプロンプトを試してください。

デバッグ

ログ

MCP サーバーに関連する Claude アプリのログは、以下の場所で確認できます。

• macOS：~/Library/Logs/Claude/mcp*.log
• Windows：%APPDATA%\Claude\logs\mcp*.log

ログをリアルタイムで表示するには、以下を実行します。

# On macOS
tail -f ~/Library/Logs/Claude/mcp*.log

# On Windows
type "%APPDATA%\Claude\logs\mcp*.log"

サーバー自体は標準エラー出力（STDERR）にログを出力します。ログレベルは RandomNumberServer クラスの初期化時に設定されます（現在は DEBUG レベルです）。

よくある問題

サーバーの切断
「MCP server disconnected」のようなメッセージが表示される場合は、以下を確認してください。

• プロトコルバージョンの互換性
• JSON-RPC メッセージの形式
• 初期化シーケンスが正しいこと
• サーバースクリプトのファイル権限

ツールが表示されない
Claude に乱数ツールが表示されない場合は、以下を確認してください。

• サーバーが設定ファイルに正しく登録されていること
• サーバースクリプトに実行権限があること
• Claude Desktop を完全に再起動すること
• エラーがないかログを確認すること

開発

新しいツールの追加

RandomNumberServer クラスを変更して、サーバーにツールを追加できます。

def setup_tools
  # Existing random number tool
  random_number_tool = MCP::Tool.new(
    "get-random-number",
    "Generate a random number between 1 and the specified maximum value",
    {
      type: "object",
      properties: {
        max: {
          type: "integer",
          description: "Maximum value for the random number (defaults to 100 if not specified)"
        }
      }
    }
  ) do |args|
    max = (args["max"] || 100).to_i
    max = 100 if max <= 0
    
    rand(1..max)
  end

  @server.register_tool(random_number_tool)
  
  # Add your new tool here
  new_tool = MCP::Tool.new(
    "tool-name",
    "Tool description",
    {
      type: "object",
      properties: {
        # Tool parameters
      }
    }
  ) do |args|
    # Tool implementation
  end
  
  @server.register_tool(new_tool)
end

テスト

新しいツールやサーバー機能を実装する際は、テストを追加することをおすすめします。ユニットテスト、統合テスト、エンドツーエンドテストを組み合わせて実施してください。

テストでは、次の項目を検証してください。

• ツールが適切に定義、登録されていること
• プロトコルが正しく処理されること
• エラー処理
• 入力の検証
• 期待される出力の確認

エラー処理と例外

MCP サーバーの堅牢性を高めるには、適切なエラー処理と例外処理を実装することが重要です。

1. ツールの実行中に発生した例外を適切に捕捉し、クライアントにわかりやすいエラーメッセージを返します
2. 無効な入力パラメーターを検証します
3. ネットワークエラーや I/O エラーを適切に処理します
4. タイムアウトやリソースの制限を考慮します