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. 考虑超时和资源限制。