mcp 0.21.0 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7ace5af244e82b2df4f3fef449fd0942d3d9be46746d820f8207cfcee87af52
-  data.tar.gz: ce4b53defad3ed24646806c2236a8d79c68597c7225fa4fcef20fd2d85031c24
+  metadata.gz: c0e0cdbc945ee9ec5d178aeaedb1c8af84eca0bae8db8e264f523b47b8d67c52
+  data.tar.gz: 6acb2d299d9ae215c26db733091ebbcbb3f6b1477c94d9b4047f9ab37c3a8f0c
 SHA512:
-  metadata.gz: 2c2ef2a03fb1b989e691aea55d350f06b9f1f357b0acfcda4e227ca359c3a12990d06fe280ced39b1e6d620181aa9c7b8d355d5985c70d090512636da7c34f3a
-  data.tar.gz: a75f884057bc318a98943fec8967c4725c63dd767552dc52591c8e08143474f8a28907e929cdbe0efb645426766b75314449b9df8c3c86aa90bb0a68247004ff
+  metadata.gz: 8299a6cf0101d4b8b980a69ed3128636aae6f0497fb431d14fdc0f6b8b659fb18ab5d886cf1cb567c53f385a4f8c0cdaf5e91aff6d1a4fe4daefca25d17a7dc2
+  data.tar.gz: dff4075f2a0fdf27329af3455b1db6960e38f557ea2436388f1a271d6915172e318b9630ccc8312fab16e3e8ac42e0dc84ef20e974b313056d377f3798d4a83c

data/README.md

@@ -41,7 +41,7 @@ It implements the Model Context Protocol specification, handling model context r
 - Supports roots (server-to-client filesystem boundary queries)
 - Supports sampling (server-to-client LLM completion requests)
 - Supports cursor-based pagination for list operations
-- Supports server-side cancellation of in-flight requests (notifications/cancelled)
+- Supports cancellation of in-flight requests on both server and client (notifications/cancelled)
 
 ### Supported Methods
 
@@ -698,8 +698,28 @@ class WeatherTool < MCP::Tool
 end
 ```
 
-Please note: in this case, you must provide `type: "array"`. The default type
-for output schemas is `object`.
+Please note: in this case, you must provide `type: "array"`. The default type for output schemas is `object`,
+applied only when the schema declares no root keyword (`type`, `$ref`, `oneOf`, `anyOf`, `allOf`, `not`, `if`, `const`, `enum`).
+
+Per SEP-2106, an output schema may be any valid JSON Schema 2020-12 document, including a primitive root
+(`{ type: "string" }`) or a root-level composition:
+
+```ruby
+class FlexibleTool < MCP::Tool
+  output_schema(
+    oneOf: [
+      { type: "string" },
+      { type: "array", items: { type: "number" } }
+    ]
+  )
+end
+```
+
+Input schemas keep `type: "object"` at the root but accept the full 2020-12 vocabulary below it
+(`$defs`/`$ref`, `oneOf`/`anyOf`/`allOf`/`not`, `if`/`then`/`else`). Two resource bounds apply to
+all tool schemas: only same-document `$ref`s (starting with `#`) are accepted, and documents are
+capped at `MCP::Tool::Schema::MAX_SCHEMA_DEPTH` nesting levels and `MCP::Tool::Schema::MAX_SUBSCHEMA_COUNT` subschema objects;
+violations raise `ArgumentError` at construction time.
 
 MCP spec for the [Output Schema](https://modelcontextprotocol.io/specification/latest/server/tools#output-schema) specifies that:
 
@@ -729,6 +749,10 @@ Tools can return structured data alongside text content using the `structured_co
 
 The structured content will be included in the JSON-RPC response as the `structuredContent` field.
 
+Per SEP-2106, `structured_content` may be any JSON value, not only an object. When a tool returns a non-object value (e.g. an array)
+without providing any content blocks, the server automatically mirrors it into `content` as serialized JSON text so older clients
+that only read `content` still receive the data.
+
 ```ruby
 class WeatherTool < MCP::Tool
   description "Get current weather and return structured data"
@@ -1205,12 +1229,7 @@ poll it to exit early. When a tool returns after cancellation has been observed,
 the server suppresses the JSON-RPC response, matching the spec. The `initialize` request
 is never cancellable per the spec.
 
-> [!NOTE]
-> Client-initiated cancellation (`Client#cancel` equivalent that would also abort
-> the calling thread's wait) is not yet implemented. Sending `notifications/cancelled`
-> from the client side can be done by constructing the notification payload and writing it
-> directly through the transport, but the calling thread does not yet unwind automatically.
-> This is tracked as a follow-up.
+Client-initiated cancellation is also supported: see [Client-Side: Cancelling an In-Flight Request](#client-side-cancelling-an-in-flight-request) below.
 
 #### Server-Side: Handlers that Check for Cancellation
 
@@ -1319,6 +1338,60 @@ Nested cancellation propagation is supported on `StreamableHTTPTransport` only.
 the parent `tools/call` is cancelled. The parent tool itself still observes cancellation
 via `server_context.cancelled?` between nested calls.
 
+#### Client-Side: Cancelling an In-Flight Request
+
+`MCP::Client` lets the caller cancel a request it has already issued. The recommended pattern is to pass
+an `MCP::Cancellation` token into the request method, run the request on a worker thread, and call
+`cancellation.cancel(reason:)` from another thread. The cancelling thread sends `notifications/cancelled` to
+the server, and the calling thread is woken up with `MCP::CancelledError`:
+
+```ruby
+client = MCP::Client.new(transport: transport)
+cancellation = MCP::Cancellation.new
+
+Thread.new do
+  client.call_tool(name: "slow_tool", arguments: {}, cancellation: cancellation)
+rescue MCP::CancelledError
+  # cleanup
+end
+
+# Later, from another thread:
+cancellation.cancel(reason: "user pressed cancel")
+```
+
+All request methods (`tools`, `list_tools`, `resources`, `list_resources`, `resource_templates`, `list_resource_templates`,
+`prompts`, `list_prompts`, `call_tool`, `read_resource`, `get_prompt`, `complete`, `ping`) accept the `cancellation:` keyword.
+Request ids are managed internally, so the token is the only thing a caller needs to cancel a request.
+
+> [!NOTE]
+> When a cancel wins the race, the SDK's worker thread that is blocked on the underlying I/O is *not* force-killed;
+> it stays blocked until the transport actually returns (or the user closes the transport). This matches the server-side
+> `StreamableHTTPTransport#send_request` trade-off. For `StreamableHTTPTransport#send_request` trade-off. For `Client::HTTP`
+> the leak resolves as soon as the server sends any response; for `Client::Stdio` you may need to call `client.transport.close`
+> to free the thread if the server stops responding entirely. The cancel-dispatch thread waits for the worker's send-boundary signal
+> (`&on_sent` from `send_request`) before issuing `notifications/cancelled`, so the cancel is held until the worker has at
+> least committed to writing the request; while the worker is wedged the cancel notification is deferred along with it.
+
+##### Wire-order guarantees
+
+`Client::Stdio` serializes the request write and any subsequent `notifications/cancelled` write through a single `@write_mutex`,
+so the server is guaranteed to read the request line before the cancel line.
+
+`Client::HTTP` cannot offer the same wire-arrival guarantee. Faraday's synchronous `post` does not expose a post-write / pre-response hook,
+so the SDK yields just before the request POST is dispatched. After the yield, the cancel-dispatch thread issues a separate `notifications/cancelled` POST
+on its own connection, and the two POSTs may overlap on the network. The spec is satisfied either way: the sender has already issued the request and
+still believes it to be in-progress when issuing the cancel ([MCP cancellation spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/cancellation)),
+and on the receiver side, "receivers MAY ignore a cancellation notification whose `requestId` is unknown" covers the case where the cancel POST
+happens to arrive first. The calling thread raises `MCP::CancelledError` regardless of network ordering.
+
+##### Custom transports
+
+Custom transports that want to support `cancellation:` must implement `send_notification(notification:)` so `notifications/cancelled` can be delivered.
+They should also accept the optional block passed to `send_request(request:, &on_sent)` and call it once the request bytes have been handed off to the wire
+(under a write-side mutex for stdio-style transports, immediately before the synchronous round-trip for HTTP-style transports).
+The cancel-dispatch thread waits on this signal before sending `notifications/cancelled`. Transports that do not invoke the block fall back to waiting for
+the worker thread to terminate, which preserves wire-order at the cost of delaying the cancel notification until the request has fully completed.
+
 ### Ping
 
 The MCP Ruby SDK supports the

data/lib/mcp/annotations.rb

@@ -2,9 +2,14 @@
 
 module MCP
   class Annotations
+    SUPPORTED_AUDIENCES = ["user", "assistant"].freeze
+
     attr_reader :audience, :priority, :last_modified
 
     def initialize(audience: nil, priority: nil, last_modified: nil)
+      if audience && !(audience.is_a?(Array) && audience.all? { |role| SUPPORTED_AUDIENCES.include?(role) })
+        raise ArgumentError, 'The value of audience must be an array of "user" or "assistant".'
+      end
       raise ArgumentError, "The value of priority must be between 0 and 1." if priority && !priority.between?(0, 1)
 
       @audience = audience

data/lib/mcp/client/http.rb

@@ -16,6 +16,8 @@ module MCP
       ACCEPT_HEADER = "application/json, text/event-stream"
       SESSION_ID_HEADER = "Mcp-Session-Id"
       PROTOCOL_VERSION_HEADER = "MCP-Protocol-Version"
+      METHOD_HEADER = "Mcp-Method"
+      NAME_HEADER = "Mcp-Name"
 
       # Raised when an `oauth:` provider is paired with an MCP URL that is neither HTTPS nor
       # a loopback `http://` URL, since a bearer token sent over plain HTTP to a remote host
@@ -178,9 +180,18 @@ module MCP
       end
 
       # Sends a JSON-RPC request and returns the parsed response body.
-      # After a successful `initialize` handshake, the session ID and protocol
-      # version returned by the server are captured and automatically included
-      # on subsequent requests.
+      # After a successful `initialize` handshake, the session ID and protocol version returned by
+      # the server are captured and automatically included on subsequent requests.
+      #
+      # If a block is given, it is invoked just before Faraday's `post` is called.
+      # Faraday's synchronous `post` does not expose a post-write / pre-response hook,
+      # so this is the latest send-boundary signal the adapter exposes; the actual TCP write happens
+      # inside `post`. `MCP::Client#dispatch_with_cancellation` uses this yield to release
+      # the cancel-dispatch thread, which then issues a separate `notifications/cancelled` POST
+      # that may overlap with the original request on the network. The spec covers this:
+      # the sender has issued the request and still believes it in-progress, and receivers MAY ignore
+      # a cancellation referring to an unknown request id when the cancel POST happens to arrive first.
+      # https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/cancellation
       def send_request(request:)
         method = request[:method] || request["method"]
         params = request[:params] || request["params"]
@@ -188,7 +199,8 @@ module MCP
         step_up_retried = false
 
         begin
-          response = client.post("", request, session_headers)
+          yield if block_given?
+          response = client.post("", request, session_headers.merge(request_metadata_headers(method, params)))
           body = parse_response_body(response, method, params)
 
           capture_session_info(method, response, body)
@@ -274,6 +286,23 @@ module MCP
         end
       end
 
+      # Sends a JSON-RPC notification (no response expected). Used by `Client#cancel` to deliver
+      # `notifications/cancelled` for an in-flight request. The server acknowledges with HTTP 202 Accepted
+      # per the Streamable HTTP spec.
+      def send_notification(notification:)
+        method = notification[:method] || notification["method"]
+
+        client.post("", notification, session_headers)
+        nil
+      rescue Faraday::Error => e
+        raise RequestHandlerError.new(
+          "Failed to send #{method} notification",
+          { method: method },
+          error_type: :internal_error,
+          original_error: e,
+        )
+      end
+
       # Terminates the session by sending an HTTP DELETE to the MCP endpoint
       # with the current `Mcp-Session-Id` header, and clears locally tracked
       # session state afterward. No-op when no session has been established.
@@ -341,6 +370,39 @@ module MCP
         request_headers
       end
 
+      # Per SEP-2243, mirror the JSON-RPC method and target name/uri into HTTP headers so intermediaries
+      # can route and inspect requests without parsing the body. `Mcp-Name` comes from `params.name`
+      # (tools, prompts) or, when absent, `params.uri` (resources).
+      #
+      # https://modelcontextprotocol.io/specification/draft/basic/transports/streamable-http#request-metadata
+      def request_metadata_headers(method, params)
+        return {} unless method
+
+        metadata_headers = { METHOD_HEADER => method }
+        if params.is_a?(Hash)
+          name = params[:name] || params["name"]
+          name = params[:uri] || params["uri"] unless name.is_a?(String)
+          metadata_headers[NAME_HEADER] = encode_header_value(name) if name.is_a?(String)
+        end
+
+        metadata_headers
+      end
+
+      # A header value that is not safe to transmit as-is - non-ASCII, control characters (including CR/LF,
+      # which would otherwise allow header injection), or significant leading/trailing whitespace - is wrapped as
+      # `=?base64?<base64>?=`. Safe ASCII values are sent unchanged.
+      def encode_header_value(value)
+        return value if safe_header_value?(value)
+
+        "=?base64?#{[value].pack("m0")}?="
+      end
+
+      def safe_header_value?(value)
+        value.bytes.all? { |byte| byte.between?(0x20, 0x7e) } &&
+          (value.empty? || (!value.start_with?(" ", "\t") && !value.end_with?(" ", "\t"))) &&
+          !(value.start_with?("=?base64?") && value.end_with?("?="))
+      end
+
       # Drives the OAuth orchestrator on a 401 from the MCP endpoint.
       # The `WWW-Authenticate` header (when present) supplies the `resource_metadata`
       # URL and an optional `scope` challenge per RFC 9728 Section 5.1.

data/lib/mcp/client/stdio.rb

@@ -34,6 +34,9 @@ module MCP
         @started = false
         @initialized = false
         @server_info = nil
+        # Serializes writes to `@stdin` so a request line and a notification line emitted from
+        # different threads (e.g. cancellation) cannot interleave on the wire.
+        @write_mutex = Mutex.new
       end
 
       # Performs the MCP `initialize` handshake: sends an `initialize` request
@@ -132,6 +135,10 @@ module MCP
         @initialized
       end
 
+      # Transports may yield once the request line has been written to `@stdin`.
+      # `MCP::Client#dispatch_with_cancellation` uses this signal to ensure a `notifications/cancelled`
+      # write does not race ahead of the request write on the wire. The yield happens inside `@write_mutex`,
+      # so any subsequent `send_notification` write waits for the mutex and is guaranteed to land after the request.
       def send_request(request:)
         start unless @started
         unless @initialized
@@ -139,10 +146,23 @@ module MCP
           connect
         end
 
-        write_message(request)
+        @write_mutex.synchronize do
+          write_message(request)
+          yield if block_given?
+        end
         read_response(request)
       end
 
+      # Sends a JSON-RPC notification (no response expected). Used by `Client#cancel` to deliver
+      # `notifications/cancelled` for an in-flight request.
+      def send_notification(notification:)
+        start unless @started
+        connect unless @initialized
+
+        @write_mutex.synchronize { write_message(notification) }
+        nil
+      end
+
       def start
         raise "MCP::Client::Stdio already started" if @started
 

data/lib/mcp/client.rb

@@ -107,6 +107,8 @@ module MCP
     # @param cursor [String, nil] Cursor from a previous page response.
     # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
     #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
+    # @param cancellation [MCP::Cancellation, nil] Optional token; cancelling it sends
+    #   `notifications/cancelled` to the server and raises `MCP::CancelledError` from this call.
     # @return [MCP::Client::ListToolsResult] Result with `tools` (Array<MCP::Client::Tool>)
     #   and `next_cursor` (String or nil).
     #
@@ -118,9 +120,9 @@ module MCP
     #     cursor = page.next_cursor
     #     break unless cursor
     #   end
-    def list_tools(cursor: nil, meta: nil)
+    def list_tools(cursor: nil, meta: nil, cancellation: nil)
       params = cursor ? { cursor: cursor } : nil
-      response = request(method: "tools/list", params: params, meta: meta)
+      response = request(method: "tools/list", params: params, meta: meta, cancellation: cancellation)
       result = response["result"] || {}
 
       tools = (result["tools"] || []).map do |tool|
@@ -141,6 +143,9 @@ module MCP
     #
     # Each call will make a new request - the result is not cached.
     #
+    # @param cancellation [MCP::Cancellation, nil] Optional cancellation token.
+    #   Cancelling it aborts whichever page is currently in flight; pages already returned are kept,
+    #   but the call raises `MCP::CancelledError` instead of returning the partial set.
     # @return [Array<MCP::Client::Tool>] An array of available tools.
     #
     # @example
@@ -148,9 +153,9 @@ module MCP
     #   tools.each do |tool|
     #     puts tool.name
     #   end
-    def tools
+    def tools(cancellation: nil)
       # TODO: consider renaming to `list_all_tools`.
-      fetch_all_pages { |cursor| list_tools(cursor: cursor) }.flat_map(&:tools)
+      fetch_all_pages { |cursor| list_tools(cursor: cursor, cancellation: cancellation) }.flat_map(&:tools)
     end
 
     # Returns a single page of resources from the server.
@@ -158,11 +163,12 @@ module MCP
     # @param cursor [String, nil] Cursor from a previous page response.
     # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
     #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
+    # @param cancellation [MCP::Cancellation, nil] Optional cancellation token.
     # @return [MCP::Client::ListResourcesResult] Result with `resources` (Array<Hash>)
     #   and `next_cursor` (String or nil).
-    def list_resources(cursor: nil, meta: nil)
+    def list_resources(cursor: nil, meta: nil, cancellation: nil)
       params = cursor ? { cursor: cursor } : nil
-      response = request(method: "resources/list", params: params, meta: meta)
+      response = request(method: "resources/list", params: params, meta: meta, cancellation: cancellation)
       result = response["result"] || {}
 
       ListResourcesResult.new(
@@ -178,10 +184,11 @@ module MCP
     #
     # Each call will make a new request - the result is not cached.
     #
+    # @param cancellation [MCP::Cancellation, nil] Optional cancellation token (see {#tools}).
     # @return [Array<Hash>] An array of available resources.
-    def resources
+    def resources(cancellation: nil)
       # TODO: consider renaming to `list_all_resources`.
-      fetch_all_pages { |cursor| list_resources(cursor: cursor) }.flat_map(&:resources)
+      fetch_all_pages { |cursor| list_resources(cursor: cursor, cancellation: cancellation) }.flat_map(&:resources)
     end
 
     # Returns a single page of resource templates from the server.
@@ -189,11 +196,12 @@ module MCP
     # @param cursor [String, nil] Cursor from a previous page response.
     # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
     #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
+    # @param cancellation [MCP::Cancellation, nil] Optional cancellation token.
     # @return [MCP::Client::ListResourceTemplatesResult] Result with `resource_templates`
     #   (Array<Hash>) and `next_cursor` (String or nil).
-    def list_resource_templates(cursor: nil, meta: nil)
+    def list_resource_templates(cursor: nil, meta: nil, cancellation: nil)
       params = cursor ? { cursor: cursor } : nil
-      response = request(method: "resources/templates/list", params: params, meta: meta)
+      response = request(method: "resources/templates/list", params: params, meta: meta, cancellation: cancellation)
       result = response["result"] || {}
 
       ListResourceTemplatesResult.new(
@@ -209,10 +217,11 @@ module MCP
     #
     # Each call will make a new request - the result is not cached.
     #
+    # @param cancellation [MCP::Cancellation, nil] Optional cancellation token (see {#tools}).
     # @return [Array<Hash>] An array of available resource templates.
-    def resource_templates
+    def resource_templates(cancellation: nil)
       # TODO: consider renaming to `list_all_resource_templates`.
-      fetch_all_pages { |cursor| list_resource_templates(cursor: cursor) }.flat_map(&:resource_templates)
+      fetch_all_pages { |cursor| list_resource_templates(cursor: cursor, cancellation: cancellation) }.flat_map(&:resource_templates)
     end
 
     # Returns a single page of prompts from the server.
@@ -220,11 +229,12 @@ module MCP
     # @param cursor [String, nil] Cursor from a previous page response.
     # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
     #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
+    # @param cancellation [MCP::Cancellation, nil] Optional cancellation token.
     # @return [MCP::Client::ListPromptsResult] Result with `prompts` (Array<Hash>)
     #   and `next_cursor` (String or nil).
-    def list_prompts(cursor: nil, meta: nil)
+    def list_prompts(cursor: nil, meta: nil, cancellation: nil)
       params = cursor ? { cursor: cursor } : nil
-      response = request(method: "prompts/list", params: params, meta: meta)
+      response = request(method: "prompts/list", params: params, meta: meta, cancellation: cancellation)
       result = response["result"] || {}
 
       ListPromptsResult.new(
@@ -240,10 +250,11 @@ module MCP
     #
     # Each call will make a new request - the result is not cached.
     #
+    # @param cancellation [MCP::Cancellation, nil] Optional cancellation token (see {#tools}).
     # @return [Array<Hash>] An array of available prompts.
-    def prompts
+    def prompts(cancellation: nil)
       # TODO: consider renaming to `list_all_prompts`.
-      fetch_all_pages { |cursor| list_prompts(cursor: cursor) }.flat_map(&:prompts)
+      fetch_all_pages { |cursor| list_prompts(cursor: cursor, cancellation: cancellation) }.flat_map(&:prompts)
     end
 
     # Calls a tool via the transport layer and returns the full response from the server.
@@ -256,6 +267,8 @@ module MCP
     #   e.g. the W3C Trace Context keys reserved by SEP-414
     #   (`MCP::TraceContext::TRACEPARENT_META_KEY`, `tracestate`, `baggage`).
     #   `progress_token` takes precedence over a `progressToken` entry in `meta`.
+    # @param cancellation [MCP::Cancellation, nil] Optional cancellation token. Cancelling it from another thread
+    #   sends `notifications/cancelled` to the server and raises `MCP::CancelledError` from this call.
     # @return [Hash] The full JSON-RPC response from the transport.
     #
     # @example Call by name
@@ -267,10 +280,19 @@ module MCP
     #   response = client.call_tool(tool: tool, arguments: { foo: "bar" })
     #   structured_content = response.dig("result", "structuredContent")
     #
+    # @example Cancellable call
+    #   cancellation = MCP::Cancellation.new
+    #   Thread.new do
+    #     client.call_tool(name: "slow_tool", arguments: {}, cancellation: cancellation)
+    #   rescue MCP::CancelledError
+    #     # cleanup
+    #   end
+    #   cancellation.cancel(reason: "user pressed cancel")
+    #
     # @note
     #   The exact requirements for `arguments` are determined by the transport layer in use.
     #   Consult the documentation for your transport (e.g., MCP::Client::HTTP) for details.
-    def call_tool(name: nil, tool: nil, arguments: nil, progress_token: nil, meta: nil)
+    def call_tool(name: nil, tool: nil, arguments: nil, progress_token: nil, meta: nil, cancellation: nil)
       tool_name = name || tool&.name
       raise ArgumentError, "Either `name:` or `tool:` must be provided." unless tool_name
 
@@ -282,7 +304,7 @@ module MCP
       end
       params[:_meta] = meta_entries unless meta_entries.empty?
 
-      request(method: "tools/call", params: params)
+      request(method: "tools/call", params: params, cancellation: cancellation)
     end
 
     # Reads a resource from the server by URI and returns the contents.
@@ -290,9 +312,10 @@ module MCP
     # @param uri [String] The URI of the resource to read.
     # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
     #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
+    # @param cancellation [MCP::Cancellation, nil] Optional cancellation token.
     # @return [Array<Hash>] An array of resource contents (text or blob).
-    def read_resource(uri:, meta: nil)
-      response = request(method: "resources/read", params: { uri: uri }, meta: meta)
+    def read_resource(uri:, meta: nil, cancellation: nil)
+      response = request(method: "resources/read", params: { uri: uri }, meta: meta, cancellation: cancellation)
 
       response.dig("result", "contents") || []
     end
@@ -302,9 +325,10 @@ module MCP
     # @param name [String] The name of the prompt to get.
     # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
     #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
+    # @param cancellation [MCP::Cancellation, nil] Optional cancellation token.
     # @return [Hash] A hash containing the prompt details.
-    def get_prompt(name:, meta: nil)
-      response = request(method: "prompts/get", params: { name: name }, meta: meta)
+    def get_prompt(name:, meta: nil, cancellation: nil)
+      response = request(method: "prompts/get", params: { name: name }, meta: meta, cancellation: cancellation)
 
       response.fetch("result", {})
     end
@@ -317,12 +341,13 @@ module MCP
     # @param context [Hash, nil] Optional context with previously resolved arguments.
     # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
     #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
+    # @param cancellation [MCP::Cancellation, nil] Optional cancellation token.
     # @return [Hash] The completion result with `"values"`, `"hasMore"`, and optionally `"total"`.
-    def complete(ref:, argument:, context: nil, meta: nil)
+    def complete(ref:, argument:, context: nil, meta: nil, cancellation: nil)
       params = { ref: ref, argument: argument }
       params[:context] = context if context
 
-      response = request(method: "completion/complete", params: params, meta: meta)
+      response = request(method: "completion/complete", params: params, meta: meta, cancellation: cancellation)
 
       response.dig("result", "completion") || { "values" => [], "hasMore" => false }
     end
@@ -330,6 +355,9 @@ module MCP
     # Sends a `ping` request to the server to verify the connection is alive.
     # Per the MCP spec, the server responds with an empty result.
     #
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
+    #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
+    # @param cancellation [MCP::Cancellation, nil] Optional cancellation token.
     # @return [Hash] An empty hash on success.
     # @raise [ServerError] If the server returns a JSON-RPC error.
     # @raise [ValidationError] If the response `result` is missing or not a Hash.
@@ -338,8 +366,8 @@ module MCP
     #   client.ping # => {}
     #
     # @see https://modelcontextprotocol.io/specification/latest/basic/utilities/ping
-    def ping(meta: nil)
-      result = request(method: Methods::PING, meta: meta)["result"]
+    def ping(meta: nil, cancellation: nil)
+      result = request(method: Methods::PING, meta: meta, cancellation: cancellation)["result"]
       raise ValidationError, "Response validation failed: missing or invalid `result`" unless result.is_a?(Hash)
 
       result
@@ -372,17 +400,21 @@ module MCP
     # without mutating the caller's hashes. Per SEP-414, `_meta` carries
     # request-specific metadata such as W3C trace context (`traceparent`,
     # `tracestate`, `baggage`); see {MCP::TraceContext}.
-    def request(method:, params: nil, meta: nil)
+    def request(method:, params: nil, meta: nil, cancellation: nil)
       params = (params || {}).merge(_meta: meta) if meta && !meta.empty?
 
       request_body = {
         jsonrpc: JsonRpcHandler::Version::V2_0,
-        id: request_id,
+        id: generate_request_id,
         method: method,
       }
       request_body[:params] = params if params
 
-      response = transport.send_request(request: request_body)
+      response = if cancellation
+        dispatch_with_cancellation(request_body, cancellation)
+      else
+        transport.send_request(request: request_body)
+      end
 
       # Guard with `is_a?(Hash)` because custom transports may return non-Hash values.
       if response.is_a?(Hash) && response.key?("error")
@@ -393,8 +425,140 @@ module MCP
       response
     end
 
-    def request_id
+    # Generates a fresh JSON-RPC request id for an outgoing request.
+    # Ids are an internal concern: the public API never accepts or exposes them, and cancellation is driven through
+    # an `MCP::Cancellation` token instead.
+    def generate_request_id
       SecureRandom.uuid
     end
+
+    # Sends `request_body` while watching `cancellation`. The actual blocking `transport.send_request` runs on
+    # a worker thread; the calling thread waits on a Queue that is woken either by the response or by a cancel signal
+    # (whichever arrives first - matching the server-side `StreamableHTTPTransport#cancel_pending_request` race contract).
+    #
+    # When a cancel wins the race, the calling thread raises `MCP::CancelledError` immediately and the `notifications/cancelled`
+    # dispatch runs fire-and-forget on its own thread. We deliberately do not wait for that dispatch here: the calling thread
+    # must not be blocked by a slow or stalled transport write on the cancel path.
+    # The worker thread is also not force-killed; it stays blocked on the underlying I/O until the server actually responds
+    # (or the transport closes). This is the same trade-off the server-side `StreamableHTTPTransport#send_request` accepts and
+    # is noted in the README's Cancellation section.
+    def dispatch_with_cancellation(request_body, cancellation)
+      unless transport.respond_to?(:send_notification)
+        raise NoMethodError, "Cancellation support requires a transport that responds to `send_notification(notification:)` " \
+          "so `notifications/cancelled` can be delivered to the peer. The bundled `MCP::Client::Stdio` and `MCP::Client::HTTP` transports " \
+          "implement this interface; custom transports must add it before passing `cancellation:` to a request method."
+      end
+
+      cancellation.raise_if_cancelled!
+
+      request_id = request_body[:id]
+      queue = Queue.new
+
+      # First-writer-wins gate. Whichever side (worker or on_cancel) flips `completed` first owns the queue's single slot; the loser bails.
+      # This closes the late-cancel window between the worker pushing `:response` and the main thread completing `dispatch_with_cancellation`,
+      # where a callback firing in that gap would otherwise emit a stray `notifications/cancelled` for a request that already succeeded.
+      completion_mutex = Mutex.new
+      completed = false
+      sent_mutex = Mutex.new
+      sent_cond = ConditionVariable.new
+      request_sent = false
+      signal_sent = lambda do
+        sent_mutex.synchronize do
+          unless request_sent
+            request_sent = true
+            sent_cond.broadcast
+          end
+        end
+      end
+
+      Thread.new do
+        Thread.current.report_on_exception = false
+        begin
+          result = transport.send_request(request: request_body, &signal_sent)
+          completion_mutex.synchronize do
+            next if completed
+
+            completed = true
+            queue.push([:response, result])
+          end
+        rescue StandardError => e
+          completion_mutex.synchronize do
+            next if completed
+
+            completed = true
+            queue.push([:error, e])
+          end
+        ensure
+          # Unblock any waiting cancel-dispatch thread on completion (or error)
+          # so it does not stall when the transport ignored the block.
+          signal_sent.call
+        end
+      end
+
+      cancel_hook = cancellation.on_cancel do |reason|
+        should_dispatch = completion_mutex.synchronize do
+          next false if completed
+
+          completed = true
+
+          # Wake the waiting thread first, then dispatch the `notifications/cancelled` send on a separate thread.
+          # The wake-first ordering matters because the cancellation callback can run on the worker thread itself
+          # (e.g. a tool that triggers cancel from within `transport.send_request`), and a synchronous `send_notification`
+          # here would deadlock when the worker holds a transport-level mutex.
+          queue.push([:cancelled, reason])
+          true
+        end
+
+        next unless should_dispatch
+
+        Thread.new do
+          Thread.current.report_on_exception = false
+          # Wait for the worker's send-boundary signal before issuing `notifications/cancelled`. Bundled transports raise
+          # the signal via `&on_sent` from inside `send_request`; custom transports that ignore the block still raise it
+          # via the worker's `ensure -> signal_sent.call`, so the loop is bounded by worker termination rather than by wall-clock time.
+          # The previous fixed-duration fallback could release this thread before the worker reached its send-boundary at all,
+          # allowing the cancel to be issued without any prior request commitment - which the spec only covers under
+          # the receiver's MAY-ignore-unknown-id clause and is therefore avoided here.
+          sent_mutex.synchronize do
+            sent_cond.wait(sent_mutex) until request_sent
+          end
+          cancel(request_id: request_id, reason: reason)
+        rescue StandardError
+          # Swallow notification-send failures: the calling thread has already been woken with `:cancelled` above and
+          # is on its way to raising `MCP::CancelledError`.
+        end
+      end
+
+      tag, payload = queue.pop
+
+      case tag
+      when :response
+        payload
+      when :error
+        raise payload
+      when :cancelled
+        raise MCP::CancelledError.new(request_id: request_id, reason: payload)
+      end
+    ensure
+      cancellation&.off_cancel(cancel_hook) if cancel_hook
+    end
+
+    # Sends `notifications/cancelled` to the server for an in-flight request.
+    # Per spec, this is fire-and-forget: the server is expected to stop processing and suppress its response,
+    # with no acknowledgement returned. Driven internally by {#dispatch_with_cancellation} when a request's
+    # `cancellation` token fires.
+    def cancel(request_id:, reason: nil)
+      params = { requestId: request_id }
+      params[:reason] = reason if reason
+
+      notification = {
+        jsonrpc: JsonRpcHandler::Version::V2_0,
+        method: Methods::NOTIFICATIONS_CANCELLED,
+        params: params,
+      }
+
+      transport.send_notification(notification: notification)
+      nil
+    end
   end
 end

data/lib/mcp/server.rb

@@ -636,7 +636,7 @@ module MCP
         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
+      serialize_structured_content_fallback(result)
     rescue RequestHandlerError, CancelledError
       # CancelledError is intentionally not wrapped so `handle_request` can turn it into
       # `JsonRpcHandler::NO_RESPONSE` per the MCP cancellation spec.
@@ -801,6 +801,18 @@ module MCP
       tool.output_schema.validate_result(result[:structuredContent])
     end
 
+    # Per SEP-2106, `structuredContent` may be any JSON value, not only an object.
+    # Clients on older protocol versions may only read `content`,
+    # so when a tool returns non-object structured content without providing
+    # any content blocks, mirror the value into `content` as serialized JSON text.
+    def serialize_structured_content_fallback(result)
+      structured = result[:structuredContent]
+      return result if structured.nil? || structured.is_a?(Hash)
+      return result unless result[:content].nil? || result[:content].empty?
+
+      result.merge(content: [{ type: "text", text: JSON.generate(structured) }])
+    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:`.

data/lib/mcp/server_context.rb

@@ -130,9 +130,14 @@ module MCP
       end
     end
 
-    def method_missing(name, ...)
+    # Forward arguments explicitly with `*args, **kwargs, &block` rather than the `...` forwarding syntax.
+    # The gem supports Ruby 2.7.0 (see `required_ruby_version`), but RuboCop's Parser backend only runs on Ruby 2.7.8,
+    # so leading-argument forwarding like `def method_missing(name, ...)` is allowed by the linter even though it
+    # raises a `SyntaxError` on Ruby 2.7.0 through 2.7.2 (it was added in Ruby 2.7.3). Explicit forwarding keeps
+    # this method loadable on Ruby 2.7.0.
+    def method_missing(name, *args, **kwargs, &block)
       if @context.respond_to?(name)
-        @context.public_send(name, ...)
+        @context.public_send(name, *args, **kwargs, &block)
       else
         super
       end

data/lib/mcp/tool/output_schema.rb

@@ -7,12 +7,29 @@ module MCP
     class OutputSchema < Schema
       class ValidationError < StandardError; end
 
+      # Root-level keywords whose presence means the user already chose a root schema shape,
+      # so no `type: "object"` default should be merged in.
+      ROOT_SCHEMA_KEYWORDS = [:type, :"$ref", :oneOf, :anyOf, :allOf, :not, :if, :const, :enum].freeze
+
       def validate_result(result)
         errors = fully_validate(result)
         if errors.any?
           raise ValidationError, "Invalid result: #{errors.join(", ")}"
         end
       end
+
+      private
+
+      # Per SEP-2106, an output schema may be ANY valid JSON Schema 2020-12 document: object, array, primitive,
+      # or a root-level composition.
+      # Default the root to an object only when no root schema keyword is present, which preserves the wire output
+      # of the common `properties`-only shape while leaving e.g. `{ type: "array" }` or `{ oneOf: [...] }` untouched
+      # (the old unconditional default merged `type: "object"` into root combinators, producing a wrong schema).
+      def apply_default_root_type!
+        return if ROOT_SCHEMA_KEYWORDS.any? { |keyword| @schema.key?(keyword) }
+
+        super
+      end
     end
   end
 end

data/lib/mcp/tool/schema.rb

@@ -36,16 +36,29 @@ module MCP
       end
       VALIDATION_CACHE = ValidationCache.new
 
-      # JSON Schema 2020-12 is the default dialect for MCP schema definitions
-      # per MCP 2025-11-25 (SEP-1613). Note: emission only — runtime validation
-      # is still performed against the JSON Schema draft-04 metaschema.
+      # JSON Schema 2020-12 is the default dialect for MCP schema definitions per MCP 2025-11-25 (SEP-1613),
+      # and SEP-2106 requires tool schemas to conform to the full 2020-12 vocabulary. Both emission and
+      # runtime validation use this dialect. Because MCP mandates 2020-12, the SDK validates against it
+      # regardless of any `$schema` a document embeds; for compliant schemas this is the same dialect
+      # the Python SDK's `jsonschema.validate` resolves to.
       JSON_SCHEMA_2020_12_URI = "https://json-schema.org/draft/2020-12/schema"
 
-      DRAFT4_META_SCHEMA_URI = "http://json-schema.org/draft-04/schema#"
+      # Resource bounds for schema compilation, mirroring the TypeScript SDK's schema bounds (SEP-2106):
+      # schemas may use the full JSON Schema 2020-12 vocabulary including composition keywords and `$ref`,
+      # so adversarial documents must be rejected before they can cause excessive validation cost.
+      # Only same-document references (starting with `#`) are accepted, so schema handling can never trigger network
+      # or file access.
+      MAX_SCHEMA_DEPTH = 64
+      MAX_SUBSCHEMA_COUNT = 10_000
+
+      # Reference keywords whose targets the SDK refuses to dereference. Both `$ref` and `$dynamicRef` may carry
+      # an absolute URI under JSON Schema 2020-12, so a non-same-document value is an external reference.
+      REFERENCE_KEYWORDS = [:"$ref", :"$dynamicRef"].freeze
 
       def initialize(schema = {})
         @schema = JSON.parse(JSON.dump(schema), symbolize_names: true)
-        @schema[:type] ||= "object"
+        apply_default_root_type!
+        validate_schema_bounds!
         validate_schema!
       end
 
@@ -61,6 +74,48 @@ module MCP
 
       private
 
+      # Root-type defaulting hook. The base class preserves the historical behavior of defaulting the root
+      # to an object schema; `OutputSchema` overrides this because SEP-2106 allows any root schema there.
+      def apply_default_root_type!
+        @schema[:type] ||= "object"
+      end
+
+      # Enforces `MAX_SCHEMA_DEPTH` / `MAX_SUBSCHEMA_COUNT` and the same-document reference rule over
+      # the whole schema document.
+      def validate_schema_bounds!
+        subschema_count = 0
+        stack = [[@schema, 1]]
+
+        until stack.empty?
+          node, depth = stack.pop
+          if depth > MAX_SCHEMA_DEPTH
+            raise ArgumentError,
+              "Invalid JSON Schema: nesting exceeds the maximum depth of #{MAX_SCHEMA_DEPTH}."
+          end
+
+          case node
+          when Hash
+            subschema_count += 1
+            if subschema_count > MAX_SUBSCHEMA_COUNT
+              raise ArgumentError,
+                "Invalid JSON Schema: document exceeds the maximum of #{MAX_SUBSCHEMA_COUNT} subschema objects."
+            end
+
+            REFERENCE_KEYWORDS.each do |keyword|
+              ref = node[keyword]
+              next unless ref.is_a?(String) && !ref.start_with?("#")
+
+              raise ArgumentError,
+                "Invalid JSON Schema: only same-document #{keyword} (starting with '#') is supported, got #{ref.inspect}."
+            end
+
+            node.each_value { |child| stack << [child, depth + 1] }
+          when Array
+            node.each { |child| stack << [child, depth + 1] }
+          end
+        end
+      end
+
       def stringify(obj)
         case obj
         when Hash
@@ -78,13 +133,16 @@ module MCP
       # Memoized per Schema instance because schema content is fixed at construction,
       # so the compiled schemer is reusable across many `fully_validate` calls.
       #
+      # Validated against the JSON Schema 2020-12 metaschema per SEP-2106, so `$defs`/`$ref` and
+      # the rest of the 2020-12 vocabulary resolve natively.
+      #
       # `format: false` preserves the legacy behavior of the previous `json-schema` based implementation,
       # which did not enforce `format` keywords. `RegexpError` from a malformed `pattern` is re-raised as
       # `ArgumentError` so callers see the same exception class they used to.
       def schemer
         @schemer ||= JSONSchemer.schema(
           stringify(schema_for_validation),
-          meta_schema: DRAFT4_META_SCHEMA_URI,
+          meta_schema: JSON_SCHEMA_2020_12_URI,
           format: false,
         )
       rescue RegexpError => e
@@ -112,8 +170,8 @@ module MCP
         VALIDATION_CACHE.store(key)
       end
 
-      # `json_schemer` is pinned to the draft-04 metaschema, so strip top-level `$schema` before validation:
-      # this preserves the legacy behavior of ignoring the advertised dialect URI when the SDK validates schemas.
+      # Strip the top-level `$schema` before validation so the SDK always validates against
+      # the 2020-12 metaschema (SEP-2106) regardless of any dialect URI a caller embedded in the document.
       def schema_for_validation
         return @schema unless @schema.key?(:"$schema")
 

data/lib/mcp/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp
 version: !ruby/object:Gem::Version
-  version: 0.21.0
+  version: 0.22.0
 platform: ruby
 authors:
 - Model Context Protocol
@@ -90,7 +90,7 @@ licenses:
 - Apache-2.0
 metadata:
   allowed_push_host: https://rubygems.org
-  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v0.21.0
+  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v0.22.0
   homepage_uri: https://ruby.sdk.modelcontextprotocol.io
   source_code_uri: https://github.com/modelcontextprotocol/ruby-sdk
   bug_tracker_uri: https://github.com/modelcontextprotocol/ruby-sdk/issues