model-context-protocol-rb

# config/initializers/model_context_protocol.rb
require "model_context_protocol"

ModelContextProtocol::Server.configure_redis do |config|
  config.redis_url = ENV.fetch("REDIS_URL", "redis://localhost:6379/0")
  config.pool_size = 20
  config.pool_timeout = 5
  config.enable_reaper = true
  config.reaper_interval = 60
  config.idle_timeout = 300
end

constraints format: :json do
  get "/mcp", to: "model_context_protocol#handle", as: :mcp_get
  post "/mcp", to: "model_context_protocol#handle", as: :mcp_post
  delete "/mcp", to: "model_context_protocol#handle", as: :mcp_delete
end

class ModelContextProtocolController < ActionController::API
  include ActionController::Live

  before_action :authenticate_user

  def handle
    server = ModelContextProtocol::Server.new do |config|
      config.name = "MyMCPServer"
      config.title = "My MCP Server"
      config.version = "1.0.0"
      config.registry = build_registry
      config.context = {
        user_id: current_user.id,
        request_id: request.id
      }
      config.transport = {
        type: :streamable_http,
        env: request.env
      }
      config.instructions = <<~INSTRUCTIONS
        This server provides prompts, tools, and resources for interacting with my app.

        Key capabilities:
        - Does this one thing
        - Does this other thing
        - Oh, yeah, and it does that one thing, too

        Use this server when you need to do stuff.
      INSTRUCTIONS
    end

    result = server.start
    handle_mcp_response(result)
  end

  private

  def build_registry
    ModelContextProtocol::Server::Registry.new do
      tools do
        # Implement user authorization logic to dynamically build registry
        register TestTool if current_user.authorized_for?(TestTool)
      end
    end
  end

  def handle_mcp_response(result)
    if result[:headers]&.dig("Content-Type") == "text/event-stream"
      setup_streaming_headers
      stream_response(result[:stream_proc])
    else
      render_json_response(result)
    end
  end

  def setup_streaming_headers
    response.headers.merge!(
      "Content-Type" => "text/event-stream",
      "Cache-Control" => "no-cache",
      "Connection" => "keep-alive"
    )
  end

  def stream_response(stream_proc)
    stream_proc&.call(response.stream)
  ensure
    response.stream.close rescue nil
  end

  def render_json_response(result)
    render json: result[:json],
      status: result[:status] || 200,
      headers: result[:headers] || {}
  end
end

gem 'model-context-protocol-rb'

server = ModelContextProtocol::Server.new do |config|
  # Name of the MCP server (intended for programmatic use)
  config.name = "MCPDevelopmentServer"

  # Version of the MCP server
  config.version = "1.0.0"

  # Optional: human-readable display name for the MCP server
  config.title = "My Awesome Server"

  # Optional: instuctions for how the MCP server should be used by LLMs
  config.instructions = <<~INSTRUCTIONS
    This server provides file system access and development tools.

    Key capabilities:
    - Read and write files in the project directory
    - Execute shell commands for development tasks
    - Analyze code structure and dependencies

    Use this server when you need to interact with the local development environment.
  INSTRUCTIONS

  # Configure pagination options for the following methods:
  # prompts/list, resources/list, resource_template/list, tools/list
  config.pagination = {
    default_page_size: 50,   # Default items per page
    max_page_size: 500,      # Maximum allowed page size
    cursor_ttl: 1800         # Cursor expiry in seconds (30 minutes)
  }

  # Disable pagination support (enabled by default)
  # config.pagination = false

  # Optional: require specific environment variables to be set
  config.require_environment_variable("API_KEY")

  # Optional: set environment variables programmatically
  config.set_environment_variable("DEBUG_MODE", "true")

  # Optional: provide prompts, resources, and tools with contextual variables
  config.context = {
    user_id: "123456",
    request_id: SecureRandom.uuid
  }

  # Optional: explicitly specify STDIO as the transport
  # This is not necessary as STDIO is the default transport
  # config.transport = { type: :stdio }
 
  # Optional: configure streamable HTTP transport if required
  # config.transport = {
  #   type: :streamable_http,
  #   env: request.env,
  #   session_ttl: 3600 # Optional: session timeout in seconds (default: 3600)
  # }

  # Register prompts, resources, resource templates, and tools
  config.registry = ModelContextProtocol::Server::Registry.new do
    prompts list_changed: true do
      register TestPrompt
    end

    resources list_changed: true, subscribe: true do
      register TestResource
    end

    resource_templates do
      register TestResourceTemplate
    end

    tools list_changed: true do
      register TestTool
    end
  end
end

# Start the MCP server
server.start

config.transport = { type: :stdio }  # This is the default, can be omitted

config.transport = { type: :streamable_http, env: request.env }

ModelContextProtocol::Server.configure_redis do |config|
  config.redis_url = ENV.fetch('REDIS_URL')
  config.pool_size = 20
  config.pool_timeout = 5
  config.enable_reaper = true
  config.reaper_interval = 60
  config.idle_timeout = 300
end

ModelContextProtocol::Server.configure_server_logging do |config|
  config.logdev = $stderr           # or a file path like '/var/log/mcp-server.log'
  config.level = Logger::INFO       # Logger::DEBUG, Logger::INFO, Logger::WARN, Logger::ERROR, Logger::FATAL
  config.progname = "MyMCPServer"   # Program name for log entries
  config.formatter = proc do |severity, datetime, progname, msg|
    "#{datetime.strftime('%Y-%m-%d %H:%M:%S')} #{severity} [#{progname}] #{msg}\n"
  end
end

config.registry = ModelContextProtocol::Server::Registry.new do
  prompts list_changed: true do
    register MyPrompt
    register AnotherPrompt
  end

  resources list_changed: true, subscribe: true do
    register MyResource
  end

  tools do
    register MyTool
  end
end

class TestPrompt < ModelContextProtocol::Server::Prompt
  define do
    # The name of the prompt for programmatic use
    name "brainstorm_excuses"
    # The human-readable prompt name for display in UI
    title "Brainstorm Excuses"
    # A short description of what the tool does
    description "A prompt for brainstorming excuses to get out of something"

    # Define arguments to be used with your prompt
    argument do
      # The name of the argument
      name "tone"
      # A short description of the argument
      description "The general tone to be used in the generated excuses"
      # If the argument is required
      required false
      # Available hints for completions
      completion ["whiny", "angry", "callous", "desperate", "nervous", "sneaky"]
    end

    argument do
      name "undesirable_activity"
      description "The thing to get out of"
      required true
    end
  end

  # You can optionally define a custom completion for an argument and pass it to completions.
  # ToneCompletion = ModelContextProtocol::Server::Completion.define do
  #   hints = ["whiny", "angry", "callous", "desperate", "nervous", "sneaky"]
  #   values = hints.grep(/#{argument_value}/)
  #   respond_with values:
  # end
  #   ...
  # define do
  #   argument do
  #     name "tone"
  #     description "The general tone to be used in the generated excuses"
  #     required false
  #     completion ToneCompletion
  #   end
  # end

  # The call method is invoked by the MCP Server to generate a response to resource/read requests
  def call
    # You can use the client_logger
    client_logger.info("Brainstorming excuses...")

    # Server logging for debugging and monitoring (not sent to client)
    server_logger.debug("Prompt called with arguments: #{arguments}")
    server_logger.info("Generating excuse brainstorming prompt")

    # Build an array of user and assistant messages
    messages = message_history do
      # Create a message with the user role
      user_message do
        # Use any type of content block in a message (text, image, audio, embedded_resource, or resource_link)
        text_content(text: "My wife wants me to: #{arguments[:undesirable_activity]}... Can you believe it?")
      end

      # You can also create messages with the assistant role
      assistant_message do
        text_content(text: "Oh, that's just downright awful. How can I help?")
      end

      user_message do
        # Reference any inputs from the client by accessing the appropriate key in the arguments hash
        text_content(text: "Can you generate some excuses for me?" + (arguments[:tone] ? " Make them as #{arguments[:tone]} as possible." : ""))
      end
    end

    # Respond with the messages
    respond_with messages:
  end
end

class TestResource < ModelContextProtocol::Server::Resource
  define do
    name "top-secret-plans.txt"
    title "Top Secret Plans"
    description "Top secret plans to do top secret things"
    mime_type "text/plain"
    uri "file:///top-secret-plans.txt"
  end

  def call
    respond_with text: "I'm finna eat all my wife's leftovers."
  end
end

class TestAnnotatedResource < ModelContextProtocol::Server::Resource
  define do
    name "annotated-document.md"
    description "A document with annotations showing priority and audience"
    mime_type "text/markdown"
    uri "file:///docs/annotated-document.md"
    annotations do
      audience [:user, :assistant]
      priority 0.9
      last_modified "2025-01-12T15:00:58Z"
    end
  end

  def call
    respond_with text: "# Annotated Document\n\nThis document has annotations."
  end
end

class TestBinaryResource < ModelContextProtocol::Server::Resource
  define do
    name "project-logo.png"
    description "The logo for the project"
    mime_type "image/png"
    uri "file:///project-logo.png"
  end

  def call
    # In a real implementation, we would retrieve the binary resource
    # This is a small valid base64 encoded string (represents "test")
    data = "dGVzdA=="
    respond_with binary: data
  end
end

class TestResourceTemplate < ModelContextProtocol::Server::ResourceTemplate
  define do
    name "project-document-resource-template"
    description "A resource template for retrieving project documents"
    mime_type "text/plain"
    uri_template "file:///{name}" do
      completion :name, ["top-secret-plans.txt"]
    end
  end

  # You can optionally define a custom completion for an argument and pass it to completions.
  # Completion = ModelContextProtocol::Server::Completion.define do
  #   hints = {
  #     "name" => ["top-secret-plans.txt"]
  #   }
  #   values = hints[argument_name].grep(/#{argument_value}/)

  #   respond_with values:
  # end

  # define do
  #   name "project-document-resource-template"
  #   description "A resource template for retrieving project documents"
  #   mime_type "text/plain"
  #   uri_template "file:///{name}" do
  #     completion :name, Completion
  #   end
  # end
end

class TestToolWithStructuredContentResponse < ModelContextProtocol::Server::Tool
  define do
    # The name of the tool for programmatic use
    name "get_weather_data"
    # The human-readable tool name for display in UI
    title "Weather Data Retriever"
    # A short description of what the tool does
    description "Get current weather data for a location"
    # The JSON schema for validating tool inputs
    input_schema do
      {
        type: "object",
        properties: {
          location: {
            type: "string",
            description: "City name or zip code"
          }
        },
        required: ["location"]
      }
    end
    # The JSON schema for validating structured content
    output_schema do
      {
        type: "object",
        properties: {
          temperature: {
            type: "number",
            description: "Temperature in celsius"
          },
          conditions: {
            type: "string",
            description: "Weather conditions description"
          },
          humidity: {
            type: "number",
            description: "Humidity percentage"
          }
        },
        required: ["temperature", "conditions", "humidity"]
      }
    end
  end

  def call
    # Use values provided by the server as context
    user_id = context[:user_id]
    client_logger.info("Initiating request for user #{user_id}...")

    # Use values provided by clients as tool arguments
    location = arguments[:location]
    client_logger.info("Getting weather data for #{location}...")

    # Returns a hash that validates against the output schema
    weather_data = get_weather_data(location)

    # Respond with structured content
    respond_with structured_content: weather_data
  end

  private

  # Simulate calling an external API to get weather data for the provided input
  def get_weather_data(location)
    {
      temperature: 22.5,
      conditions: "Partly cloudy",
      humidity: 65
    }
  end
end

class TestToolWithTextResponse < ModelContextProtocol::Server::Tool
  define do
    name "double"
    title "Number Doubler"
    description "Doubles the provided number"
    input_schema do
      {
        type: "object",
        properties: {
          number: {
            type: "string"
          }
        },
        required: ["number"]
      }
    end
  end

  def call
    client_logger.info("Silly user doesn't know how to double a number")
    number = arguments[:number].to_i
    calculation = number * 2

    user_id = context[:user_id]
    salutation = user_id ? "User #{user_id}, " : ""
    text_content = text_content(text: salutation << "#{number} doubled is #{calculation}")

    respond_with content: text_content
  end
end

class TestToolWithImageResponse < ModelContextProtocol::Server::Tool
  define do
    name "custom-chart-generator"
    description "Generates a chart in various formats"
    input_schema do
      {
        type: "object",
        properties: {
          chart_type: {
            type: "string",
            description: "Type of chart (pie, bar, line)"
          },
          format: {
            type: "string",
            description: "Image format (jpg, svg, etc)"
          }
        },
        required: ["chart_type", "format"]
      }
    end
  end

  def call
    # Map format to mime type
    mime_type = case arguments[:format].downcase
    when "svg"
      "image/svg+xml"
    when "jpg", "jpeg"
      "image/jpeg"
    else
      "image/png"
    end

    # In a real implementation, we would generate an actual chart
    # This is a small valid base64 encoded string (represents "test")
    data = "dGVzdA=="
    image_content = image_content(data:, mime_type:)
    respond_with content: image_content
  end
end

class TestToolWithResourceResponse < ModelContextProtocol::Server::Tool
  define do
    name "resource-finder"
    description "Finds a resource given a name"
    input_schema do
      {
        type: "object",
        properties: {
          name: {
            type: "string",
            description: "The name of the resource"
          }
        },
        required: ["name"]
      }
    end
  end

  RESOURCE_MAPPINGS = {
    test_annotated_resource: TestAnnotatedResource,
    test_binary_resource: TestBinaryResource,
    test_resource: TestResource
  }.freeze

  def call
    name = arguments[:name]
    resource_klass = RESOURCE_MAPPINGS[name.downcase.to_sym]
    unless resource_klass
      return respond_with :error, text: "Resource `#{name}` not found"
    end

    resource_data = resource_klass.call(client_logger, context)

    respond_with content: embedded_resource_content(resource: resource_data)
  end
end

class TestToolWithMixedContentResponse < ModelContextProtocol::Server::Tool
  define do
    name "get_temperature_history"
    description "Gets comprehensive temperature history for a zip code"
    input_schema do
      {
        type: "object",
        properties: {
          zip: {
            type: "string"
          }
        },
        required: ["zip"]
      }
    end
  end

  def call
    client_logger.info("Getting comprehensive temperature history data")

    zip = arguments[:zip]
    temperature_history = retrieve_temperature_history(zip:)
    temperature_history_block = text_content(text: temperature_history.join(", "))

    temperature_chart = generate_weather_history_chart(temperature_history)
    temperature_chart_block = image_content(
      data: temperature_chart[:base64_chart_data],
      mime_type: temperature_chart[:mime_type]
    )

    respond_with content: [temperature_history_block, temperature_chart_block]
  end

  private

  def retrieve_temperature_history(zip:)
    # Simulates a call to an API or DB to retrieve weather history
    [85.2, 87.4, 89.0, 95.3, 96.0]
  end

  def generate_weather_history_chart(history)
    # SImulate a call to generate a chart given the weather history
    {
      base64_chart_data: "dGVzdA==",
      mime_type: "image/png"
    }
  end
end

class TestToolWithToolErrorResponse < ModelContextProtocol::Server::Tool
  define do
    name "api-caller"
    description "Makes calls to external APIs"
    input_schema do
      {
        type: "object",
        properties: {
          api_endpoint: {
            type: "string",
            description: "API endpoint URL"
          },
          method: {
            type: "string",
            description: "HTTP method (GET, POST, etc)"
          }
        },
        required: ["api_endpoint", "method"]
      }
    end
  end

  def call
    # Simulate an API call failure
    respond_with error: "Failed to call API at #{arguments[:api_endpoint]}: Connection timed out"
  end
end

class TestToolWithCancellableSleep < ModelContextProtocol::Server::Tool
  define do
    name "cancellable_sleep"
    title "Cancellable Sleep Tool"
    description "Sleep for 3 seconds with cancellation support"
    input_schema do
      {
        type: "object",
        properties: {},
        additionalProperties: false
      }
    end
  end

  def call
    client_logger.info("Starting 3 second sleep operation")

    result = cancellable do
      sleep 3
      "Sleep completed successfully"
    end

    respond_with content: text_content(text: result)
  end
end

class TestToolWithProgressableAndCancellable < ModelContextProtocol::Server::Tool
  define do
    name "test_tool_with_progressable_and_cancellable"
    description "A test tool that demonstrates combined progressable and cancellable functionality"

    input_schema do
      {
        type: "object",
        properties: {
          max_duration: {
            type: "number",
            description: "Expected maximum duration in seconds"
          },
          work_steps: {
            type: "number",
            description: "Number of work steps to perform"
          }
        },
        required: ["max_duration"]
      }
    end
  end

  def call
    max_duration = arguments[:max_duration] || 10
    work_steps = arguments[:work_steps] || 10
    client_logger.info("Starting progressable call with max_duration=#{max_duration}, work_steps=#{work_steps}")

    result = progressable(max_duration:, message: "Processing #{work_steps} items") do
      cancellable do
        processed_items = []

        work_steps.times do |i|
          sleep(max_duration / work_steps.to_f)
          processed_items << "item_#{i + 1}"
        end

        processed_items
      end
    end

    response = text_content(text: "Successfully processed #{result.length} items: #{result.join(", ")}")

    respond_with content: response
  end
end

class TestCompletion < ModelContextProtocol::Server::Completion
  def call
    hints = {
      "message" => ["hello", "world", "foo", "bar"]
    }
    values = hints[argument_name].grep(/#{argument_value}/)

    respond_with values:
  end
end