mcp 0.3.0 → 0.5.0

data/lib/mcp/server.rb

@@ -1,10 +1,19 @@
 # frozen_string_literal: true
 
-require "json_rpc_handler"
+require_relative "../json_rpc_handler"
 require_relative "instrumentation"
 require_relative "methods"
 
 module MCP
+  class ToolNotUnique < StandardError
+    def initialize(duplicated_tool_names)
+      super(<<~MESSAGE)
+        Tool names should be unique. Use `tool_name` to assign unique names to:
+        #{duplicated_tool_names.join(", ")}
+      MESSAGE
+    end
+  end
+
   class Server
     DEFAULT_VERSION = "0.1.0"
 
@@ -31,12 +40,15 @@ module MCP
 
     include Instrumentation
 
-    attr_accessor :name, :title, :version, :instructions, :tools, :prompts, :resources, :server_context, :configuration, :capabilities, :transport
+    attr_accessor :description, :icons, :name, :title, :version, :website_url, :instructions, :tools, :prompts, :resources, :server_context, :configuration, :capabilities, :transport
 
     def initialize(
+      description: nil,
+      icons: [],
       name: "model_context_protocol",
       title: nil,
       version: DEFAULT_VERSION,
+      website_url: nil,
       instructions: nil,
       tools: [],
       prompts: [],
@@ -47,10 +59,14 @@ module MCP
       capabilities: nil,
       transport: nil
     )
+      @description = description
+      @icons = icons
       @name = name
       @title = title
       @version = version
+      @website_url = website_url
       @instructions = instructions
+      @tool_names = tools.map(&:name_value)
       @tools = tools.to_h { |t| [t.name_value, t] }
       @prompts = prompts.to_h { |p| [p.name_value, p] }
       @resources = resources
@@ -80,6 +96,7 @@ module MCP
         Methods::RESOURCES_UNSUBSCRIBE => ->(_) {},
         Methods::COMPLETION_COMPLETE => ->(_) {},
         Methods::LOGGING_SET_LEVEL => ->(_) {},
+        Methods::ELICITATION_CREATE => ->(_) {},
       }
       @transport = transport
     end
@@ -96,16 +113,21 @@ module MCP
       end
     end
 
-    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
+    def define_tool(name: nil, title: nil, description: nil, input_schema: nil, annotations: nil, meta: nil, &block)
+      tool = Tool.define(name: name, title: title, description: description, input_schema: input_schema, annotations: annotations, meta: meta, &block)
+      tool_name = tool.name_value
+
+      @tool_names << tool_name
+      @tools[tool_name] = tool
 
       validate!
     end
 
     def define_prompt(name: nil, title: nil, description: nil, arguments: [], &block)
-      prompt = Prompt.define(name:, title:, description:, arguments:, &block)
+      prompt = Prompt.define(name: name, title: title, description: description, arguments: arguments, &block)
       @prompts[prompt.name_value] = prompt
+
+      validate!
     end
 
     def define_custom_method(method_name:, &block)
@@ -171,6 +193,30 @@ module MCP
     private
 
     def validate!
+      validate_tool_name!
+
+      # NOTE: The draft protocol version is the next version after 2025-11-25.
+      if @configuration.protocol_version <= "2025-06-18"
+        if server_info.key?(:description)
+          message = "Error occurred in server_info. `description` is not supported in protocol version 2025-06-18 or earlier"
+          raise ArgumentError, message
+        end
+      end
+
+      if @configuration.protocol_version <= "2025-03-26"
+        if server_info.key?(:title) || server_info.key?(:websiteUrl)
+          message = "Error occurred in server_info. `title` or `website_url` are not supported in protocol version 2025-03-26 or earlier"
+          raise ArgumentError, message
+        end
+
+        primitive_titles = [@tools.values, @prompts.values, @resources, @resource_templates].flatten.map(&:title)
+
+        if primitive_titles.any?
+          message = "Error occurred in #{primitive_titles.join(", ")}. `title` is not supported in protocol version 2025-03-26 or earlier"
+          raise ArgumentError, message
+        end
+      end
+
       if @configuration.protocol_version == "2024-11-05"
         if @instructions
           message = "`instructions` supported by protocol version 2025-03-26 or higher"
@@ -189,6 +235,12 @@ module MCP
       end
     end
 
+    def validate_tool_name!
+      duplicated_tool_names = @tool_names.tally.filter_map { |name, count| name if count >= 2 }
+
+      raise ToolNotUnique, duplicated_tool_names unless duplicated_tool_names.empty?
+    end
+
     def handle_request(request, method)
       handler = @handlers[method]
       unless handler
@@ -237,9 +289,12 @@ module MCP
 
     def server_info
       @server_info ||= {
-        name:,
-        title:,
-        version:,
+        description: description,
+        icons: icons,
+        name: name,
+        title: title,
+        version: version,
+        websiteUrl: website_url,
       }.compact
     end
 
@@ -253,27 +308,27 @@ module MCP
     end
 
     def list_tools(request)
-      @tools.map { |_, tool| tool.to_h }
+      @tools.values.map(&:to_h)
     end
 
     def call_tool(request)
       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)
+        add_instrumentation_data(tool_name: tool_name, error: :tool_not_found)
+
+        return error_tool_response("Tool not found: #{tool_name}")
       end
 
       arguments = request[:arguments] || {}
-      add_instrumentation_data(tool_name:)
+      add_instrumentation_data(tool_name: 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,
-        )
+
+        missing = tool.input_schema.missing_required_arguments(arguments).join(", ")
+        return error_tool_response("Missing required arguments: #{missing}")
       end
 
       if configuration.validate_tool_call_arguments && tool.input_schema
@@ -281,19 +336,20 @@ module MCP
           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)
+
+          return error_tool_response(e.message)
         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
+      call_tool_with_args(tool, arguments)
+    rescue => e
+      report_exception(e, request: request)
+
+      error_tool_response("Internal error calling tool #{tool_name}: #{e.message}")
     end
 
     def list_prompts(request)
-      @prompts.map { |_, prompt| prompt.to_h }
+      @prompts.values.map(&:to_h)
     end
 
     def get_prompt(request)
@@ -304,7 +360,7 @@ module MCP
         raise RequestHandlerError.new("Prompt not found #{prompt_name}", request, error_type: :prompt_not_found)
       end
 
-      add_instrumentation_data(prompt_name:)
+      add_instrumentation_data(prompt_name: prompt_name)
 
       prompt_args = request[:arguments]
       prompt.validate_arguments!(prompt_args)
@@ -336,6 +392,16 @@ module MCP
       end
     end
 
+    def error_tool_response(text)
+      Tool::Response.new(
+        [{
+          type: "text",
+          text: text,
+        }],
+        error: true,
+      ).to_h
+    end
+
     def accepts_server_context?(method_object)
       parameters = method_object.parameters
 

data/lib/mcp/string_utils.rb

@@ -1,4 +1,3 @@
-# typed: strict
 # frozen_string_literal: true
 
 module MCP
@@ -16,9 +15,9 @@ module MCP
     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')
+      camel_cased_word
+        .gsub(/(?<=[A-Z])(?=[A-Z][a-z])/, "_")
+        .gsub(/(?<=[a-z\d])(?=[A-Z])/, "_")
         .tr("-", "_")
         .downcase
     end

data/lib/mcp/tool/annotations.rb

@@ -19,7 +19,7 @@ module MCP
           idempotentHint: idempotent_hint,
           openWorldHint: open_world_hint,
           readOnlyHint: read_only_hint,
-          title:,
+          title: title,
         }.compact
       end
     end

data/lib/mcp/tool/input_schema.rb

@@ -1,74 +1,28 @@
 # frozen_string_literal: true
 
-require "json-schema"
+require_relative "schema"
 
 module MCP
   class Tool
-    class InputSchema
+    class InputSchema < Schema
       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" }.tap do |hsh|
-          hsh[:properties] = properties if properties.any?
-          hsh[:required] = required if required.any?
-        end
-      end
-
       def missing_required_arguments?(arguments)
         missing_required_arguments(arguments).any?
       end
 
       def missing_required_arguments(arguments)
-        (required - arguments.keys.map(&:to_sym))
+        return [] unless schema[:required].is_a?(Array)
+
+        (schema[:required] - arguments.keys.map(&:to_s))
       end
 
       def validate_arguments(arguments)
-        errors = JSON::Validator.fully_validate(to_h, arguments)
+        errors = fully_validate(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

@@ -1,66 +1,18 @@
 # frozen_string_literal: true
 
-require "json-schema"
+require_relative "schema"
 
 module MCP
   class Tool
-    class OutputSchema
+    class OutputSchema < Schema
       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)
+        errors = fully_validate(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

@@ -5,16 +5,17 @@ module MCP
     class Response
       NOT_GIVEN = Object.new.freeze
 
-      attr_reader :content
+      attr_reader :content, :structured_content
 
-      def initialize(content, deprecated_error = NOT_GIVEN, error: false)
+      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
+        @content = content || []
         @error = error
+        @structured_content = structured_content
       end
 
       def error?
@@ -22,7 +23,7 @@ module MCP
       end
 
       def to_h
-        { content:, isError: error? }.compact
+        { content: content, isError: error?, structuredContent: @structured_content }.compact
       end
     end
   end

data/lib/mcp/tool/schema.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "json-schema"
+
+module MCP
+  class Tool
+    class Schema
+      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?(self.class) && schema == other.schema
+      end
+
+      def to_h
+        @schema
+      end
+
+      private
+
+      def fully_validate(data)
+        JSON::Validator.fully_validate(to_h, data)
+      end
+
+      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 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
+        gem_path = File.realpath(Gem.loaded_specs["json-schema"].full_gem_path)
+        schema_reader = JSON::Schema::Reader.new(
+          accept_uri: false,
+          accept_file: ->(path) { File.realpath(path.to_s).start_with?(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.rb

@@ -4,10 +4,13 @@ module MCP
   class Tool
     class << self
       NOT_SET = Object.new
+      MAX_LENGTH_OF_NAME = 128
 
       attr_reader :title_value
       attr_reader :description_value
+      attr_reader :icons_value
       attr_reader :annotations_value
+      attr_reader :meta_value
 
       def call(*args, server_context: nil)
         raise NotImplementedError, "Subclasses must implement call"
@@ -18,9 +21,11 @@ module MCP
           name: name_value,
           title: title_value,
           description: description_value,
+          icons: icons&.map(&:to_h),
           inputSchema: input_schema_value.to_h,
           outputSchema: @output_schema_value&.to_h,
           annotations: annotations_value&.to_h,
+          _meta: meta_value,
         }.compact
       end
 
@@ -29,9 +34,11 @@ module MCP
         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(:@icons_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)
@@ -39,11 +46,13 @@ module MCP
           name_value
         else
           @name_value = value
+
+          validate!
         end
       end
 
       def name_value
-        @name_value || StringUtils.handle_from_class_name(name)
+        @name_value || (name.nil? ? nil : StringUtils.handle_from_class_name(name))
       end
 
       def input_schema_value
@@ -68,13 +77,19 @@ module MCP
         end
       end
 
+      def icons(value = NOT_SET)
+        if value == NOT_SET
+          @icons_value
+        else
+          @icons_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:)
+          @input_schema_value = InputSchema.new(value)
         elsif value.is_a?(InputSchema)
           @input_schema_value = value
         end
@@ -84,14 +99,20 @@ module MCP
         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:)
+          @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
@@ -100,15 +121,33 @@ module MCP
         end
       end
 
-      def define(name: nil, title: nil, description: nil, input_schema: nil, output_schema: nil, annotations: nil, &block)
+      def define(name: nil, title: nil, description: nil, icons: [], input_schema: nil, output_schema: nil, meta: nil, annotations: nil, &block)
         Class.new(self) do
           tool_name name
           title title
           description description
+          icons icons
           input_schema input_schema
+          meta meta
           output_schema output_schema
           self.annotations(annotations) if annotations
           define_singleton_method(:call, &block) if block
+        end.tap(&:validate!)
+      end
+
+      # It complies with the following tool name specification:
+      # https://modelcontextprotocol.io/specification/latest/server/tools#tool-names
+      def validate!
+        return true unless tool_name
+
+        if tool_name.empty? || tool_name.length > MAX_LENGTH_OF_NAME
+          raise ArgumentError, "Tool names should be between 1 and 128 characters in length (inclusive)."
+        end
+
+        unless tool_name.match?(/\A[A-Za-z\d_\-\.]+\z/)
+          raise ArgumentError, <<~MESSAGE
+            Tool names only allowed characters: uppercase and lowercase ASCII letters (A-Z, a-z), digits (0-9), underscore (_), hyphen (-), and dot (.).
+          MESSAGE
         end
       end
     end

data/lib/mcp/version.rb

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

data/lib/mcp.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require_relative "json_rpc_handler"
 require_relative "mcp/configuration"
 require_relative "mcp/content"
+require_relative "mcp/icon"
 require_relative "mcp/instrumentation"
 require_relative "mcp/methods"
 require_relative "mcp/prompt"

data/mcp.gemspec

@@ -13,11 +13,15 @@ Gem::Specification.new do |spec|
   spec.homepage      = "https://github.com/modelcontextprotocol/ruby-sdk"
   spec.license       = "MIT"
 
-  spec.required_ruby_version = ">= 3.2.0"
+  # Since this library is used by a broad range of users, it does not align its support policy with Ruby's EOL.
+  spec.required_ruby_version = ">= 2.7.0"
 
   spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["changelog_uri"] = "https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v#{spec.version}"
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
+  spec.metadata["documentation_uri"] = "https://rubydoc.info/gems/mcp"
 
   spec.files = Dir.chdir(File.expand_path("..", __FILE__)) do
     %x(git ls-files -z).split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
@@ -27,6 +31,5 @@ Gem::Specification.new do |spec|
   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_dependency("json-schema", ">= 4.1")
 end