Ruby MCP Server for Claude Integration

Overview

The Ruby MCP Server for Claude Integration is an experimental Ruby implementation of the Model Context Protocol (MCP). It serves as a starter server framework for integrating Large Language Models (LLMs) like Claude with external tools. This project provides a foundational structure for building and managing tools that can be called by LLMs, with a current implementation that includes a random number generator tool.

Features

• get-random-number Tool: Generates a random integer between 1 and a specified maximum value (defaults to 100).
• MCP Protocol Compatibility: Supports MCP protocol version 2024-11-05.
• Detailed Logging: Includes comprehensive logging for debugging purposes.
• JSON-RPC 2.0 Compliance: Ensures proper handling of JSON-RPC 2.0 messages.

Requirements

• Ruby 3.0+: Ensure you have Ruby 3.0 or later installed on your system.

Architecture and Design

Core Components

• MCP::Server: Handles MCP protocol messages, including initialization, tool registration, message handling, and error management.
• MCP::Transport::Stdio: Manages communication via standard I/O, including message reception and response transmission.
• MCP::Tool: Defines and executes tools, managing tool names, descriptions, and input schemas.
• RandomNumberServer: Initializes the server, sets up tools, and manages server execution.

Protocol Flow

1. Client Initialization: The client sends an initialize request with the protocol version.
2. Server Response: The server responds with its capabilities and matches the protocol version.
3. Initialized Notification: The server sends an initialized notification.
4. Tool Interaction: The client can then list and call available tools.

Implemented MCP APIs

• initialize: Initializes the server and negotiates the protocol version.
• tools/list: Lists available tools and their schemas.
• tools/call: Executes a tool with provided arguments.

Installation

Clone the repository:

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

Make the server script executable:

chmod +x bin/run_server.rb

Usage

Direct Execution

Run the server directly:

./bin/run_server.rb

Integration with Claude Desktop

Add the following to your Claude Desktop configuration:

• 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"\
      ]
    }
  }
}

Replace the path with the absolute path to your run_server.rb file. Restart Claude Desktop and try a prompt like "Generate a random number between 1 and 50."

Debugging

Logs

Claude app logs related to MCP servers are available at:

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

To view the logs in real-time:

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

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

Common Issues

• Server Disconnection: Check protocol version compatibility, JSON-RPC message formatting, and file permissions.
• Tool Not Showing Up: Ensure the server is properly registered in the config file and has execution permissions.

Development

Adding New Tools

Modify the RandomNumberServer class to add new tools:

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

Testing

Implement unit tests, integration tests, and end-to-end tests to verify:

• Tool definition and registration.
• Protocol handling.
• Error handling.
• Input validation.
• Expected output confirmation.

Error Handling and Exceptions

Improve server robustness by:

1. Catching exceptions during tool execution and returning meaningful error messages.
2. Validating input parameters.
3. Handling network and I/O errors.
4. Considering timeouts and resource limitations.

About

This project is an experimental Ruby implementation of the Model Context Protocol (MCP), designed as a starter framework for integrating LLMs like Claude with external tools.

Resources

• Readme
• Activity

Stars

2 stars

Watchers

1 watching

Forks

0 forks

Report repository

Releases

No releases published

Packages 0

No packages published

Languages

• Ruby 100.0%