mcp 0.1.0 → 0.3.0

data/lib/mcp/server.rb

@@ -20,24 +20,37 @@ module MCP
       end
     end
 
+    class MethodAlreadyDefinedError < StandardError
+      attr_reader :method_name
+
+      def initialize(method_name)
+        super("Method #{method_name} already defined")
+        @method_name = method_name
+      end
+    end
+
     include Instrumentation
 
-    attr_writer :capabilities
-    attr_accessor :name, :version, :tools, :prompts, :resources, :server_context, :configuration
+    attr_accessor :name, :title, :version, :instructions, :tools, :prompts, :resources, :server_context, :configuration, :capabilities, :transport
 
     def initialize(
       name: "model_context_protocol",
+      title: nil,
       version: DEFAULT_VERSION,
+      instructions: nil,
       tools: [],
       prompts: [],
       resources: [],
       resource_templates: [],
       server_context: nil,
       configuration: nil,
-      capabilities: nil
+      capabilities: nil,
+      transport: nil
     )
       @name = name
+      @title = title
       @version = version
+      @instructions = instructions
       @tools = tools.to_h { |t| [t.name_value, t] }
       @prompts = prompts.to_h { |p| [p.name_value, p] }
       @resources = resources
@@ -46,6 +59,10 @@ module MCP
       @server_context = server_context
       @configuration = MCP.configuration.merge(configuration)
 
+      validate!
+
+      @capabilities = capabilities || default_capabilities
+
       @handlers = {
         Methods::RESOURCES_LIST => method(:list_resources),
         Methods::RESOURCES_READ => method(:read_resource_no_content),
@@ -56,6 +73,7 @@ module MCP
         Methods::PROMPTS_GET => method(:get_prompt),
         Methods::INITIALIZE => method(:init),
         Methods::PING => ->(_) { {} },
+        Methods::NOTIFICATIONS_INITIALIZED => ->(_) {},
 
         # No op handlers for currently unsupported methods
         Methods::RESOURCES_SUBSCRIBE => ->(_) {},
@@ -63,10 +81,7 @@ module MCP
         Methods::COMPLETION_COMPLETE => ->(_) {},
         Methods::LOGGING_SET_LEVEL => ->(_) {},
       }
-    end
-
-    def capabilities
-      @capabilities ||= determine_capabilities
+      @transport = transport
     end
 
     def handle(request)
@@ -81,16 +96,50 @@ module MCP
       end
     end
 
-    def define_tool(name: nil, description: nil, input_schema: nil, annotations: nil, &block)
-      tool = Tool.define(name:, description:, input_schema:, annotations:, &block)
+    def define_tool(name: nil, title: nil, description: nil, input_schema: nil, annotations: nil, &block)
+      tool = Tool.define(name:, title:, description:, input_schema:, annotations:, &block)
       @tools[tool.name_value] = tool
+
+      validate!
     end
 
-    def define_prompt(name: nil, description: nil, arguments: [], &block)
-      prompt = Prompt.define(name:, description:, arguments:, &block)
+    def define_prompt(name: nil, title: nil, description: nil, arguments: [], &block)
+      prompt = Prompt.define(name:, title:, description:, arguments:, &block)
       @prompts[prompt.name_value] = prompt
     end
 
+    def define_custom_method(method_name:, &block)
+      if @handlers.key?(method_name)
+        raise MethodAlreadyDefinedError, method_name
+      end
+
+      @handlers[method_name] = block
+    end
+
+    def notify_tools_list_changed
+      return unless @transport
+
+      @transport.send_notification(Methods::NOTIFICATIONS_TOOLS_LIST_CHANGED)
+    rescue => e
+      report_exception(e, { notification: "tools_list_changed" })
+    end
+
+    def notify_prompts_list_changed
+      return unless @transport
+
+      @transport.send_notification(Methods::NOTIFICATIONS_PROMPTS_LIST_CHANGED)
+    rescue => e
+      report_exception(e, { notification: "prompts_list_changed" })
+    end
+
+    def notify_resources_list_changed
+      return unless @transport
+
+      @transport.send_notification(Methods::NOTIFICATIONS_RESOURCES_LIST_CHANGED)
+    rescue => e
+      report_exception(e, { notification: "resources_list_changed" })
+    end
+
     def resources_list_handler(&block)
       @handlers[Methods::RESOURCES_LIST] = block
     end
@@ -121,6 +170,25 @@ module MCP
 
     private
 
+    def validate!
+      if @configuration.protocol_version == "2024-11-05"
+        if @instructions
+          message = "`instructions` supported by protocol version 2025-03-26 or higher"
+          raise ArgumentError, message
+        end
+
+        error_tool_names = @tools.each_with_object([]) do |(tool_name, tool), error_tool_names|
+          if tool.annotations
+            error_tool_names << tool_name
+          end
+        end
+        unless error_tool_names.empty?
+          message = "Error occurred in #{error_tool_names.join(", ")}. `annotations` are supported by protocol version 2025-03-26 or higher"
+          raise ArgumentError, message
+        end
+      end
+    end
+
     def handle_request(request, method)
       handler = @handlers[method]
       unless handler
@@ -159,41 +227,36 @@ module MCP
       }
     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)
+    def default_capabilities
       {
-        prompts: defines_prompts ? {} : nil,
-        resources: defines_resources || defines_resource_templates ? {} : nil,
-        tools: defines_tools ? {} : nil,
-      }.compact
+        tools: { listChanged: true },
+        prompts: { listChanged: true },
+        resources: { listChanged: true },
+      }
     end
 
     def server_info
       @server_info ||= {
         name:,
+        title:,
         version:,
-      }
+      }.compact
     end
 
     def init(request)
-      add_instrumentation_data(method: Methods::INITIALIZE)
       {
         protocolVersion: configuration.protocol_version,
         capabilities: capabilities,
         serverInfo: server_info,
-      }
+        instructions: instructions,
+      }.compact
     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
@@ -201,7 +264,7 @@ module MCP
         raise RequestHandlerError.new("Tool not found #{tool_name}", request, error_type: :tool_not_found)
       end
 
-      arguments = request[:arguments]
+      arguments = request[:arguments] || {}
       add_instrumentation_data(tool_name:)
 
       if tool.input_schema&.missing_required_arguments?(arguments)
@@ -213,26 +276,27 @@ module MCP
         )
       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
+      if configuration.validate_tool_call_arguments && tool.input_schema
+        begin
+          tool.input_schema.validate_arguments(arguments)
+        rescue Tool::InputSchema::ValidationError => e
+          add_instrumentation_data(error: :invalid_schema)
+          raise RequestHandlerError.new(e.message, request, error_type: :invalid_schema)
         end
+      end
+
+      begin
+        call_tool_with_args(tool, arguments)
       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
@@ -245,25 +309,20 @@ module MCP
       prompt_args = request[:arguments]
       prompt.validate_arguments!(prompt_args)
 
-      prompt.template(prompt_args, server_context:).to_h
+      call_prompt_template_with_args(prompt, prompt_args)
     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
 
@@ -277,22 +336,27 @@ module MCP
       end
     end
 
-    def tool_call_parameters(tool)
-      method_def = tool_call_method_def(tool)
-      method_def.parameters.flatten
+    def accepts_server_context?(method_object)
+      parameters = method_object.parameters
+
+      parameters.any? { |type, name| type == :keyrest || name == :server_context }
     end
 
-    def tool_call_method_def(tool)
-      method = tool.method(:call)
+    def call_tool_with_args(tool, arguments)
+      args = arguments&.transform_keys(&:to_sym) || {}
 
-      if defined?(T::Utils) && T::Utils.respond_to?(:signature_for_method)
-        sorbet_typed_method_definition = T::Utils.signature_for_method(method)&.method
+      if accepts_server_context?(tool.method(:call))
+        tool.call(**args, server_context: server_context).to_h
+      else
+        tool.call(**args).to_h
+      end
+    end
 
-        # 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
+    def call_prompt_template_with_args(prompt, args)
+      if accepts_server_context?(prompt.method(:template))
+        prompt.template(args, server_context: server_context).to_h
       else
-        method
+        prompt.template(args).to_h
       end
     end
   end

data/lib/mcp/tool/annotations.rb

@@ -3,9 +3,9 @@
 module MCP
   class Tool
     class Annotations
-      attr_reader :title, :read_only_hint, :destructive_hint, :idempotent_hint, :open_world_hint
+      attr_reader :destructive_hint, :idempotent_hint, :open_world_hint, :read_only_hint, :title
 
-      def initialize(title: nil, read_only_hint: nil, destructive_hint: nil, idempotent_hint: nil, open_world_hint: nil)
+      def initialize(destructive_hint: true, idempotent_hint: false, open_world_hint: true, read_only_hint: false, title: nil)
         @title = title
         @read_only_hint = read_only_hint
         @destructive_hint = destructive_hint
@@ -15,11 +15,11 @@ module MCP
 
       def to_h
         {
-          title:,
-          readOnlyHint: read_only_hint,
           destructiveHint: destructive_hint,
           idempotentHint: idempotent_hint,
           openWorldHint: open_world_hint,
+          readOnlyHint: read_only_hint,
+          title:,
         }.compact
       end
     end

data/lib/mcp/tool/input_schema.rb

@@ -1,17 +1,29 @@
 # frozen_string_literal: true
 
+require "json-schema"
+
 module MCP
   class Tool
     class InputSchema
+      class ValidationError < StandardError; end
+
       attr_reader :properties, :required
 
       def initialize(properties: {}, required: [])
         @properties = properties
         @required = required.map(&:to_sym)
+        validate_schema!
+      end
+
+      def ==(other)
+        other.is_a?(InputSchema) && properties == other.properties && required == other.required
       end
 
       def to_h
-        { type: "object", properties:, required: }
+        { type: "object" }.tap do |hsh|
+          hsh[:properties] = properties if properties.any?
+          hsh[:required] = required if required.any?
+        end
       end
 
       def missing_required_arguments?(arguments)
@@ -21,6 +33,42 @@ module MCP
       def missing_required_arguments(arguments)
         (required - arguments.keys.map(&:to_sym))
       end
+
+      def validate_arguments(arguments)
+        errors = JSON::Validator.fully_validate(to_h, arguments)
+        if errors.any?
+          raise ValidationError, "Invalid arguments: #{errors.join(", ")}"
+        end
+      end
+
+      private
+
+      def validate_schema!
+        check_for_refs!
+        schema = to_h
+        schema_reader = JSON::Schema::Reader.new(
+          accept_uri: false,
+          accept_file: ->(path) { path.to_s.start_with?(Gem.loaded_specs["json-schema"].full_gem_path) },
+        )
+        metaschema = JSON::Validator.validator_for_name("draft4").metaschema
+        errors = JSON::Validator.fully_validate(metaschema, schema, schema_reader: schema_reader)
+        if errors.any?
+          raise ArgumentError, "Invalid JSON Schema: #{errors.join(", ")}"
+        end
+      end
+
+      def check_for_refs!(obj = properties)
+        case obj
+        when Hash
+          if obj.key?("$ref") || obj.key?(:$ref)
+            raise ArgumentError, "Invalid JSON Schema: $ref is not allowed in tool input schemas"
+          end
+
+          obj.each_value { |value| check_for_refs!(value) }
+        when Array
+          obj.each { |item| check_for_refs!(item) }
+        end
+      end
     end
   end
 end

data/lib/mcp/tool/output_schema.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "json-schema"
+
+module MCP
+  class Tool
+    class OutputSchema
+      class ValidationError < StandardError; end
+
+      attr_reader :properties, :required
+
+      def initialize(properties: {}, required: [])
+        @properties = properties
+        @required = required.map(&:to_sym)
+        validate_schema!
+      end
+
+      def ==(other)
+        other.is_a?(OutputSchema) && properties == other.properties && required == other.required
+      end
+
+      def to_h
+        { type: "object" }.tap do |hsh|
+          hsh[:properties] = properties if properties.any?
+          hsh[:required] = required if required.any?
+        end
+      end
+
+      def validate_result(result)
+        errors = JSON::Validator.fully_validate(to_h, result)
+        if errors.any?
+          raise ValidationError, "Invalid result: #{errors.join(", ")}"
+        end
+      end
+
+      private
+
+      def validate_schema!
+        check_for_refs!
+        schema = to_h
+        schema_reader = JSON::Schema::Reader.new(
+          accept_uri: false,
+          accept_file: ->(path) { path.to_s.start_with?(Gem.loaded_specs["json-schema"].full_gem_path) },
+        )
+        metaschema = JSON::Validator.validator_for_name("draft4").metaschema
+        errors = JSON::Validator.fully_validate(metaschema, schema, schema_reader: schema_reader)
+        if errors.any?
+          raise ArgumentError, "Invalid JSON Schema: #{errors.join(", ")}"
+        end
+      end
+
+      def check_for_refs!(obj = properties)
+        case obj
+        when Hash
+          if obj.key?("$ref") || obj.key?(:$ref)
+            raise ArgumentError, "Invalid JSON Schema: $ref is not allowed in tool output schemas"
+          end
+
+          obj.each_value { |value| check_for_refs!(value) }
+        when Array
+          obj.each { |item| check_for_refs!(item) }
+        end
+      end
+    end
+  end
+end

data/lib/mcp/tool/response.rb

@@ -3,15 +3,26 @@
 module MCP
   class Tool
     class Response
-      attr_reader :content, :is_error
+      NOT_GIVEN = Object.new.freeze
+
+      attr_reader :content
+
+      def initialize(content, deprecated_error = NOT_GIVEN, error: false)
+        if deprecated_error != NOT_GIVEN
+          warn("Passing `error` with the 2nd argument of `Response.new` is deprecated. Use keyword argument like `Response.new(content, error: error)` instead.", uplevel: 1)
+          error = deprecated_error
+        end
 
-      def initialize(content, is_error = false)
         @content = content
-        @is_error = is_error
+        @error = error
+      end
+
+      def error?
+        !!@error
       end
 
       def to_h
-        { content:, isError: is_error }.compact
+        { content:, isError: error? }.compact
       end
     end
   end

data/lib/mcp/tool.rb

@@ -5,29 +5,32 @@ module MCP
     class << self
       NOT_SET = Object.new
 
+      attr_reader :title_value
       attr_reader :description_value
-      attr_reader :input_schema_value
       attr_reader :annotations_value
 
-      def call(*args, server_context:)
+      def call(*args, server_context: nil)
         raise NotImplementedError, "Subclasses must implement call"
       end
 
       def to_h
-        result = {
+        {
           name: name_value,
+          title: title_value,
           description: description_value,
           inputSchema: input_schema_value.to_h,
-        }
-        result[:annotations] = annotations_value.to_h if annotations_value
-        result
+          outputSchema: @output_schema_value&.to_h,
+          annotations: annotations_value&.to_h,
+        }.compact
       end
 
       def inherited(subclass)
         super
         subclass.instance_variable_set(:@name_value, nil)
+        subclass.instance_variable_set(:@title_value, nil)
         subclass.instance_variable_set(:@description_value, nil)
         subclass.instance_variable_set(:@input_schema_value, nil)
+        subclass.instance_variable_set(:@output_schema_value, nil)
         subclass.instance_variable_set(:@annotations_value, nil)
       end
 
@@ -43,6 +46,20 @@ module MCP
         @name_value || StringUtils.handle_from_class_name(name)
       end
 
+      def input_schema_value
+        @input_schema_value || InputSchema.new
+      end
+
+      attr_reader :output_schema_value
+
+      def title(value = NOT_SET)
+        if value == NOT_SET
+          @title_value
+        else
+          @title_value = value
+        end
+      end
+
       def description(value = NOT_SET)
         if value == NOT_SET
           @description_value
@@ -63,6 +80,18 @@ module MCP
         end
       end
 
+      def output_schema(value = NOT_SET)
+        if value == NOT_SET
+          output_schema_value
+        elsif value.is_a?(Hash)
+          properties = value[:properties] || value["properties"] || {}
+          required = value[:required] || value["required"] || []
+          @output_schema_value = OutputSchema.new(properties:, required:)
+        elsif value.is_a?(OutputSchema)
+          @output_schema_value = value
+        end
+      end
+
       def annotations(hash = NOT_SET)
         if hash == NOT_SET
           @annotations_value
@@ -71,11 +100,13 @@ module MCP
         end
       end
 
-      def define(name: nil, description: nil, input_schema: nil, annotations: nil, &block)
+      def define(name: nil, title: nil, description: nil, input_schema: nil, output_schema: nil, annotations: nil, &block)
         Class.new(self) do
           tool_name name
+          title title
           description description
           input_schema input_schema
+          output_schema output_schema
           self.annotations(annotations) if annotations
           define_singleton_method(:call, &block) if block
         end

data/lib/mcp/transport.rb

@@ -2,32 +2,44 @@
 
 module MCP
   class Transport
+    # Initialize the transport with the server instance
     def initialize(server)
       @server = server
     end
 
+    # Send a response to the client
     def send_response(response)
       raise NotImplementedError, "Subclasses must implement send_response"
     end
 
+    # Open the transport connection
     def open
       raise NotImplementedError, "Subclasses must implement open"
     end
 
+    # Close the transport connection
     def close
       raise NotImplementedError, "Subclasses must implement close"
     end
 
-    private
+    # Handle a JSON request
+    # Returns a response that should be sent back to the client
+    def handle_json_request(request)
+      response = @server.handle_json(request)
+      send_response(response) if response
+    end
 
+    # Handle an incoming request
+    # Returns a response that should be sent back to the client
     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
+    # Send a notification to the client
+    # Returns true if the notification was sent successfully
+    def send_notification(method, params = nil)
+      raise NotImplementedError, "Subclasses must implement send_notification"
     end
   end
 end

data/lib/mcp/transports/stdio.rb

@@ -1,35 +1,15 @@
 # frozen_string_literal: true
 
-require_relative "../transport"
-require "json"
+require_relative "../server/transports/stdio_transport"
+
+warn <<~MESSAGE, uplevel: 3
+  Use `require "mcp/server/transports/stdio_transport"` instead of `require "mcp/transports/stdio"`.
+  Also use `MCP::Server::Transports::StdioTransport` instead of `MCP::Transports::StdioTransport`.
+  This API is deprecated and will be removed in a future release.
+MESSAGE
 
 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
+    StdioTransport = Server::Transports::StdioTransport
   end
 end