mcp 0.1.0

data/lib/mcp/server.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+require "json_rpc_handler"
+require_relative "instrumentation"
+require_relative "methods"
+
+module MCP
+  class Server
+    DEFAULT_VERSION = "0.1.0"
+
+    class RequestHandlerError < StandardError
+      attr_reader :error_type
+      attr_reader :original_error
+
+      def initialize(message, request, error_type: :internal_error, original_error: nil)
+        super(message)
+        @request = request
+        @error_type = error_type
+        @original_error = original_error
+      end
+    end
+
+    include Instrumentation
+
+    attr_writer :capabilities
+    attr_accessor :name, :version, :tools, :prompts, :resources, :server_context, :configuration
+
+    def initialize(
+      name: "model_context_protocol",
+      version: DEFAULT_VERSION,
+      tools: [],
+      prompts: [],
+      resources: [],
+      resource_templates: [],
+      server_context: nil,
+      configuration: nil,
+      capabilities: nil
+    )
+      @name = name
+      @version = version
+      @tools = tools.to_h { |t| [t.name_value, t] }
+      @prompts = prompts.to_h { |p| [p.name_value, p] }
+      @resources = resources
+      @resource_templates = resource_templates
+      @resource_index = index_resources_by_uri(resources)
+      @server_context = server_context
+      @configuration = MCP.configuration.merge(configuration)
+
+      @handlers = {
+        Methods::RESOURCES_LIST => method(:list_resources),
+        Methods::RESOURCES_READ => method(:read_resource_no_content),
+        Methods::RESOURCES_TEMPLATES_LIST => method(:list_resource_templates),
+        Methods::TOOLS_LIST => method(:list_tools),
+        Methods::TOOLS_CALL => method(:call_tool),
+        Methods::PROMPTS_LIST => method(:list_prompts),
+        Methods::PROMPTS_GET => method(:get_prompt),
+        Methods::INITIALIZE => method(:init),
+        Methods::PING => ->(_) { {} },
+
+        # No op handlers for currently unsupported methods
+        Methods::RESOURCES_SUBSCRIBE => ->(_) {},
+        Methods::RESOURCES_UNSUBSCRIBE => ->(_) {},
+        Methods::COMPLETION_COMPLETE => ->(_) {},
+        Methods::LOGGING_SET_LEVEL => ->(_) {},
+      }
+    end
+
+    def capabilities
+      @capabilities ||= determine_capabilities
+    end
+
+    def handle(request)
+      JsonRpcHandler.handle(request) do |method|
+        handle_request(request, method)
+      end
+    end
+
+    def handle_json(request)
+      JsonRpcHandler.handle_json(request) do |method|
+        handle_request(request, method)
+      end
+    end
+
+    def define_tool(name: nil, description: nil, input_schema: nil, annotations: nil, &block)
+      tool = Tool.define(name:, description:, input_schema:, annotations:, &block)
+      @tools[tool.name_value] = tool
+    end
+
+    def define_prompt(name: nil, description: nil, arguments: [], &block)
+      prompt = Prompt.define(name:, description:, arguments:, &block)
+      @prompts[prompt.name_value] = prompt
+    end
+
+    def resources_list_handler(&block)
+      @handlers[Methods::RESOURCES_LIST] = block
+    end
+
+    def resources_read_handler(&block)
+      @handlers[Methods::RESOURCES_READ] = block
+    end
+
+    def resources_templates_list_handler(&block)
+      @handlers[Methods::RESOURCES_TEMPLATES_LIST] = block
+    end
+
+    def tools_list_handler(&block)
+      @handlers[Methods::TOOLS_LIST] = block
+    end
+
+    def tools_call_handler(&block)
+      @handlers[Methods::TOOLS_CALL] = block
+    end
+
+    def prompts_list_handler(&block)
+      @handlers[Methods::PROMPTS_LIST] = block
+    end
+
+    def prompts_get_handler(&block)
+      @handlers[Methods::PROMPTS_GET] = block
+    end
+
+    private
+
+    def handle_request(request, method)
+      handler = @handlers[method]
+      unless handler
+        instrument_call("unsupported_method") {}
+        return
+      end
+
+      Methods.ensure_capability!(method, capabilities)
+
+      ->(params) {
+        instrument_call(method) do
+          case method
+          when Methods::TOOLS_LIST
+            { tools: @handlers[Methods::TOOLS_LIST].call(params) }
+          when Methods::PROMPTS_LIST
+            { prompts: @handlers[Methods::PROMPTS_LIST].call(params) }
+          when Methods::RESOURCES_LIST
+            { resources: @handlers[Methods::RESOURCES_LIST].call(params) }
+          when Methods::RESOURCES_READ
+            { contents: @handlers[Methods::RESOURCES_READ].call(params) }
+          when Methods::RESOURCES_TEMPLATES_LIST
+            { resourceTemplates: @handlers[Methods::RESOURCES_TEMPLATES_LIST].call(params) }
+          else
+            @handlers[method].call(params)
+          end
+        rescue => e
+          report_exception(e, { request: request })
+          if e.is_a?(RequestHandlerError)
+            add_instrumentation_data(error: e.error_type)
+            raise e
+          end
+
+          add_instrumentation_data(error: :internal_error)
+          raise RequestHandlerError.new("Internal error handling #{method} request", request, original_error: e)
+        end
+      }
+    end
+
+    def determine_capabilities
+      defines_prompts = @prompts.any? || @handlers[Methods::PROMPTS_LIST] != method(:list_prompts)
+      defines_tools = @tools.any? || @handlers[Methods::TOOLS_LIST] != method(:list_tools)
+      defines_resources = @resources.any? || @handlers[Methods::RESOURCES_LIST] != method(:list_resources)
+      defines_resource_templates = @resource_templates.any? || @handlers[Methods::RESOURCES_TEMPLATES_LIST] != method(:list_resource_templates)
+      {
+        prompts: defines_prompts ? {} : nil,
+        resources: defines_resources || defines_resource_templates ? {} : nil,
+        tools: defines_tools ? {} : nil,
+      }.compact
+    end
+
+    def server_info
+      @server_info ||= {
+        name:,
+        version:,
+      }
+    end
+
+    def init(request)
+      add_instrumentation_data(method: Methods::INITIALIZE)
+      {
+        protocolVersion: configuration.protocol_version,
+        capabilities: capabilities,
+        serverInfo: server_info,
+      }
+    end
+
+    def list_tools(request)
+      add_instrumentation_data(method: Methods::TOOLS_LIST)
+      @tools.map { |_, tool| tool.to_h }
+    end
+
+    def call_tool(request)
+      add_instrumentation_data(method: Methods::TOOLS_CALL)
+      tool_name = request[:name]
+      tool = tools[tool_name]
+      unless tool
+        add_instrumentation_data(error: :tool_not_found)
+        raise RequestHandlerError.new("Tool not found #{tool_name}", request, error_type: :tool_not_found)
+      end
+
+      arguments = request[:arguments]
+      add_instrumentation_data(tool_name:)
+
+      if tool.input_schema&.missing_required_arguments?(arguments)
+        add_instrumentation_data(error: :missing_required_arguments)
+        raise RequestHandlerError.new(
+          "Missing required arguments: #{tool.input_schema.missing_required_arguments(arguments).join(", ")}",
+          request,
+          error_type: :missing_required_arguments,
+        )
+      end
+
+      begin
+        call_params = tool_call_parameters(tool)
+
+        if call_params.include?(:server_context)
+          tool.call(**arguments.transform_keys(&:to_sym), server_context:).to_h
+        else
+          tool.call(**arguments.transform_keys(&:to_sym)).to_h
+        end
+      rescue => e
+        raise RequestHandlerError.new("Internal error calling tool #{tool_name}", request, original_error: e)
+      end
+    end
+
+    def list_prompts(request)
+      add_instrumentation_data(method: Methods::PROMPTS_LIST)
+      @prompts.map { |_, prompt| prompt.to_h }
+    end
+
+    def get_prompt(request)
+      add_instrumentation_data(method: Methods::PROMPTS_GET)
+      prompt_name = request[:name]
+      prompt = @prompts[prompt_name]
+      unless prompt
+        add_instrumentation_data(error: :prompt_not_found)
+        raise RequestHandlerError.new("Prompt not found #{prompt_name}", request, error_type: :prompt_not_found)
+      end
+
+      add_instrumentation_data(prompt_name:)
+
+      prompt_args = request[:arguments]
+      prompt.validate_arguments!(prompt_args)
+
+      prompt.template(prompt_args, server_context:).to_h
+    end
+
+    def list_resources(request)
+      add_instrumentation_data(method: Methods::RESOURCES_LIST)
+
+      @resources.map(&:to_h)
+    end
+
+    # Server implementation should set `resources_read_handler` to override no-op default
+    def read_resource_no_content(request)
+      add_instrumentation_data(method: Methods::RESOURCES_READ)
+      add_instrumentation_data(resource_uri: request[:uri])
+      []
+    end
+
+    def list_resource_templates(request)
+      add_instrumentation_data(method: Methods::RESOURCES_TEMPLATES_LIST)
+
+      @resource_templates.map(&:to_h)
+    end
+
+    def report_exception(exception, server_context = {})
+      configuration.exception_reporter.call(exception, server_context)
+    end
+
+    def index_resources_by_uri(resources)
+      resources.each_with_object({}) do |resource, hash|
+        hash[resource.uri] = resource
+      end
+    end
+
+    def tool_call_parameters(tool)
+      method_def = tool_call_method_def(tool)
+      method_def.parameters.flatten
+    end
+
+    def tool_call_method_def(tool)
+      method = tool.method(:call)
+
+      if defined?(T::Utils) && T::Utils.respond_to?(:signature_for_method)
+        sorbet_typed_method_definition = T::Utils.signature_for_method(method)&.method
+
+        # Return the Sorbet typed method definition if it exists, otherwise fallback to original method
+        # definition if Sorbet is defined but not used by this tool.
+        sorbet_typed_method_definition || method
+      else
+        method
+      end
+    end
+  end
+end

data/lib/mcp/string_utils.rb

@@ -0,0 +1,26 @@
+# typed: strict
+# frozen_string_literal: true
+
+module MCP
+  module StringUtils
+    extend self
+
+    def handle_from_class_name(class_name)
+      underscore(demodulize(class_name))
+    end
+
+    private
+
+    def demodulize(path)
+      path.to_s.split("::").last || path.to_s
+    end
+
+    def underscore(camel_cased_word)
+      camel_cased_word.dup
+        .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        .tr("-", "_")
+        .downcase
+    end
+  end
+end

data/lib/mcp/tool/annotations.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module MCP
+  class Tool
+    class Annotations
+      attr_reader :title, :read_only_hint, :destructive_hint, :idempotent_hint, :open_world_hint
+
+      def initialize(title: nil, read_only_hint: nil, destructive_hint: nil, idempotent_hint: nil, open_world_hint: nil)
+        @title = title
+        @read_only_hint = read_only_hint
+        @destructive_hint = destructive_hint
+        @idempotent_hint = idempotent_hint
+        @open_world_hint = open_world_hint
+      end
+
+      def to_h
+        {
+          title:,
+          readOnlyHint: read_only_hint,
+          destructiveHint: destructive_hint,
+          idempotentHint: idempotent_hint,
+          openWorldHint: open_world_hint,
+        }.compact
+      end
+    end
+  end
+end

data/lib/mcp/tool/input_schema.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module MCP
+  class Tool
+    class InputSchema
+      attr_reader :properties, :required
+
+      def initialize(properties: {}, required: [])
+        @properties = properties
+        @required = required.map(&:to_sym)
+      end
+
+      def to_h
+        { type: "object", properties:, required: }
+      end
+
+      def missing_required_arguments?(arguments)
+        missing_required_arguments(arguments).any?
+      end
+
+      def missing_required_arguments(arguments)
+        (required - arguments.keys.map(&:to_sym))
+      end
+    end
+  end
+end

data/lib/mcp/tool/response.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module MCP
+  class Tool
+    class Response
+      attr_reader :content, :is_error
+
+      def initialize(content, is_error = false)
+        @content = content
+        @is_error = is_error
+      end
+
+      def to_h
+        { content:, isError: is_error }.compact
+      end
+    end
+  end
+end

data/lib/mcp/tool.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module MCP
+  class Tool
+    class << self
+      NOT_SET = Object.new
+
+      attr_reader :description_value
+      attr_reader :input_schema_value
+      attr_reader :annotations_value
+
+      def call(*args, server_context:)
+        raise NotImplementedError, "Subclasses must implement call"
+      end
+
+      def to_h
+        result = {
+          name: name_value,
+          description: description_value,
+          inputSchema: input_schema_value.to_h,
+        }
+        result[:annotations] = annotations_value.to_h if annotations_value
+        result
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@name_value, nil)
+        subclass.instance_variable_set(:@description_value, nil)
+        subclass.instance_variable_set(:@input_schema_value, nil)
+        subclass.instance_variable_set(:@annotations_value, nil)
+      end
+
+      def tool_name(value = NOT_SET)
+        if value == NOT_SET
+          name_value
+        else
+          @name_value = value
+        end
+      end
+
+      def name_value
+        @name_value || StringUtils.handle_from_class_name(name)
+      end
+
+      def description(value = NOT_SET)
+        if value == NOT_SET
+          @description_value
+        else
+          @description_value = value
+        end
+      end
+
+      def input_schema(value = NOT_SET)
+        if value == NOT_SET
+          input_schema_value
+        elsif value.is_a?(Hash)
+          properties = value[:properties] || value["properties"] || {}
+          required = value[:required] || value["required"] || []
+          @input_schema_value = InputSchema.new(properties:, required:)
+        elsif value.is_a?(InputSchema)
+          @input_schema_value = value
+        end
+      end
+
+      def annotations(hash = NOT_SET)
+        if hash == NOT_SET
+          @annotations_value
+        else
+          @annotations_value = Annotations.new(**hash)
+        end
+      end
+
+      def define(name: nil, description: nil, input_schema: nil, annotations: nil, &block)
+        Class.new(self) do
+          tool_name name
+          description description
+          input_schema input_schema
+          self.annotations(annotations) if annotations
+          define_singleton_method(:call, &block) if block
+        end
+      end
+    end
+  end
+end

data/lib/mcp/transport.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module MCP
+  class Transport
+    def initialize(server)
+      @server = server
+    end
+
+    def send_response(response)
+      raise NotImplementedError, "Subclasses must implement send_response"
+    end
+
+    def open
+      raise NotImplementedError, "Subclasses must implement open"
+    end
+
+    def close
+      raise NotImplementedError, "Subclasses must implement close"
+    end
+
+    private
+
+    def handle_request(request)
+      response = @server.handle(request)
+      send_response(response) if response
+    end
+
+    def handle_json_request(request)
+      response = @server.handle_json(request)
+      send_response(response) if response
+    end
+  end
+end

data/lib/mcp/transports/stdio.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "../transport"
+require "json"
+
+module MCP
+  module Transports
+    class StdioTransport < Transport
+      def initialize(server)
+        @server = server
+        @open = false
+        $stdin.set_encoding("UTF-8")
+        $stdout.set_encoding("UTF-8")
+        super
+      end
+
+      def open
+        @open = true
+        while @open && (line = $stdin.gets)
+          handle_json_request(line.strip)
+        end
+      end
+
+      def close
+        @open = false
+      end
+
+      def send_response(message)
+        json_message = message.is_a?(String) ? message : JSON.generate(message)
+        $stdout.puts(json_message)
+        $stdout.flush
+      end
+    end
+  end
+end

data/lib/mcp/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MCP
+  VERSION = "0.1.0"
+end

data/lib/mcp.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "mcp/server"
+require_relative "mcp/string_utils"
+require_relative "mcp/tool"
+require_relative "mcp/tool/input_schema"
+require_relative "mcp/tool/annotations"
+require_relative "mcp/tool/response"
+require_relative "mcp/content"
+require_relative "mcp/resource"
+require_relative "mcp/resource/contents"
+require_relative "mcp/resource/embedded"
+require_relative "mcp/resource_template"
+require_relative "mcp/prompt"
+require_relative "mcp/prompt/argument"
+require_relative "mcp/prompt/message"
+require_relative "mcp/prompt/result"
+require_relative "mcp/version"
+require_relative "mcp/configuration"
+require_relative "mcp/methods"
+
+module MCP
+  class << self
+    def configure
+      yield(configuration)
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+  end
+
+  class Annotations
+    attr_reader :audience, :priority
+
+    def initialize(audience: nil, priority: nil)
+      @audience = audience
+      @priority = priority
+    end
+  end
+end

data/mcp.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "lib/mcp/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "mcp"
+  spec.version       = MCP::VERSION
+  spec.authors       = ["Model Context Protocol"]
+  spec.email         = ["mcp-support@anthropic.com"]
+
+  spec.summary       = "The official Ruby SDK for Model Context Protocol servers and clients"
+  spec.description   = spec.summary
+  spec.homepage      = "https://github.com/modelcontextprotocol/ruby-sdk"
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  spec.files = Dir.chdir(File.expand_path("..", __FILE__)) do
+    %x(git ls-files -z).split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency("json_rpc_handler", "~> 0.1")
+  spec.add_development_dependency("activesupport")
+  spec.add_development_dependency("sorbet-static-and-runtime")
+end