mcp 0.9.2 → 0.11.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,26 +108,40 @@ 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
     end
 
-    def handle(request)
-      JsonRpcHandler.handle(request) do |method|
-        handle_request(request, method)
+    # Processes a parsed JSON-RPC request and returns the response as a Hash.
+    #
+    # @param request [Hash] A parsed JSON-RPC request.
+    # @param session [ServerSession, nil] Per-connection session. Passed by
+    #   `ServerSession#handle` for session-scoped notification delivery.
+    #   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, request_id|
+        handle_request(request, method, session: session, related_request_id: request_id)
       end
     end
 
-    def handle_json(request)
-      JsonRpcHandler.handle_json(request) do |method|
-        handle_request(request, method)
+    # Processes a JSON-RPC request string and returns the response as a JSON string.
+    #
+    # @param request [String] A JSON-RPC request as a JSON string.
+    # @param session [ServerSession, nil] Per-connection session. Passed by
+    #   `ServerSession#handle_json` for session-scoped notification delivery.
+    #   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, request_id|
+        handle_request(request, method, session: session, related_request_id: request_id)
       end
     end
 
@@ -172,21 +194,6 @@ module MCP
       report_exception(e, { notification: "resources_list_changed" })
     end
 
-    def notify_progress(progress_token:, progress:, total: nil, message: nil)
-      return unless @transport
-
-      params = {
-        "progressToken" => progress_token,
-        "progress" => progress,
-        "total" => total,
-        "message" => message,
-      }.compact
-
-      @transport.send_notification(Methods::NOTIFICATIONS_PROGRESS, params)
-    rescue => e
-      report_exception(e, notification: "progress")
-    end
-
     def notify_log_message(data:, level:, logger: nil)
       return unless @transport
       return unless logging_message_notification&.should_notify?(level)
@@ -199,32 +206,100 @@ module MCP
       report_exception(e, { notification: "log_message" })
     end
 
-    def resources_list_handler(&block)
-      @handlers[Methods::RESOURCES_LIST] = block
-    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.
+    #
+    # @yield [params] The request params containing `:uri`.
+    # @yieldreturn [Array<Hash>, Hash] Resource contents.
     def resources_read_handler(&block)
       @handlers[Methods::RESOURCES_READ] = block
     end
 
-    def resources_templates_list_handler(&block)
-      @handlers[Methods::RESOURCES_TEMPLATES_LIST] = block
-    end
-
-    def tools_list_handler(&block)
-      @handlers[Methods::TOOLS_LIST] = 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
 
-    def tools_call_handler(&block)
-      @handlers[Methods::TOOLS_CALL] = block
-    end
+      if tools && !capabilities.dig(:sampling, :tools)
+        raise "Client does not support sampling with tools."
+      end
 
-    def prompts_list_handler(&block)
-      @handlers[Methods::PROMPTS_LIST] = block
-    end
+      if tool_choice && !capabilities.dig(:sampling, :tools)
+        raise "Client does not support sampling with tool_choice."
+      end
 
-    def prompts_get_handler(&block)
-      @handlers[Methods::PROMPTS_GET] = block
+      {
+        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
@@ -297,11 +372,12 @@ module MCP
       end
     end
 
-    def handle_request(request, method)
+    def handle_request(request, method, session: nil, related_request_id: nil)
       handler = @handlers[method]
       unless handler
         instrument_call("unsupported_method") do
-          add_instrumentation_data(client: @client) if @client
+          client = session&.client || @client
+          add_instrumentation_data(client: client) if client
         end
         return
       end
@@ -311,6 +387,8 @@ module MCP
       ->(params) {
         instrument_call(method) do
           result = case method
+          when Methods::INITIALIZE
+            init(params, session: session)
           when Methods::TOOLS_LIST
             { tools: @handlers[Methods::TOOLS_LIST].call(params) }
           when Methods::PROMPTS_LIST
@@ -321,19 +399,25 @@ module MCP
             { contents: @handlers[Methods::RESOURCES_READ].call(params) }
           when Methods::RESOURCES_TEMPLATES_LIST
             { resourceTemplates: @handlers[Methods::RESOURCES_TEMPLATES_LIST].call(params) }
+          when Methods::TOOLS_CALL
+            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
             @handlers[method].call(params)
           end
-          add_instrumentation_data(client: @client) if @client
+          client = session&.client || @client
+          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
@@ -360,10 +444,17 @@ module MCP
       }.compact
     end
 
-    def init(params)
-      @client = params[:clientInfo] if params
+    def init(params, session: nil)
+      if params
+        if session
+          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
@@ -389,7 +480,7 @@ module MCP
       }.compact
     end
 
-    def configure_logging_level(request)
+    def configure_logging_level(request, session: nil)
       if capabilities[:logging].nil?
         raise RequestHandlerError.new("Server does not support logging", request, error_type: :internal_error)
       end
@@ -399,6 +490,7 @@ module MCP
         raise RequestHandlerError.new("Invalid log level #{request[:level]}", request, error_type: :invalid_params)
       end
 
+      session&.configure_logging(logging_message_notification)
       @logging_message_notification = logging_message_notification
 
       {}
@@ -408,7 +500,7 @@ module MCP
       @tools.values.map(&:to_h)
     end
 
-    def call_tool(request)
+    def call_tool(request, session: nil, related_request_id: nil)
       tool_name = request[:name]
 
       tool = tools[tool_name]
@@ -425,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
@@ -434,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)
+      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)
@@ -483,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
@@ -509,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)
+    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(server: self, progress_token: progress_token)
-        server_context = ServerContext.new(context, progress: progress)
+        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
@@ -541,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,15 +2,47 @@
 
 module MCP
   class ServerContext
-    def initialize(context, progress:)
+    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.
+    # The notification is automatically scoped to the originating session.
+    #
+    # @param progress [Numeric] Current progress value.
+    # @param total [Numeric, nil] Total expected value.
+    # @param message [String, nil] Human-readable status message.
     def report_progress(progress, total: nil, message: nil)
       @progress.report(progress, total: total, message: message)
     end
 
+    # Sends a log message notification scoped to the originating session.
+    #
+    # @param data [Object] The log data to send.
+    # @param level [String] Log level (e.g., `"debug"`, `"info"`, `"error"`).
+    # @param logger [String, nil] Logger name.
+    def notify_log_message(data:, level:, logger: nil)
+      return unless @notification_target
+
+      @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, ...)
       if @context.respond_to?(name)
         @context.public_send(name, ...)

data/lib/mcp/server_session.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "methods"
+
+module MCP
+  # Holds per-connection state for a single client session.
+  # Created by the transport layer; delegates request handling to the shared `Server`.
+  class ServerSession
+    attr_reader :session_id, :client, :logging_message_notification
+
+    def initialize(server:, transport:, session_id: nil)
+      @server = server
+      @transport = transport
+      @session_id = session_id
+      @client = nil
+      @client_capabilities = nil
+      @logging_message_notification = nil
+    end
+
+    def handle(request)
+      @server.handle(request, session: self)
+    end
+
+    def handle_json(request_json)
+      @server.handle_json(request_json, session: self)
+    end
+
+    # Called by `Server#init` during the initialization handshake.
+    def store_client_info(client:, capabilities: nil)
+      @client = client
+      @client_capabilities = capabilities
+    end
+
+    # Called by `Server#configure_logging_level`.
+    def configure_logging(logging_message_notification)
+      @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, related_request_id: nil)
+      params = {
+        "progressToken" => progress_token,
+        "progress" => progress,
+        "total" => total,
+        "message" => message,
+      }.compact
+
+      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, 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, 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, related_request_id: nil)
+      if @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,5 +1,7 @@
 # frozen_string_literal: true
 
+require "securerandom"
+
 module MCP
   class Transport
     # Initialize the transport with the server instance
@@ -36,10 +38,21 @@ module MCP
       send_response(response) if response
     end
 
-    # Send a notification to the client
-    # Returns true if the notification was sent successfully
+    # 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
+
+    # 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.9.2"
+  VERSION = "0.11.0"
 end

data/lib/mcp.rb

@@ -15,6 +15,7 @@ module MCP
   autoload :Resource, "mcp/resource"
   autoload :ResourceTemplate, "mcp/resource_template"
   autoload :Server, "mcp/server"
+  autoload :ServerSession, "mcp/server_session"
   autoload :Tool, "mcp/tool"
 
   class << self