mcp 0.2.0 → 0.3.0

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, &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
 
@@ -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,7 +248,8 @@ module MCP
         protocolVersion: configuration.protocol_version,
         capabilities: capabilities,
         serverInfo: server_info,
-      }
+        instructions: instructions,
+      }.compact
     end
 
     def list_tools(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)
@@ -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/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

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,8 +5,8 @@ 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: nil)
@@ -14,20 +14,23 @@ module MCP
       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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MCP
-  VERSION = "0.2.0"
+  VERSION = "0.3.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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Model Context Protocol
@@ -67,6 +67,9 @@ files:
 - examples/streamable_http_client.rb
 - examples/streamable_http_server.rb
 - lib/mcp.rb
+- lib/mcp/client.rb
+- lib/mcp/client/http.rb
+- lib/mcp/client/tool.rb
 - lib/mcp/configuration.rb
 - lib/mcp/content.rb
 - lib/mcp/instrumentation.rb
@@ -87,6 +90,7 @@ files:
 - lib/mcp/tool.rb
 - lib/mcp/tool/annotations.rb
 - lib/mcp/tool/input_schema.rb
+- lib/mcp/tool/output_schema.rb
 - lib/mcp/tool/response.rb
 - lib/mcp/transport.rb
 - lib/mcp/transports/stdio.rb
@@ -113,7 +117,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: The official Ruby SDK for Model Context Protocol servers and clients
 test_files: []