mcp 0.10.0 → 0.15.0

data/lib/mcp/server.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 require_relative "../json_rpc_handler"
+require_relative "cancellation"
+require_relative "cancelled_error"
 require_relative "instrumentation"
 require_relative "methods"
 require_relative "logging_message_notification"
 require_relative "progress"
 require_relative "server_context"
+require_relative "server/pagination"
 require_relative "server/transports"
 
 module MCP
@@ -24,15 +27,34 @@ 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
+      attr_reader :error_type, :original_error, :error_code, :error_data
 
-      def initialize(message, request, error_type: :internal_error, original_error: nil)
+      def initialize(message, request, error_type: :internal_error, original_error: nil, error_code: nil, error_data: nil)
         super(message)
         @request = request
         @error_type = error_type
         @original_error = original_error
+        @error_code = error_code
+        @error_data = error_data
+      end
+    end
+
+    class URLElicitationRequiredError < RequestHandlerError
+      def initialize(elicitations)
+        super(
+          "URL elicitation required",
+          nil,
+          error_type: :url_elicitation_required,
+          error_code: -32042,
+          error_data: { elicitations: elicitations },
+        )
       end
     end
 
@@ -46,8 +68,10 @@ module MCP
     end
 
     include Instrumentation
+    include Pagination
 
     attr_accessor :description, :icons, :name, :title, :version, :website_url, :instructions, :tools, :prompts, :resources, :server_context, :configuration, :capabilities, :transport, :logging_message_notification
+    attr_reader :page_size, :client_capabilities
 
     def initialize(
       description: nil,
@@ -64,6 +88,7 @@ module MCP
       server_context: nil,
       configuration: nil,
       capabilities: nil,
+      page_size: nil,
       transport: nil
     )
       @description = description
@@ -80,18 +105,22 @@ module MCP
       @resource_templates = resource_templates
       @resource_index = index_resources_by_uri(resources)
       @server_context = server_context
+      self.page_size = page_size
       @configuration = MCP.configuration.merge(configuration)
       @client = nil
 
       validate!
 
       @capabilities = capabilities || default_capabilities
+      @client_capabilities = nil
       @logging_message_notification = nil
 
       @handlers = {
         Methods::RESOURCES_LIST => method(:list_resources),
         Methods::RESOURCES_READ => method(:read_resource_no_content),
         Methods::RESOURCES_TEMPLATES_LIST => method(:list_resource_templates),
+        Methods::RESOURCES_SUBSCRIBE => ->(_) { {} },
+        Methods::RESOURCES_UNSUBSCRIBE => ->(_) { {} },
         Methods::TOOLS_LIST => method(:list_tools),
         Methods::TOOLS_CALL => method(:call_tool),
         Methods::PROMPTS_LIST => method(:list_prompts),
@@ -100,13 +129,9 @@ module MCP
         Methods::PING => ->(_) { {} },
         Methods::NOTIFICATIONS_INITIALIZED => ->(_) {},
         Methods::NOTIFICATIONS_PROGRESS => ->(_) {},
+        Methods::NOTIFICATIONS_ROOTS_LIST_CHANGED => ->(_) {},
+        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
@@ -119,8 +144,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 +157,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
 
@@ -162,6 +187,14 @@ module MCP
       @handlers[method_name] = block
     end
 
+    def page_size=(page_size)
+      unless page_size.nil? || (page_size.is_a?(Integer) && page_size > 0)
+        raise ArgumentError, "page_size must be nil or a positive integer"
+      end
+
+      @page_size = page_size
+    end
+
     def notify_tools_list_changed
       return unless @transport
 
@@ -198,6 +231,14 @@ module MCP
       report_exception(e, { notification: "log_message" })
     end
 
+    # Sets a handler for `notifications/roots/list_changed` notifications.
+    # Called when a client notifies the server that its filesystem roots have changed.
+    #
+    # @yield [params] The notification params (typically `nil`).
+    def roots_list_changed_handler(&block)
+      @handlers[Methods::NOTIFICATIONS_ROOTS_LIST_CHANGED] = block
+    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 +249,72 @@ 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
+
+    # Sets a custom handler for `resources/subscribe` requests.
+    # The block receives the parsed request params. The return value is
+    # ignored; the response is always an empty result `{}` per the MCP specification.
+    #
+    # @yield [params] The request params containing `:uri`.
+    def resources_subscribe_handler(&block)
+      @handlers[Methods::RESOURCES_SUBSCRIBE] = block
+    end
+
+    # Sets a custom handler for `resources/unsubscribe` requests.
+    # The block receives the parsed request params. The return value is
+    # ignored; the response is always an empty result `{}` per the MCP specification.
+    #
+    # @yield [params] The request params containing `:uri`.
+    def resources_unsubscribe_handler(&block)
+      @handlers[Methods::RESOURCES_UNSUBSCRIBE] = 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,10 +385,17 @@ module MCP
       end
     end
 
-    def handle_request(request, method, session: nil)
+    def handle_request(request, method, session: nil, related_request_id: nil)
+      # `notifications/cancelled` is dispatched directly: it is a notification (no JSON-RPC id)
+      # and intentionally bypasses the `@handlers` lookup, capability check, in-flight registry,
+      # and rescue blocks below.
+      if method == Methods::NOTIFICATIONS_CANCELLED
+        return ->(params) { handle_cancelled_notification(params, session: session) }
+      end
+
       handler = @handlers[method]
       unless handler
-        instrument_call("unsupported_method") do
+        instrument_call("unsupported_method", server_context: { request: request }) do
           client = session&.client || @client
           add_instrumentation_data(client: client) if client
         end
@@ -290,45 +404,78 @@ module MCP
 
       Methods.ensure_capability!(method, capabilities)
 
+      # `initialize` MUST NOT be cancelled (MCP spec 2025-11-25, cancellation item 2),
+      # so do not track it in the in-flight registry.
+      cancellation = if related_request_id && method != Methods::INITIALIZE
+        session&.register_in_flight(related_request_id)
+      end
+
       ->(params) {
-        instrument_call(method) do
+        reported_exception = nil
+        instrument_call(
+          method,
+          server_context: { request: request },
+          exception_already_reported: ->(e) { reported_exception.equal?(e) },
+        ) 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
-            { prompts: @handlers[Methods::PROMPTS_LIST].call(params) }
-          when Methods::RESOURCES_LIST
-            { resources: @handlers[Methods::RESOURCES_LIST].call(params) }
           when Methods::RESOURCES_READ
-            { contents: @handlers[Methods::RESOURCES_READ].call(params) }
-          when Methods::RESOURCES_TEMPLATES_LIST
-            { resourceTemplates: @handlers[Methods::RESOURCES_TEMPLATES_LIST].call(params) }
+            { contents: read_resource_contents(params, session: session, related_request_id: related_request_id, cancellation: cancellation) }
+          when Methods::RESOURCES_SUBSCRIBE, Methods::RESOURCES_UNSUBSCRIBE
+            dispatch_optional_context_handler(@handlers[method], params, session: session, related_request_id: related_request_id, cancellation: cancellation)
+            {}
           when Methods::TOOLS_CALL
-            call_tool(params, session: session)
+            call_tool(params, session: session, related_request_id: related_request_id, cancellation: cancellation)
+          when Methods::PROMPTS_GET
+            get_prompt(params, session: session, related_request_id: related_request_id, cancellation: cancellation)
+          when Methods::COMPLETION_COMPLETE
+            complete(params, session: session, related_request_id: related_request_id, cancellation: cancellation)
           when Methods::LOGGING_SET_LEVEL
             configure_logging_level(params, session: session)
           else
-            @handlers[method].call(params)
+            dispatch_optional_context_handler(@handlers[method], params, session: session, related_request_id: related_request_id, cancellation: cancellation)
           end
           client = session&.client || @client
           add_instrumentation_data(client: client) if client
 
+          if cancellation&.cancelled?
+            add_instrumentation_data(cancelled: true, cancellation_reason: cancellation.reason)
+            next JsonRpcHandler::NO_RESPONSE
+          end
+
           result
+        rescue CancelledError => e
+          add_instrumentation_data(cancelled: true, cancellation_reason: e.reason)
+          next JsonRpcHandler::NO_RESPONSE
+        rescue RequestHandlerError => e
+          report_exception(e.original_error || e, { request: request })
+          add_instrumentation_data(error: e.error_type)
+          reported_exception = e
+          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)
+          wrapped = RequestHandlerError.new("Internal error handling #{method} request", request, original_error: e)
+          reported_exception = wrapped
+          raise wrapped
+        ensure
+          session&.unregister_in_flight(related_request_id) if related_request_id
         end
       }
     end
 
+    def handle_cancelled_notification(params, session: nil)
+      return unless session
+      return unless params.is_a?(Hash)
+
+      request_id = params[:requestId] || params["requestId"]
+      return if request_id.nil?
+
+      reason = params[:reason] || params["reason"]
+      session.cancel_incoming(request_id: request_id, reason: reason)
+    end
+
     def default_capabilities
       {
         tools: { listChanged: true },
@@ -355,10 +502,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
@@ -401,10 +549,12 @@ module MCP
     end
 
     def list_tools(request)
-      @tools.values.map(&:to_h)
+      page = paginate(@tools.values, cursor: cursor_from(request), page_size: @page_size, request: request, &:to_h)
+
+      { tools: page[:items], nextCursor: page[:next_cursor] }.compact
     end
 
-    def call_tool(request, session: nil)
+    def call_tool(request, session: nil, related_request_id: nil, cancellation: nil)
       tool_name = request[:name]
 
       tool = tools[tool_name]
@@ -436,20 +586,29 @@ module MCP
 
       progress_token = request.dig(:_meta, :progressToken)
 
-      call_tool_with_args(tool, arguments, server_context_with_meta(request), progress_token: progress_token, session: session)
-    rescue RequestHandlerError
+      call_tool_with_args(
+        tool, arguments, server_context_with_meta(request), progress_token: progress_token, session: session, related_request_id: related_request_id, cancellation: cancellation
+      )
+    rescue RequestHandlerError, CancelledError
+      # CancelledError is intentionally not wrapped so `handle_request` can turn it into
+      # `JsonRpcHandler::NO_RESPONSE` per the MCP cancellation spec.
       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)
-      @prompts.values.map(&:to_h)
+      page = paginate(@prompts.values, cursor: cursor_from(request), page_size: @page_size, request: request, &:to_h)
+
+      { prompts: page[:items], nextCursor: page[:next_cursor] }.compact
     end
 
-    def get_prompt(request)
+    def get_prompt(request, session: nil, related_request_id: nil, cancellation: nil)
       prompt_name = request[:name]
       prompt = @prompts[prompt_name]
       unless prompt
@@ -462,11 +621,20 @@ module MCP
       prompt_args = request[:arguments]
       prompt.validate_arguments!(prompt_args)
 
-      call_prompt_template_with_args(prompt, prompt_args, server_context_with_meta(request))
+      server_context = build_server_context(
+        request: request,
+        session: session,
+        related_request_id: related_request_id,
+        cancellation: cancellation,
+      )
+
+      call_prompt_template_with_args(prompt, prompt_args, server_context)
     end
 
     def list_resources(request)
-      @resources.map(&:to_h)
+      page = paginate(@resources, cursor: cursor_from(request), page_size: @page_size, request: request, &:to_h)
+
+      { resources: page[:items], nextCursor: page[:next_cursor] }.compact
     end
 
     # Server implementation should set `resources_read_handler` to override no-op default
@@ -476,7 +644,85 @@ module MCP
     end
 
     def list_resource_templates(request)
-      @resource_templates.map(&:to_h)
+      page = paginate(@resource_templates, cursor: cursor_from(request), page_size: @page_size, request: request, &:to_h)
+
+      { resourceTemplates: page[:items], nextCursor: page[:next_cursor] }.compact
+    end
+
+    def complete(params, session: nil, related_request_id: nil, cancellation: nil)
+      validate_completion_params!(params)
+
+      result = dispatch_optional_context_handler(
+        @handlers[Methods::COMPLETION_COMPLETE],
+        params,
+        session: session,
+        related_request_id: related_request_id,
+        cancellation: cancellation,
+      )
+
+      normalize_completion_result(result)
+    end
+
+    # Invokes `resources/read` via the registered handler. If the handler block opts in to `server_context:`,
+    # pass an `MCP::ServerContext` so the handler can observe cancellation via `server_context.cancelled?` or
+    # `server_context.raise_if_cancelled!`.
+    def read_resource_contents(request, session: nil, related_request_id: nil, cancellation: nil)
+      dispatch_optional_context_handler(
+        @handlers[Methods::RESOURCES_READ],
+        request,
+        session: session,
+        related_request_id: related_request_id,
+        cancellation: cancellation,
+      )
+    end
+
+    # Opt-in `server_context:` dispatch for block-based handlers registered via `resources_read_handler`,
+    # `completion_handler`, `resources_subscribe_handler`, `resources_unsubscribe_handler`, or `define_custom_method`.
+    # Existing handlers that only accept `params` are called unchanged; handlers that declare a `server_context:`
+    # keyword receive an `MCP::ServerContext` wrapping the raw server context with cancellation plumbing.
+    def dispatch_optional_context_handler(handler, params, session: nil, related_request_id: nil, cancellation: nil)
+      return handler.call(params) unless handler_declares_server_context?(handler)
+
+      server_context = build_server_context(
+        request: params,
+        session: session,
+        related_request_id: related_request_id,
+        cancellation: cancellation,
+      )
+      handler.call(params, server_context: server_context)
+    end
+
+    # Stricter than `accepts_server_context?`: requires `server_context` to appear as a named keyword parameter
+    # (`:key` optional, `:keyreq` required). Positional parameters named `server_context` (`:req` / `:opt`) are NOT
+    # treated as opt-in - otherwise `handler.call(params, server_context: ctx)` would pass the `{server_context: ctx}`
+    # Hash as the handler's second positional argument, which is never what the user meant.
+    #
+    # `**kwargs`-only signatures (`:keyrest` without a named `server_context`) are also not opt-in here,
+    # because the dispatch site passes a positional `params`, and a `**kwargs`-only block cannot accept
+    # that positional argument (lambdas/methods raise `ArgumentError`; non-lambda procs silently drop `params`).
+    # Tool handlers intentionally allow `**kwargs` opt-in via `accepts_server_context?` because they are invoked
+    # via `tool.call(**args, server_context: …)` without a positional argument.
+    def handler_declares_server_context?(handler)
+      return false unless handler.respond_to?(:parameters)
+
+      handler.parameters.any? do |type, name|
+        name == :server_context && (type == :key || type == :keyreq)
+      end
+    end
+
+    # Builds an `MCP::ServerContext` used to give a handler access to session-scoped helpers
+    # (progress, cancellation, nested server-to-client requests).
+    def build_server_context(request:, session:, related_request_id:, cancellation:)
+      meta_source = request.is_a?(Hash) ? request : {}
+      progress_token = meta_source.dig(:_meta, :progressToken)
+      progress = Progress.new(notification_target: session, progress_token: progress_token, related_request_id: related_request_id)
+      ServerContext.new(
+        server_context_with_meta(meta_source),
+        progress: progress,
+        notification_target: session,
+        related_request_id: related_request_id,
+        cancellation: cancellation,
+      )
     end
 
     def report_exception(exception, server_context = {})
@@ -499,18 +745,32 @@ module MCP
       ).to_h
     end
 
+    # Whether a tool/prompt handler opts in to receiving an `MCP::ServerContext`.
+    # Recognizes `:keyrest` (`**kwargs`) because tools are invoked without a positional argument
+    # (`tool.call(**args, server_context:)`), soa `**kwargs`-only signature safely captures `server_context:`.
+    # Named keyword `server_context` must be `:key` or `:keyreq` - positional parameters (`:req` / `:opt`) that
+    # happen to be named `server_context` are excluded because the call site passes `server_context:` as a keyword,
+    # and a positional slot would receive the `{server_context: ctx}` Hash instead.
     def accepts_server_context?(method_object)
       parameters = method_object.parameters
 
-      parameters.any? { |type, name| type == :keyrest || name == :server_context }
+      parameters.any? do |type, name|
+        type == :keyrest || (name == :server_context && (type == :key || type == :keyreq))
+      end
     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, cancellation: 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,
+          cancellation: cancellation,
+        )
         tool.call(**args, server_context: server_context).to_h
       else
         tool.call(**args).to_h
@@ -537,5 +797,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