MCP Ruby Skeleton

🚀 MCP Ruby Server Skeleton

This project is a Ruby implementation of the Model Context Protocol (MCP) server, which provides an interface allowing large language models (LLMs) like Claude to call tools. Currently, it offers a tool to generate random numbers.

Acknowledgment: The implementation of this project is inspired by Azuki Azusa's article Building a Model Context Protocol Server with TypeScript.

✨ Features

• get-random-number: Generate a random integer between 0 and a specified maximum value (default is 100).
• Compatible with MCP protocol version 2024-11-05.
• Detailed logging for debugging.
• Message handling compliant with JSON-RPC 2.0.

📋 Requirements

• Ruby 3.0+

🏗️ Architecture and Design

The server consists of the following components:

Core Components

• MCP::Server: The main server implementation, responsible for handling MCP protocol messages.

  • Protocol initialization.
  • Tool registration and management.
  • Message handling.
  • Tool listing and execution.
  • Error handling.

• MCP::Transport::Stdio: The standard I/O transport layer for communication.

  • Message reception.
  • Response transmission.
  • Event-driven message handling.

• MCP::Tool: Tool definition and execution handler.

  • Management of tool names, descriptions, and input modes.
  • Implementation of tool logic.
  • Parameter handling during execution.

• RandomNumberServer: The server implementation responsible for generating random numbers and registering tools.

Architecture and Design Explanation

The overall architecture of the server follows the modular design principle. MCP::Server is the core component, responsible for registering and managing all tools and handling requests sent by clients. MCP::Transport::Stdio serves as the standard I/O transport layer, responsible for sending and receiving messages. MCP::Tool is the implementation class for specific tools, with each tool having its own logic and parameter validation.

📦 Installation

Clone the Repository with Git

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

Dependency Management

The project uses Bundler to manage dependencies:

bundle install

💻 Usage Examples

Start the Server

ruby server.rb

By default, the server listens on localhost:3000.

Call a Tool

Call the get-random-number Tool

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

Example response:

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

🐞 Debugging

Logging

The server provides detailed logging functionality. Log information includes:

• Request content.
• Response content.
• Error information (if any).

Log files are stored in log/server.log.

Common Issues

1. How to handle large inputs?

Adjust the maximum value of the rand method:

max = (args["max"] || 100).to_i
max = [max, 100].min # Ensure the maximum value does not exceed 100

🚀 Development

Add New Tools

Add new tools in the initialize method of RandomNumberServer:

def initialize(server)
  super

  # Register a new tool
  new_tool = MCP::Tool.new(
    "new-tool-name",
    "New tool description",
    {
      type: "object",
      properties: {
        # Tool parameters
      }
    }
  ) do |args|
    # Tool implementation
  end

  server.register_tool(new_tool)
end

Testing

When adding new tools or server features, it is recommended to add tests. Tests should include:

• Unit tests: Verify the correctness of tool definition and registration.
• Integration tests: Verify the correctness of protocol handling.
• End-to-end tests: Verify the correctness of client-server interaction.

Error Handling and Exception Handling

To improve the robustness of the MCP server, it is recommended to implement the following error handling:

1. Catch exceptions during tool execution and return meaningful error messages to the client.
2. Validate invalid input parameters.
3. Handle network and I/O errors correctly.
4. Consider timeouts and resource limitations.