mcp 0.21.0 → 0.23.0

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/methods.rb

@@ -47,6 +47,10 @@ module MCP
     end
 
     class << self
+      def notification?(method)
+        method.is_a?(String) && method.start_with?("notifications/")
+      end
+
       def ensure_capability!(method, capabilities)
         case method
         when PROMPTS_GET, PROMPTS_LIST

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

@@ -9,10 +9,25 @@ module MCP
       class StdioTransport < Transport
         STATUS_INTERRUPTED = Signal.list["INT"] + 128
 
-        def initialize(server)
+        # Default upper bound on a single newline-delimited frame. CRuby's `IO#gets`
+        # without a limit accumulates bytes until a newline arrives, so a peer that
+        # never emits one can grow a single String until the process is OOM-killed.
+        # 4 MiB is large enough for any realistic JSON-RPC frame, including
+        # base64-embedded images.
+        MAX_LINE_BYTES = 4 * 1024 * 1024
+
+        def initialize(server, max_line_bytes: MAX_LINE_BYTES)
           super(server)
           @open = false
           @session = nil
+          # Reject `nil` or non-positive values: `IO#gets("\n", nil)` and a negative
+          # limit read without an upper bound, which would silently disable the
+          # protection this option exists to provide.
+          unless max_line_bytes.is_a?(Integer) && max_line_bytes > 0
+            raise ArgumentError, "max_line_bytes must be a positive Integer"
+          end
+
+          @max_line_bytes = max_line_bytes
           $stdin.set_encoding("UTF-8")
           $stdout.set_encoding("UTF-8")
         end
@@ -20,7 +35,20 @@ module MCP
         def open
           @open = true
           @session = ServerSession.new(server: @server, transport: self)
-          while @open && (line = $stdin.gets)
+          while @open
+            begin
+              line = read_line($stdin)
+            rescue RequestHandlerError => e
+              # Stop accumulating and end the connection gracefully rather than
+              # letting an unbounded read exhaust memory or escape as an uncaught
+              # backtrace. Scoped to the read so genuine request errors raised while
+              # handling a frame are not swallowed here.
+              @open = false
+              MCP.configuration.exception_reporter.call(e, { error: "stdio frame exceeds limit" })
+              break
+            end
+            break if line.nil?
+
             response = @session.handle_json(line.strip)
             send_response(response) if response
           end
@@ -73,7 +101,7 @@ module MCP
             raise
           end
 
-          while @open && (line = $stdin.gets)
+          while @open && (line = read_line($stdin))
             begin
               parsed = JSON.parse(line.strip, symbolize_names: true)
             rescue JSON::ParserError => e
@@ -95,6 +123,26 @@ module MCP
 
           raise "Transport closed while waiting for response to #{method} request."
         end
+
+        private
+
+        # Reads one newline-delimited frame, bounded by `@max_line_bytes`. Returns
+        # the line (including its trailing newline) or `nil` at EOF. Raises when the
+        # limit is reached before a newline arrives, which signals a peer streaming
+        # an unbounded frame. A short final frame without a trailing newline (EOF) is
+        # still returned, since its length stays under the limit.
+        def read_line(io)
+          line = io.gets("\n", @max_line_bytes)
+          if line && !line.end_with?("\n") && line.bytesize >= @max_line_bytes
+            raise RequestHandlerError.new(
+              "stdio frame exceeds #{@max_line_bytes} bytes without a newline",
+              nil,
+              error_type: :internal_error,
+            )
+          end
+
+          line
+        end
       end
     end
   end