MCP Ruby Server Skeleton

MCP Ruby 服务骨架

致谢：此实现受 Azuki Azusa 撰写的文章 使用 TypeScript 构建 Model Context Protocol 服务端 启发。

此项目是 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 之间的随机数”的提示词。

调试

日志

Claude 应用中与 MCP 服务相关的日志位于：

• 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 服务已断开连接”的消息，请检查：

• 协议版本兼容性
• 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. 考虑超时和资源限制