Model Context Protocol

A Ruby gem implementing Model Context Protocol + JSON RPC 2.0 spec

Overview

Model Context Protocol provides a standardized way to interact with language models through a JSON RPC 2.0 interface.

It handles request/response formatting, error handling, and tool integrations in a type-safe manner using Sorbet.

See https://spec.modelcontextprotocol.io/specification/

This implementation breaks from the transport examples in the spec as it implements a POST-based JSON RPC call rather than a stateful SSE transport.

MCP Server

The ModelContextProtocol::Server class is the core component that handles JSON-RPC requests and responses. It implements the Model Context Protocol specification, handling model context requests and responses.

Key Features

• Implements JSON-RPC 2.0 message handling
• Supports protocol initialization and capability negotiation
• Manages tool registration and invocation
• Provides type-safe request/response handling using Sorbet

Supported Methods

• initialize - Initializes the protocol and returns server capabilities
• ping - Simple health check that returns "pong"
• tools/list - Lists all registered tools and their schemas
• tools/call - Invokes a specific tool with provided arguments
• prompts/list - Lists all registered prompts and their schemas
• prompts/get - Retrieves a specific prompt by name

Usage

Implement an ApplicationController which calls the Server#handle method, eg

module ModelContextProtocol
  class ApplicationController < ActionController::Base

    sig { void }
    def index
      server = ModelContextProtocol::Server.new(
        name: "my_server",
        tools: [someTool, anotherTool],
        prompts: [myPrompt]
      )
      render(json: server.handle(request.body.read).to_h)
    end
  end
end

Tools

MCP spec includes Tools which provide functionality to LLM apps.

This gem provides a ModelContextProtocol::Tool class that can be used to create tools in two ways:

1. As a class definition:

class MyTool < ModelContextProtocol::Tool
  tool_name "my_tool"
  tool_description "This tool performs specific functionality..."
  tool_input_schema [{ type: "text", name: "message" }]

  def call(message)
    Tool::Response.new([{ type: "text", content: "OK" }])
  end
end

tool = MyTool.new

2. By using the ModelContextProtocol::Tool.define method with a block:

tool = ModelContextProtocol::Tool.define(name: "my_tool", description: "This tool performs specific functionality...") do |args|
  Tool::Response.new([{ type: "text", content: "OK" }])
end

Prompts

MCP spec includes Prompts, which enable servers to define reusable prompt templates and workflows that clients can easily surface to users and LLMs.

The ModelContextProtocol::Prompt class provides two ways to create prompts:

1. As a class definition with metadata:

class MyPrompt < ModelContextProtocol::Prompt
  prompt_name "my_prompt"  # Optional - defaults to underscored class name
  description "This prompt performs specific functionality..."
  arguments [
    Prompt::Argument.new(
      name: "message",
      description: "Input message",
      required: true
    )
  ]

  def template(args)
    Prompt::Result.new(
      description: "Response description",
      messages: [
        Prompt::Message.new(
          role: "user",
          content: Content::Text.new("User message")
        ),
        Prompt::Message.new(
          role: "assistant",
          content: Content::Text.new(args["message"])
        )
      ]
    )
  end
end

2. Using the ModelContextProtocol::Prompt.define method:

prompt = ModelContextProtocol::Prompt.define(
  name: "my_prompt",
  description: "This prompt performs specific functionality...",
  arguments: [
    Prompt::Argument.new(
      name: "message",
      description: "Input message",
      required: true
    )
  ]
) do |args|
  Prompt::Result.new(
    description: "Response description",
    messages: [
      Prompt::Message.new(
        role: "user",
        content: Content::Text.new("User message")
      ),
      Prompt::Message.new(
        role: "assistant",
        content: Content::Text.new(args["message"])
      )
    ]
  )
end

Key Components

• Prompt::Argument - Defines input parameters for the prompt template
• Prompt::Message - Represents a message in the conversation with a role and content
• Prompt::Result - The output of a prompt template containing description and messages
• Content::Text - Text content for messages

Usage

Register prompts with the MCP server:

server = ModelContextProtocol::Server.new(
  name: "my_server",
  prompts: [MyPrompt.new]
)

The server will handle prompt listing and execution through the MCP protocol methods:

• prompts/list - Lists all registered prompts and their schemas
• prompts/get - Retrieves and executes a specific prompt with arguments

Releases

TODO