mcp 0.10.0 → 0.12.0

data/lib/mcp/server.rb

@@ -24,6 +24,12 @@ module MCP
     UNSUPPORTED_PROPERTIES_UNTIL_2025_06_18 = [:description, :icons].freeze
     UNSUPPORTED_PROPERTIES_UNTIL_2025_03_26 = [:title, :websiteUrl].freeze
 
+    DEFAULT_COMPLETION_RESULT = { completion: { values: [], hasMore: false } }.freeze
+
+    # Servers return an array of completion values ranked by relevance, with maximum 100 items per response.
+    # https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/completion#completion-results
+    MAX_COMPLETION_VALUES = 100
+
     class RequestHandlerError < StandardError
       attr_reader :error_type
       attr_reader :original_error
@@ -48,6 +54,7 @@ module MCP
     include Instrumentation
 
     attr_accessor :description, :icons, :name, :title, :version, :website_url, :instructions, :tools, :prompts, :resources, :server_context, :configuration, :capabilities, :transport, :logging_message_notification
+    attr_reader :client_capabilities
 
     def initialize(
       description: nil,
@@ -86,6 +93,7 @@ module MCP
       validate!
 
       @capabilities = capabilities || default_capabilities
+      @client_capabilities = nil
       @logging_message_notification = nil
 
       @handlers = {
@@ -100,12 +108,12 @@ module MCP
         Methods::PING => ->(_) { {} },
         Methods::NOTIFICATIONS_INITIALIZED => ->(_) {},
         Methods::NOTIFICATIONS_PROGRESS => ->(_) {},
+        Methods::COMPLETION_COMPLETE => ->(_) { DEFAULT_COMPLETION_RESULT },
         Methods::LOGGING_SET_LEVEL => method(:configure_logging_level),
 
         # No op handlers for currently unsupported methods
         Methods::RESOURCES_SUBSCRIBE => ->(_) { {} },
         Methods::RESOURCES_UNSUBSCRIBE => ->(_) { {} },
-        Methods::COMPLETION_COMPLETE => ->(_) { { completion: { values: [], hasMore: false } } },
         Methods::ELICITATION_CREATE => ->(_) {},
       }
       @transport = transport
@@ -119,8 +127,8 @@ module MCP
     #   When `nil`, progress and logging notifications from tool handlers are silently skipped.
     # @return [Hash, nil] The JSON-RPC response, or `nil` for notifications.
     def handle(request, session: nil)
-      JsonRpcHandler.handle(request) do |method|
-        handle_request(request, method, session: session)
+      JsonRpcHandler.handle(request) do |method, request_id|
+        handle_request(request, method, session: session, related_request_id: request_id)
       end
     end
 
@@ -132,8 +140,8 @@ module MCP
     #   When `nil`, progress and logging notifications from tool handlers are silently skipped.
     # @return [String, nil] The JSON-RPC response as JSON, or `nil` for notifications.
     def handle_json(request, session: nil)
-      JsonRpcHandler.handle_json(request) do |method|
-        handle_request(request, method, session: session)
+      JsonRpcHandler.handle_json(request) do |method, request_id|
+        handle_request(request, method, session: session, related_request_id: request_id)
       end
     end
 
@@ -198,6 +206,44 @@ module MCP
       report_exception(e, { notification: "log_message" })
     end
 
+    # Sends a `sampling/createMessage` request to the client.
+    # For single-client transports (e.g., `StdioTransport`). For multi-client transports
+    # (e.g., `StreamableHTTPTransport`), use `ServerSession#create_sampling_message` instead
+    # to ensure the request is routed to the correct client.
+    def create_sampling_message(
+      messages:,
+      max_tokens:,
+      system_prompt: nil,
+      model_preferences: nil,
+      include_context: nil,
+      temperature: nil,
+      stop_sequences: nil,
+      metadata: nil,
+      tools: nil,
+      tool_choice: nil,
+      related_request_id: nil
+    )
+      unless @transport
+        raise "Cannot send sampling request without a transport."
+      end
+
+      params = build_sampling_params(
+        @client_capabilities,
+        messages: messages,
+        max_tokens: max_tokens,
+        system_prompt: system_prompt,
+        model_preferences: model_preferences,
+        include_context: include_context,
+        temperature: temperature,
+        stop_sequences: stop_sequences,
+        metadata: metadata,
+        tools: tools,
+        tool_choice: tool_choice,
+      )
+
+      @transport.send_request(Methods::SAMPLING_CREATE_MESSAGE, params)
+    end
+
     # Sets a custom handler for `resources/read` requests.
     # The block receives the parsed request params and should return resource
     # contents. The return value is set as the `contents` field of the response.
@@ -208,6 +254,54 @@ module MCP
       @handlers[Methods::RESOURCES_READ] = block
     end
 
+    # Sets a custom handler for `completion/complete` requests.
+    # The block receives the parsed request params and should return completion values.
+    #
+    # @yield [params] The request params containing `:ref`, `:argument`, and optionally `:context`.
+    # @yieldreturn [Hash] A hash with `:completion` key containing `:values`, optional `:total`, and `:hasMore`.
+    def completion_handler(&block)
+      @handlers[Methods::COMPLETION_COMPLETE] = block
+    end
+
+    def build_sampling_params(
+      capabilities,
+      messages:,
+      max_tokens:,
+      system_prompt: nil,
+      model_preferences: nil,
+      include_context: nil,
+      temperature: nil,
+      stop_sequences: nil,
+      metadata: nil,
+      tools: nil,
+      tool_choice: nil
+    )
+      unless capabilities&.dig(:sampling)
+        raise "Client does not support sampling."
+      end
+
+      if tools && !capabilities.dig(:sampling, :tools)
+        raise "Client does not support sampling with tools."
+      end
+
+      if tool_choice && !capabilities.dig(:sampling, :tools)
+        raise "Client does not support sampling with tool_choice."
+      end
+
+      {
+        messages: messages,
+        maxTokens: max_tokens,
+        systemPrompt: system_prompt,
+        modelPreferences: model_preferences,
+        includeContext: include_context,
+        temperature: temperature,
+        stopSequences: stop_sequences,
+        metadata: metadata,
+        tools: tools,
+        toolChoice: tool_choice,
+      }.compact
+    end
+
     private
 
     def validate!
@@ -278,7 +372,7 @@ module MCP
       end
     end
 
-    def handle_request(request, method, session: nil)
+    def handle_request(request, method, session: nil, related_request_id: nil)
       handler = @handlers[method]
       unless handler
         instrument_call("unsupported_method") do
@@ -306,7 +400,9 @@ module MCP
           when Methods::RESOURCES_TEMPLATES_LIST
             { resourceTemplates: @handlers[Methods::RESOURCES_TEMPLATES_LIST].call(params) }
           when Methods::TOOLS_CALL
-            call_tool(params, session: session)
+            call_tool(params, session: session, related_request_id: related_request_id)
+          when Methods::COMPLETION_COMPLETE
+            complete(params)
           when Methods::LOGGING_SET_LEVEL
             configure_logging_level(params, session: session)
           else
@@ -316,13 +412,12 @@ module MCP
           add_instrumentation_data(client: client) if client
 
           result
+        rescue RequestHandlerError => e
+          report_exception(e.original_error || e, { request: request })
+          add_instrumentation_data(error: e.error_type)
+          raise e
         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
@@ -355,10 +450,11 @@ module MCP
           session.store_client_info(client: params[:clientInfo], capabilities: params[:capabilities])
         else
           @client = params[:clientInfo]
+          @client_capabilities = params[:capabilities]
         end
+        protocol_version = params[:protocolVersion]
       end
 
-      protocol_version = params[:protocolVersion] if params
       negotiated_version = if Configuration::SUPPORTED_STABLE_PROTOCOL_VERSIONS.include?(protocol_version)
         protocol_version
       else
@@ -404,7 +500,7 @@ module MCP
       @tools.values.map(&:to_h)
     end
 
-    def call_tool(request, session: nil)
+    def call_tool(request, session: nil, related_request_id: nil)
       tool_name = request[:name]
 
       tool = tools[tool_name]
@@ -421,7 +517,7 @@ module MCP
         add_instrumentation_data(error: :missing_required_arguments)
 
         missing = tool.input_schema.missing_required_arguments(arguments).join(", ")
-        return error_tool_response("Missing required arguments: #{missing}")
+        raise RequestHandlerError.new("Missing required arguments: #{missing}", request, error_type: :invalid_params)
       end
 
       if configuration.validate_tool_call_arguments && tool.input_schema
@@ -430,19 +526,22 @@ module MCP
         rescue Tool::InputSchema::ValidationError => e
           add_instrumentation_data(error: :invalid_schema)
 
-          return error_tool_response(e.message)
+          raise RequestHandlerError.new(e.message, request, error_type: :invalid_params)
         end
       end
 
       progress_token = request.dig(:_meta, :progressToken)
 
-      call_tool_with_args(tool, arguments, server_context_with_meta(request), progress_token: progress_token, session: session)
+      call_tool_with_args(tool, arguments, server_context_with_meta(request), progress_token: progress_token, session: session, related_request_id: related_request_id)
     rescue RequestHandlerError
       raise
     rescue => e
-      report_exception(e, request: request)
-
-      error_tool_response("Internal error calling tool #{tool_name}: #{e.message}")
+      raise RequestHandlerError.new(
+        "Internal error calling tool #{tool_name}: #{e.message}",
+        request,
+        error_type: :internal_error,
+        original_error: e,
+      )
     end
 
     def list_prompts(request)
@@ -479,6 +578,14 @@ module MCP
       @resource_templates.map(&:to_h)
     end
 
+    def complete(params)
+      validate_completion_params!(params)
+
+      result = @handlers[Methods::COMPLETION_COMPLETE].call(params)
+
+      normalize_completion_result(result)
+    end
+
     def report_exception(exception, server_context = {})
       configuration.exception_reporter.call(exception, server_context)
     end
@@ -505,12 +612,12 @@ module MCP
       parameters.any? { |type, name| type == :keyrest || name == :server_context }
     end
 
-    def call_tool_with_args(tool, arguments, context, progress_token: nil, session: nil)
+    def call_tool_with_args(tool, arguments, context, progress_token: nil, session: nil, related_request_id: nil)
       args = arguments&.transform_keys(&:to_sym) || {}
 
       if accepts_server_context?(tool.method(:call))
-        progress = Progress.new(notification_target: session, progress_token: progress_token)
-        server_context = ServerContext.new(context, progress: progress, notification_target: session)
+        progress = Progress.new(notification_target: session, progress_token: progress_token, related_request_id: related_request_id)
+        server_context = ServerContext.new(context, progress: progress, notification_target: session, related_request_id: related_request_id)
         tool.call(**args, server_context: server_context).to_h
       else
         tool.call(**args).to_h
@@ -537,5 +644,56 @@ module MCP
         server_context
       end
     end
+
+    def validate_completion_params!(params)
+      unless params.is_a?(Hash)
+        raise RequestHandlerError.new("Invalid params", params, error_type: :invalid_params)
+      end
+
+      ref = params[:ref]
+      if ref.nil? || ref[:type].nil?
+        raise RequestHandlerError.new("Missing or invalid ref", params, error_type: :invalid_params)
+      end
+
+      argument = params[:argument]
+      if argument.nil? || argument[:name].nil? || !argument.key?(:value)
+        raise RequestHandlerError.new("Missing argument name or value", params, error_type: :invalid_params)
+      end
+
+      case ref[:type]
+      when "ref/prompt"
+        unless @prompts[ref[:name]]
+          raise RequestHandlerError.new("Prompt not found: #{ref[:name]}", params, error_type: :invalid_params)
+        end
+      when "ref/resource"
+        uri = ref[:uri]
+        found = @resource_index.key?(uri) || @resource_templates.any? { |t| t.uri_template == uri }
+        unless found
+          raise RequestHandlerError.new("Resource not found: #{uri}", params, error_type: :invalid_params)
+        end
+      else
+        raise RequestHandlerError.new("Invalid ref type: #{ref[:type]}", params, error_type: :invalid_params)
+      end
+    end
+
+    def normalize_completion_result(result)
+      return DEFAULT_COMPLETION_RESULT unless result.is_a?(Hash)
+
+      completion = result[:completion] || result["completion"]
+      return DEFAULT_COMPLETION_RESULT unless completion.is_a?(Hash)
+
+      values = completion[:values] || completion["values"] || []
+      total = completion[:total] || completion["total"]
+      has_more = completion[:hasMore] || completion["hasMore"] || false
+
+      count = values.length
+      if count > MAX_COMPLETION_VALUES
+        has_more = true
+        total ||= count
+        values = values.first(MAX_COMPLETION_VALUES)
+      end
+
+      { completion: { values: values, total: total, hasMore: has_more }.compact }
+    end
   end
 end

data/lib/mcp/server_context.rb

@@ -2,10 +2,11 @@
 
 module MCP
   class ServerContext
-    def initialize(context, progress:, notification_target:)
+    def initialize(context, progress:, notification_target:, related_request_id: nil)
       @context = context
       @progress = progress
       @notification_target = notification_target
+      @related_request_id = related_request_id
     end
 
     # Reports progress for the current tool operation.
@@ -26,7 +27,20 @@ module MCP
     def notify_log_message(data:, level:, logger: nil)
       return unless @notification_target
 
-      @notification_target.notify_log_message(data: data, level: level, logger: logger)
+      @notification_target.notify_log_message(data: data, level: level, logger: logger, related_request_id: @related_request_id)
+    end
+
+    # Delegates to the session so the request is scoped to the originating client.
+    # Falls back to `@context` (via `method_missing`) when `@notification_target`
+    # does not support sampling.
+    def create_sampling_message(**kwargs)
+      if @notification_target.respond_to?(:create_sampling_message)
+        @notification_target.create_sampling_message(**kwargs, related_request_id: @related_request_id)
+      elsif @context.respond_to?(:create_sampling_message)
+        @context.create_sampling_message(**kwargs, related_request_id: @related_request_id)
+      else
+        raise NoMethodError, "undefined method 'create_sampling_message' for #{self}"
+      end
     end
 
     def method_missing(name, ...)

data/lib/mcp/server_session.rb

@@ -13,7 +13,7 @@ module MCP
       @transport = transport
       @session_id = session_id
       @client = nil
-      @client_capabilities = nil # TODO: Use for per-session capability validation.
+      @client_capabilities = nil
       @logging_message_notification = nil
     end
 
@@ -36,8 +36,19 @@ module MCP
       @logging_message_notification = logging_message_notification
     end
 
+    # Returns per-session client capabilities, falling back to global.
+    def client_capabilities
+      @client_capabilities || @server.client_capabilities
+    end
+
+    # Sends a `sampling/createMessage` request scoped to this session.
+    def create_sampling_message(related_request_id: nil, **kwargs)
+      params = @server.build_sampling_params(client_capabilities, **kwargs)
+      send_to_transport_request(Methods::SAMPLING_CREATE_MESSAGE, params, related_request_id: related_request_id)
+    end
+
     # Sends a progress notification to this session only.
-    def notify_progress(progress_token:, progress:, total: nil, message: nil)
+    def notify_progress(progress_token:, progress:, total: nil, message: nil, related_request_id: nil)
       params = {
         "progressToken" => progress_token,
         "progress" => progress,
@@ -45,35 +56,52 @@ module MCP
         "message" => message,
       }.compact
 
-      send_to_transport(Methods::NOTIFICATIONS_PROGRESS, params)
+      send_to_transport(Methods::NOTIFICATIONS_PROGRESS, params, related_request_id: related_request_id)
     rescue => e
       @server.report_exception(e, notification: "progress")
     end
 
     # Sends a log message notification to this session only.
-    def notify_log_message(data:, level:, logger: nil)
+    def notify_log_message(data:, level:, logger: nil, related_request_id: nil)
       effective_logging = @logging_message_notification || @server.logging_message_notification
       return unless effective_logging&.should_notify?(level)
 
       params = { "data" => data, "level" => level }
       params["logger"] = logger if logger
 
-      send_to_transport(Methods::NOTIFICATIONS_MESSAGE, params)
+      send_to_transport(Methods::NOTIFICATIONS_MESSAGE, params, related_request_id: related_request_id)
     rescue => e
       @server.report_exception(e, { notification: "log_message" })
     end
 
     private
 
+    # Branches on `@session_id` because `StdioTransport` creates a `ServerSession` without
+    # a `session_id` (`session_id: nil`), while `StreamableHTTPTransport` always provides one.
+    #
     # TODO: When Ruby 2.7 support is dropped, replace with a direct call:
     # `@transport.send_notification(method, params, session_id: @session_id)` and
     # add `**` to `Transport#send_notification` and `StdioTransport#send_notification`.
-    def send_to_transport(method, params)
+    def send_to_transport(method, params, related_request_id: nil)
       if @session_id
-        @transport.send_notification(method, params, session_id: @session_id)
+        @transport.send_notification(method, params, session_id: @session_id, related_request_id: related_request_id)
       else
         @transport.send_notification(method, params)
       end
     end
+
+    # Branches on `@session_id` because `StdioTransport` creates a `ServerSession` without
+    # a `session_id` (`session_id: nil`), while `StreamableHTTPTransport` always provides one.
+    #
+    # TODO: When Ruby 2.7 support is dropped, replace with a direct call:
+    # `@transport.send_request(method, params, session_id: @session_id)` and
+    # add `**` to `Transport#send_request` and `StdioTransport#send_request`.
+    def send_to_transport_request(method, params, related_request_id: nil)
+      if @session_id
+        @transport.send_request(method, params, session_id: @session_id, related_request_id: related_request_id)
+      else
+        @transport.send_request(method, params)
+      end
+    end
   end
 end

data/lib/mcp/tool/schema.rb

@@ -8,7 +8,7 @@ module MCP
       attr_reader :schema
 
       def initialize(schema = {})
-        @schema = deep_transform_keys(JSON.parse(JSON.dump(schema)), &:to_sym)
+        @schema = JSON.parse(JSON.dump(schema), symbolize_names: true)
         @schema[:type] ||= "object"
         validate_schema!
       end
@@ -27,19 +27,6 @@ module MCP
         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|
-            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)

data/lib/mcp/transport.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
+require "securerandom"
+
 module MCP
   class Transport
     # Initialize the transport with the server instance
     def initialize(server)
       @server = server
+      server.transport = self
     end
 
     # Send a response to the client
@@ -41,5 +44,16 @@ module MCP
     def send_notification(method, params = nil)
       raise NotImplementedError, "Subclasses must implement send_notification"
     end
+
+    # Send a JSON-RPC request to the client and wait for a response.
+    def send_request(method, params = nil)
+      raise NotImplementedError, "Subclasses must implement send_request"
+    end
+
+    private
+
+    def generate_request_id
+      SecureRandom.uuid
+    end
   end
 end

data/lib/mcp/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Model Context Protocol
@@ -28,7 +28,9 @@ email:
 - mcp-support@anthropic.com
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- LICENSE
+- README.md
 files:
 - LICENSE
 - README.md
@@ -76,7 +78,7 @@ licenses:
 - Apache-2.0
 metadata:
   allowed_push_host: https://rubygems.org
-  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v0.10.0
+  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v0.12.0
   homepage_uri: https://github.com/modelcontextprotocol/ruby-sdk
   source_code_uri: https://github.com/modelcontextprotocol/ruby-sdk
   bug_tracker_uri: https://github.com/modelcontextprotocol/ruby-sdk/issues