mcp 0.2.0 → 0.4.0

data/lib/mcp/prompt.rb

@@ -1,4 +1,3 @@
-# typed: strict
 # frozen_string_literal: true
 
 module MCP
@@ -6,22 +5,32 @@ module MCP
     class << self
       NOT_SET = Object.new
 
+      attr_reader :title_value
       attr_reader :description_value
       attr_reader :arguments_value
+      attr_reader :meta_value
 
       def template(args, server_context: nil)
         raise NotImplementedError, "Subclasses must implement template"
       end
 
       def to_h
-        { name: name_value, description: description_value, arguments: arguments_value.map(&:to_h) }.compact
+        {
+          name: name_value,
+          title: title_value,
+          description: description_value,
+          arguments: arguments_value&.map(&:to_h),
+          _meta: meta_value,
+        }.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(:@arguments_value, nil)
+        subclass.instance_variable_set(:@meta_value, nil)
       end
 
       def prompt_name(value = NOT_SET)
@@ -36,6 +45,14 @@ module MCP
         @name_value || StringUtils.handle_from_class_name(name)
       end
 
+      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
@@ -52,14 +69,24 @@ module MCP
         end
       end
 
-      def define(name: nil, description: nil, arguments: [], &block)
+      def meta(value = NOT_SET)
+        if value == NOT_SET
+          @meta_value
+        else
+          @meta_value = value
+        end
+      end
+
+      def define(name: nil, title: nil, description: nil, arguments: [], meta: nil, &block)
         Class.new(self) do
           prompt_name name
+          title title
           description description
           arguments arguments
           define_singleton_method(:template) do |args, server_context: nil|
             instance_exec(args, server_context:, &block)
           end
+          meta meta
         end
       end
 

data/lib/mcp/resource/contents.rb

@@ -1,4 +1,3 @@
-# typed: strict
 # frozen_string_literal: true
 
 module MCP

data/lib/mcp/resource/embedded.rb

@@ -1,4 +1,3 @@
-# typed: strict
 # frozen_string_literal: true
 
 module MCP

data/lib/mcp/resource.rb

@@ -1,23 +1,24 @@
-# typed: strict
 # frozen_string_literal: true
 
 module MCP
   class Resource
-    attr_reader :uri, :name, :description, :mime_type
+    attr_reader :uri, :name, :title, :description, :mime_type
 
-    def initialize(uri:, name:, description: nil, mime_type: nil)
+    def initialize(uri:, name:, title: nil, description: nil, mime_type: nil)
       @uri = uri
       @name = name
+      @title = title
       @description = description
       @mime_type = mime_type
     end
 
     def to_h
       {
-        uri: @uri,
-        name: @name,
-        description: @description,
-        mimeType: @mime_type,
+        uri: uri,
+        name: name,
+        title: title,
+        description: description,
+        mimeType: mime_type,
       }.compact
     end
   end

data/lib/mcp/resource_template.rb

@@ -1,23 +1,24 @@
-# typed: strict
 # frozen_string_literal: true
 
 module MCP
   class ResourceTemplate
-    attr_reader :uri_template, :name, :description, :mime_type
+    attr_reader :uri_template, :name, :title, :description, :mime_type
 
-    def initialize(uri_template:, name:, description: nil, mime_type: nil)
+    def initialize(uri_template:, name:, title: nil, description: nil, mime_type: nil)
       @uri_template = uri_template
       @name = name
+      @title = title
       @description = description
       @mime_type = mime_type
     end
 
     def to_h
       {
-        uriTemplate: @uri_template,
-        name: @name,
-        description: @description,
-        mimeType: @mime_type,
+        uriTemplate: uri_template,
+        name: name,
+        title: title,
+        description: description,
+        mimeType: mime_type,
       }.compact
     end
   end

data/lib/mcp/server/transports/streamable_http_transport.rb

@@ -34,7 +34,13 @@ module MCP
           end
         end
 
-        def send_notification(notification, session_id: nil)
+        def send_notification(method, params = nil, session_id: nil)
+          notification = {
+            jsonrpc: "2.0",
+            method:,
+          }
+          notification[:params] = params if params
+
           @mutex.synchronize do
             if session_id
               # Send to specific session
@@ -102,6 +108,8 @@ module MCP
 
           if body["method"] == "initialize"
             handle_initialization(body_string, body)
+          elsif notification?(body) || response?(body)
+            handle_accepted
           else
             handle_regular_request(body_string, session_id)
           end
@@ -160,6 +168,14 @@ module MCP
           [400, { "Content-Type" => "application/json" }, [{ error: "Invalid JSON" }.to_json]]
         end
 
+        def notification?(body)
+          !body["id"] && !!body["method"]
+        end
+
+        def response?(body)
+          !!body["id"] && !body["method"]
+        end
+
         def handle_initialization(body_string, body)
           session_id = SecureRandom.uuid
 
@@ -179,6 +195,10 @@ module MCP
           [200, headers, [response]]
         end
 
+        def handle_accepted
+          [202, {}, []]
+        end
+
         def handle_regular_request(body_string, session_id)
           # If session ID is provided, but not in the sessions hash, return an error
           if session_id && !@sessions.key?(session_id)

data/lib/mcp/server.rb

@@ -31,11 +31,13 @@ module MCP
 
     include Instrumentation
 
-    attr_accessor :name, :version, :tools, :prompts, :resources, :server_context, :configuration, :capabilities, :transport
+    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: [],
@@ -46,7 +48,9 @@ module MCP
       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
@@ -54,6 +58,9 @@ module MCP
       @resource_index = index_resources_by_uri(resources)
       @server_context = server_context
       @configuration = MCP.configuration.merge(configuration)
+
+      validate!
+
       @capabilities = capabilities || default_capabilities
 
       @handlers = {
@@ -66,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 => ->(_) {},
@@ -88,13 +96,15 @@ 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, meta: nil, &block)
+      tool = Tool.define(name:, title:, description:, input_schema:, annotations:, meta:, &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
 
@@ -160,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
@@ -209,8 +238,9 @@ module MCP
     def server_info
       @server_info ||= {
         name:,
+        title:,
         version:,
-      }
+      }.compact
     end
 
     def init(request)
@@ -218,11 +248,12 @@ module MCP
         protocolVersion: configuration.protocol_version,
         capabilities: capabilities,
         serverInfo: server_info,
-      }
+        instructions: instructions,
+      }.compact
     end
 
     def list_tools(request)
-      @tools.map { |_, tool| tool.to_h }
+      @tools.values.map(&:to_h)
     end
 
     def call_tool(request)
@@ -233,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)
@@ -262,7 +293,7 @@ module MCP
     end
 
     def list_prompts(request)
-      @prompts.map { |_, prompt| prompt.to_h }
+      @prompts.values.map(&:to_h)
     end
 
     def get_prompt(request)
@@ -307,14 +338,12 @@ module MCP
 
     def accepts_server_context?(method_object)
       parameters = method_object.parameters
-      accepts_server_context = parameters.any? { |_type, name| name == :server_context }
-      has_kwargs = parameters.any? { |type, _| type == :keyrest }
 
-      accepts_server_context || has_kwargs
+      parameters.any? { |type, name| type == :keyrest || name == :server_context }
     end
 
     def call_tool_with_args(tool, arguments)
-      args = arguments.transform_keys(&:to_sym)
+      args = arguments&.transform_keys(&:to_sym) || {}
 
       if accepts_server_context?(tool.method(:call))
         tool.call(**args, server_context: server_context).to_h

data/lib/mcp/string_utils.rb

@@ -1,4 +1,3 @@
-# typed: strict
 # frozen_string_literal: true
 
 module MCP

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

@@ -15,8 +15,13 @@ module MCP
         validate_schema!
       end
 
+      def ==(other)
+        other.is_a?(InputSchema) && properties == other.properties && required == other.required
+      end
+
       def to_h
-        { type: "object", properties: }.tap do |hsh|
+        { type: "object" }.tap do |hsh|
+          hsh[:properties] = properties if properties.any?
           hsh[:required] = required if required.any?
         end
       end
@@ -45,7 +50,10 @@ module MCP
           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
+        metaschema_path = Pathname.new(JSON::Validator.validator_for_name("draft4").metaschema)
+        # Converts metaschema to a file URI for cross-platform compatibility
+        metaschema_uri = JSON::Util::URI.file_uri(metaschema_path.expand_path.cleanpath.to_s.tr("\\", "/"))
+        metaschema = metaschema_uri.to_s
         errors = JSON::Validator.fully_validate(metaschema, schema, schema_reader: schema_reader)
         if errors.any?
           raise ArgumentError, "Invalid JSON Schema: #{errors.join(", ")}"

data/lib/mcp/tool/output_schema.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "json-schema"
+
+module MCP
+  class Tool
+    class OutputSchema
+      class ValidationError < StandardError; end
+
+      attr_reader :schema
+
+      def initialize(schema = {})
+        @schema = deep_transform_keys(JSON.parse(JSON.dump(schema)), &:to_sym)
+        @schema[:type] ||= "object"
+        validate_schema!
+      end
+
+      def ==(other)
+        other.is_a?(OutputSchema) && schema == other.schema
+      end
+
+      def to_h
+        @schema
+      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 deep_transform_keys(schema, &block)
+        case schema
+        when Hash
+          schema.each_with_object({}) do |(key, value), result|
+            if key.casecmp?("$ref")
+              raise ArgumentError, "Invalid JSON Schema: $ref is not allowed in tool output schemas"
+            end
+
+            result[yield(key)] = deep_transform_keys(value, &block)
+          end
+        when Array
+          schema.map { |e| deep_transform_keys(e, &block) }
+        else
+          schema
+        end
+      end
+
+      def validate_schema!
+        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_path = Pathname.new(JSON::Validator.validator_for_name("draft4").metaschema)
+        # Converts metaschema to a file URI for cross-platform compatibility
+        metaschema_uri = JSON::Util::URI.file_uri(metaschema_path.expand_path.cleanpath.to_s.tr("\\", "/"))
+        metaschema = metaschema_uri.to_s
+        errors = JSON::Validator.fully_validate(metaschema, schema, schema_reader: schema_reader)
+        if errors.any?
+          raise ArgumentError, "Invalid JSON Schema: #{errors.join(", ")}"
+        end
+      end
+    end
+  end
+end

data/lib/mcp/tool/response.rb

@@ -3,15 +3,27 @@
 module MCP
   class Tool
     class Response
-      attr_reader :content, :is_error
+      NOT_GIVEN = Object.new.freeze
 
-      def initialize(content, is_error = false)
-        @content = content
-        @is_error = is_error
+      attr_reader :content, :structured_content
+
+      def initialize(content = nil, deprecated_error = NOT_GIVEN, error: false, structured_content: nil)
+        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
+
+        @content = content || []
+        @error = error
+        @structured_content = structured_content
+      end
+
+      def error?
+        !!@error
       end
 
       def to_h
-        { content:, isError: is_error }.compact
+        { content:, isError: error?, structuredContent: @structured_content }.compact
       end
     end
   end

data/lib/mcp/tool.rb

@@ -5,30 +5,36 @@ 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
+      attr_reader :meta_value
 
       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,
+          _meta: meta_value,
+        }.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)
+        subclass.instance_variable_set(:@meta_value, nil)
       end
 
       def tool_name(value = NOT_SET)
@@ -43,6 +49,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 +83,24 @@ module MCP
         end
       end
 
+      def output_schema(value = NOT_SET)
+        if value == NOT_SET
+          output_schema_value
+        elsif value.is_a?(Hash)
+          @output_schema_value = OutputSchema.new(value)
+        elsif value.is_a?(OutputSchema)
+          @output_schema_value = value
+        end
+      end
+
+      def meta(value = NOT_SET)
+        if value == NOT_SET
+          @meta_value
+        else
+          @meta_value = value
+        end
+      end
+
       def annotations(hash = NOT_SET)
         if hash == NOT_SET
           @annotations_value
@@ -71,11 +109,14 @@ 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, meta: nil, annotations: nil, &block)
         Class.new(self) do
           tool_name name
+          title title
           description description
           input_schema input_schema
+          meta meta
+          output_schema output_schema
           self.annotations(annotations) if annotations
           define_singleton_method(:call, &block) if block
         end

data/lib/mcp/version.rb

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

data/lib/mcp.rb

@@ -18,10 +18,14 @@ require_relative "mcp/server/transports/stdio_transport"
 require_relative "mcp/string_utils"
 require_relative "mcp/tool"
 require_relative "mcp/tool/input_schema"
+require_relative "mcp/tool/output_schema"
 require_relative "mcp/tool/response"
 require_relative "mcp/tool/annotations"
 require_relative "mcp/transport"
 require_relative "mcp/version"
+require_relative "mcp/client"
+require_relative "mcp/client/http"
+require_relative "mcp/client/tool"
 
 module MCP
   class << self