MCP Ruby Skeleton

🚀 MCP Ruby 服務器骨架

這個項目是 Model Context Protocol (MCP) 服務器的 Ruby 實現，它提供了一個接口，允許大型語言模型（LLMs）如 Claude 調用工具。當前實現提供了一個生成隨機數的工具。

⚠️ 重要提示

本文的實現靈感來源於 Azuki Azusa 的文章 Building a Model Context Protocol Server with TypeScript。

✨ 主要特性

• get-random-number：生成一個在指定最大值（默認為 100）之間的隨機整數。
• 兼容 MCP 協議版本 2024 - 11 - 05。
• 詳細的日誌記錄用於調試。
• 符合 JSON - RPC 2.0 的消息處理。

📦 安裝指南

使用 Git 克隆倉庫

git clone [your-repository-url]
cd mcp-ruby-server

依賴管理

項目使用 Bundler 管理依賴：

bundle install

💻 使用示例

基礎用法

啟動服務器

ruby server.rb

默認情況下，服務器監聽 localhost:3000。

調用 get-random-number 工具

curl -X POST http://localhost:3000 -d '{"method":"get-random-number","params":{},"id":1}'

響應示例：

{
  "result": 42,
  "id": 1
}

📚 詳細文檔

需求

• Ruby 3.0+

架構與設計

該服務器由以下組件組成：

核心組件

• MCP::Server：主要服務器實現，負責處理 MCP 協議消息。
  • 協議初始化
  • 工具註冊和管理
  • 消息處理
  • 工具列表和執行
  • 錯誤處理
• MCP::Transport::Stdio：標準 I/O 傳輸層，用於通信。
  • 消息接收
  • 響應傳輸
  • 事件驅動的消息處理
• MCP::Tool：工具定義和執行處理器。
  • 工具名稱、描述和輸入模式的管理
  • 工具邏輯實現
  • 執行期間參數處理
• RandomNumberServer：服務器實現，負責生成隨機數並註冊工具。

架構與設計說明

服務器的整體架構遵循模塊化設計原則。MCP::Server 是核心組件，負責註冊和管理所有工具，並處理客戶端發送的請求。MCP::Transport::Stdio 作為標準 I/O 傳輸層，負責消息的收發。MCP::Tool 則是具體工具的實現類，每個工具都有自己的邏輯和參數驗證。

調試

日誌記錄

服務器提供詳細的日誌記錄功能，日誌信息包括：

• 請求內容
• 響應內容
• 錯誤信息（如果有） 日誌文件存儲在 log/server.log 中。

常見問題

如何處理大輸入？調整 rand 方法的最大值：

max = (args["max"] || 100).to_i
max = [max, 100].min # 確保最大值不超過 100

發展

添加新工具

在 RandomNumberServer 中的 initialize 方法中添加新的工具：

def initialize(server)
  super

  # 註冊新工具
  new_tool = MCP::Tool.new(
    "new-tool-name",
    "新工具描述",
    {
      type: "object",
      properties: {
        # 工具參數
      }
    }
  ) do |args|
    # 工具實現
  end

  server.register_tool(new_tool)
end

測試

在添加新的工具或服務器功能時，建議增加測試。測試應包括：

• 單元測試：驗證工具定義和註冊的正確性
• 集成測試：驗證協議處理的正確性
• 端到端測試：驗證客戶端與服務器交互的正確性

錯誤處理與異常處理

為了提高 MCP 服務器的健壯性，建議實現以下錯誤處理：

1. 在工具執行期間捕獲異常，並向客戶端返回有意義的錯誤消息。
2. 驗證無效輸入參數。
3. 正確處理網絡和 I/O 錯誤。
4. 考慮超時和資源限制。