mcp 0.14.0 → 0.16.0

data/lib/mcp/configuration.rb

@@ -16,7 +16,7 @@ module MCP
     attr_writer :instrumentation_callback
 
     def initialize(exception_reporter: nil, around_request: nil, instrumentation_callback: nil, protocol_version: nil,
-      validate_tool_call_arguments: true)
+      validate_tool_call_arguments: true, validate_tool_call_results: false)
       @exception_reporter = exception_reporter
       @around_request = around_request
       @instrumentation_callback = instrumentation_callback
@@ -25,8 +25,10 @@ module MCP
         validate_protocol_version!(protocol_version)
       end
       validate_value_of_validate_tool_call_arguments!(validate_tool_call_arguments)
+      validate_value_of_validate_tool_call_results!(validate_tool_call_results)
 
       @validate_tool_call_arguments = validate_tool_call_arguments
+      @validate_tool_call_results = validate_tool_call_results
     end
 
     def protocol_version=(protocol_version)
@@ -41,6 +43,12 @@ module MCP
       @validate_tool_call_arguments = validate_tool_call_arguments
     end
 
+    def validate_tool_call_results=(validate_tool_call_results)
+      validate_value_of_validate_tool_call_results!(validate_tool_call_results)
+
+      @validate_tool_call_results = validate_tool_call_results
+    end
+
     def protocol_version
       @protocol_version || LATEST_STABLE_PROTOCOL_VERSION
     end
@@ -80,11 +88,16 @@ module MCP
     end
 
     attr_reader :validate_tool_call_arguments
+    attr_reader :validate_tool_call_results
 
     def validate_tool_call_arguments?
       !!@validate_tool_call_arguments
     end
 
+    def validate_tool_call_results?
+      !!@validate_tool_call_results
+    end
+
     def merge(other)
       return self if other.nil?
 
@@ -113,6 +126,7 @@ module MCP
       end
 
       validate_tool_call_arguments = other.validate_tool_call_arguments
+      validate_tool_call_results = other.validate_tool_call_results
 
       Configuration.new(
         exception_reporter: exception_reporter,
@@ -120,6 +134,7 @@ module MCP
         instrumentation_callback: instrumentation_callback,
         protocol_version: protocol_version,
         validate_tool_call_arguments: validate_tool_call_arguments,
+        validate_tool_call_results: validate_tool_call_results,
       )
     end
 
@@ -138,6 +153,12 @@ module MCP
       end
     end
 
+    def validate_value_of_validate_tool_call_results!(validate_tool_call_results)
+      unless validate_tool_call_results.is_a?(TrueClass) || validate_tool_call_results.is_a?(FalseClass)
+        raise ArgumentError, "validate_tool_call_results must be a boolean"
+      end
+    end
+
     def default_exception_reporter
       @default_exception_reporter ||= ->(exception, server_context) {}
     end

data/lib/mcp/server/transports/stdio_transport.rb

@@ -54,6 +54,13 @@ module MCP
           false
         end
 
+        # NOTE: This signature deliberately matches the abstract `Transport#send_request` contract
+        # (`method, params = nil`) without the cancellation kwargs that `StreamableHTTPTransport#send_request` accepts.
+        # On Ruby 2.7 the project's supported minimum a method that mixes a positional `params` Hash with
+        # explicit keyword arguments cannot be called as `send_request(method, { ... })` - the trailing Hash would be
+        # auto-promoted to keyword arguments. Stdio is single-threaded and blocks on `$stdin.gets`, so nested-request
+        # cancellation has very limited value here regardless; servers that need cancellation propagation for nested
+        # server-to-client requests should use `StreamableHTTPTransport`.
         def send_request(method, params = nil)
           request_id = generate_request_id
           request = { jsonrpc: "2.0", id: request_id, method: method }

data/lib/mcp/server/transports/streamable_http_transport.rb

@@ -175,7 +175,7 @@ module MCP
         # sends the request via SSE stream, then blocks on `queue.pop`.
         # When the client POSTs a response, `handle_response` matches it by `request_id`
         # and pushes the result onto the queue, unblocking this thread.
-        def send_request(method, params = nil, session_id: nil, related_request_id: nil)
+        def send_request(method, params = nil, session_id: nil, related_request_id: nil, parent_cancellation: nil, server_session: nil)
           if @stateless
             raise "Stateless mode does not support server-to-client requests."
           end
@@ -190,6 +190,7 @@ module MCP
 
           request_id = generate_request_id
           queue = Queue.new
+          cancel_hook = nil
 
           request = { jsonrpc: "2.0", id: request_id, method: method }
           request[:params] = params if params
@@ -229,6 +230,16 @@ module MCP
             raise "No active stream for #{method} request."
           end
 
+          if parent_cancellation && server_session
+            cancel_hook = parent_cancellation.on_cancel do |reason|
+              server_session.send_peer_cancellation(
+                nested_request_id: request_id,
+                related_request_id: related_request_id,
+                reason: reason,
+              )
+            end
+          end
+
           response = queue.pop
 
           if response.is_a?(Hash) && response.key?(:error)
@@ -239,8 +250,18 @@ module MCP
             raise "SSE session closed while waiting for #{method} response."
           end
 
+          if response == :cancelled
+            reason = @mutex.synchronize { @pending_responses.dig(request_id, :cancel_reason) }
+            raise MCP::CancelledError.new(
+              "#{method} request was cancelled",
+              request_id: request_id,
+              reason: reason,
+            )
+          end
+
           response
         ensure
+          parent_cancellation.off_cancel(cancel_hook) if cancel_hook
           if request_id
             @mutex.synchronize do
               @pending_responses.delete(request_id)
@@ -248,6 +269,24 @@ module MCP
           end
         end
 
+        # Unblocks a `send_request` awaiting a response when the peer is being cancelled.
+        # The waiting thread will see `:cancelled` on its queue and raise `MCP::CancelledError`.
+        #
+        # Race note: this is first-writer-wins on the pending-response queue. If a real response
+        # has already been pushed (client responded before the cancel hook fired), that response
+        # wins and `:cancelled` is enqueued behind it but never read - `send_request` returns
+        # the real response and deletes the pending entry in its `ensure` block. Conversely,
+        # if `:cancelled` arrives first, any later client response is silently dropped in `handle_response`
+        # because the pending entry has been removed.
+        def cancel_pending_request(request_id, reason: nil)
+          @mutex.synchronize do
+            if (pending = @pending_responses[request_id])
+              pending[:cancel_reason] = reason
+              pending[:queue].push(:cancelled)
+            end
+          end
+        end
+
         private
 
         def start_reaper_thread
@@ -309,6 +348,7 @@ module MCP
             return missing_session_id_response if !@stateless && !session_id
 
             if notification?(body)
+              dispatch_notification(body_string, session_id)
               handle_accepted
             elsif response?(body)
               return session_not_found_response if !@stateless && !session_exists?(session_id)
@@ -459,6 +499,22 @@ module MCP
           !body[:id] && !!body[:method]
         end
 
+        # Dispatches a client-originated notification (e.g. `notifications/cancelled`,
+        # `notifications/initialized`) through the server so it can update session state.
+        def dispatch_notification(body_string, session_id)
+          server_session = nil
+          if session_id && !@stateless
+            @mutex.synchronize do
+              session = @sessions[session_id]
+              server_session = session[:server_session] if session
+            end
+          end
+
+          dispatch_handle_json(body_string, server_session)
+        rescue => e
+          MCP.configuration.exception_reporter.call(e, { error: "Failed to dispatch notification" })
+        end
+
         def response?(body)
           !!body[:id] && !body[:method]
         end
@@ -536,6 +592,12 @@ module MCP
             handle_request_with_sse_response(body_string, session_id, server_session, related_request_id: related_request_id)
           else
             response = dispatch_handle_json(body_string, server_session)
+
+            # `Server#handle_json` returns `nil` when cancellation has suppressed the JSON-RPC response per spec.
+            # Mirror the notification path and ack with 202 instead of returning a 200 with a `nil` Rack body,
+            # which would produce an empty body the client cannot parse as JSON.
+            return handle_accepted if response.nil?
+
             [200, { "Content-Type" => "application/json" }, [response]]
           end
         end

data/lib/mcp/server.rb

@@ -1,6 +1,8 @@
 # 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"
@@ -160,8 +162,8 @@ module MCP
       end
     end
 
-    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)
+    def define_tool(name: nil, title: nil, description: nil, input_schema: nil, output_schema: nil, annotations: nil, meta: nil, &block)
+      tool = Tool.define(name: name, title: title, description: description, input_schema: input_schema, output_schema: output_schema, annotations: annotations, meta: meta, &block)
       tool_name = tool.name_value
 
       @tool_names << tool_name
@@ -384,6 +386,13 @@ module MCP
     end
 
     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", server_context: { request: request }) do
@@ -395,6 +404,12 @@ 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) {
         reported_exception = nil
         instrument_call(
@@ -406,23 +421,33 @@ module MCP
           when Methods::INITIALIZE
             init(params, session: session)
           when Methods::RESOURCES_READ
-            { contents: @handlers[Methods::RESOURCES_READ].call(params) }
+            { contents: read_resource_contents(params, session: session, related_request_id: related_request_id, cancellation: cancellation) }
           when Methods::RESOURCES_SUBSCRIBE, Methods::RESOURCES_UNSUBSCRIBE
-            @handlers[method].call(params)
+            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, related_request_id: related_request_id)
+            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)
+            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)
@@ -434,10 +459,23 @@ module MCP
           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 },
@@ -516,7 +554,7 @@ module MCP
       { tools: page[:items], nextCursor: page[:next_cursor] }.compact
     end
 
-    def call_tool(request, session: nil, related_request_id: nil)
+    def call_tool(request, session: nil, related_request_id: nil, cancellation: nil)
       tool_name = request[:name]
 
       tool = tools[tool_name]
@@ -533,7 +571,7 @@ module MCP
         add_instrumentation_data(error: :missing_required_arguments)
 
         missing = tool.input_schema.missing_required_arguments(arguments).join(", ")
-        raise RequestHandlerError.new("Missing required arguments: #{missing}", request, error_type: :invalid_params)
+        return error_tool_response("Missing required arguments: #{missing}")
       end
 
       if configuration.validate_tool_call_arguments && tool.input_schema
@@ -542,14 +580,20 @@ module MCP
         rescue Tool::InputSchema::ValidationError => e
           add_instrumentation_data(error: :invalid_schema)
 
-          raise RequestHandlerError.new(e.message, request, error_type: :invalid_params)
+          return error_tool_response(e.message)
         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, related_request_id: related_request_id)
-    rescue RequestHandlerError
+      result = 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
+      )
+      validate_tool_call_result!(tool, result)
+      result
+    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
       raise RequestHandlerError.new(
@@ -566,7 +610,7 @@ module MCP
       { 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
@@ -579,7 +623,14 @@ 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)
@@ -600,14 +651,82 @@ module MCP
       { resourceTemplates: page[:items], nextCursor: page[:next_cursor] }.compact
     end
 
-    def complete(params)
+    def complete(params, session: nil, related_request_id: nil, cancellation: nil)
       validate_completion_params!(params)
 
-      result = @handlers[Methods::COMPLETION_COMPLETE].call(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 = {})
       configuration.exception_reporter.call(exception, server_context)
     end
@@ -628,18 +747,40 @@ module MCP
       ).to_h
     end
 
+    def validate_tool_call_result!(tool, result)
+      return unless configuration.validate_tool_call_results
+      return unless tool.output_schema
+      return if result[:isError]
+
+      tool.output_schema.validate_result(result[:structuredContent])
+    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, related_request_id: 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, related_request_id: related_request_id)
-        server_context = ServerContext.new(context, progress: progress, notification_target: session, 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

data/lib/mcp/server_context.rb

@@ -2,11 +2,22 @@
 
 module MCP
   class ServerContext
-    def initialize(context, progress:, notification_target:, related_request_id: nil)
+    attr_reader :cancellation
+
+    def initialize(context, progress:, notification_target:, related_request_id: nil, cancellation: nil)
       @context = context
       @progress = progress
       @notification_target = notification_target
       @related_request_id = related_request_id
+      @cancellation = cancellation
+    end
+
+    def cancelled?
+      !!@cancellation&.cancelled?
+    end
+
+    def raise_if_cancelled!
+      @cancellation&.raise_if_cancelled!
     end
 
     # Reports progress for the current tool operation.