mcp 0.22.0 → 0.24.0

data/lib/mcp/client.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
+require_relative "client/elicitation"
 require_relative "client/oauth"
 require_relative "client/stdio"
 require_relative "client/http"
 require_relative "client/paginated_result"
 require_relative "client/tool"
+require_relative "result_type"
 
 module MCP
   class Client
@@ -29,11 +31,44 @@ module MCP
       end
     end
 
+    # Raised inside a server-to-client request handler (registered via `on_server_request`, e.g. `on_sampling`)
+    # to answer the request with a specific JSON-RPC error code instead of the default internal error.
+    # Mirrors the TypeScript SDK's `McpError` and the Python SDK's `ErrorData` return: for example,
+    # the sampling spec answers a rejected request with code `-1`.
+    # https://modelcontextprotocol.io/specification/2025-11-25/client/sampling
+    class ServerRequestError < StandardError
+      attr_reader :code
+
+      def initialize(message, code:)
+        super(message)
+        @code = code
+      end
+    end
+
     # Raised when a server response fails client-side validation, e.g., a success response
     # whose `result` field is missing or has the wrong type. This is distinct from a
     # server-returned JSON-RPC error, which is raised as `ServerError`.
     class ValidationError < StandardError; end
 
+    # Raised when a server answers with a SEP-2322 Multi Round-Trip `input_required` result instead of
+    # a final result. The result is not an error on the wire: it asks the client to fulfill the server's
+    # `inputRequests` (a map of id => `{ "method" => ..., "params" => ... }` request objects with
+    # `sampling/createMessage`, `roots/list`, or `elicitation/create` shapes) and re-issue
+    # the original request with `inputResponses` plus the echoed opaque `requestState`.
+    # This SDK does not yet drive that resume loop automatically; callers can inspect `input_requests`
+    # and respond manually.
+    # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2322
+    class InputRequiredError < StandardError
+      attr_reader :input_requests, :request_state, :result
+
+      def initialize(message, input_requests:, request_state: nil, result: nil)
+        super(message)
+        @input_requests = input_requests
+        @request_state = request_state
+        @result = result
+      end
+    end
+
     # Raised when the server responds 404 to a request containing a session ID,
     # indicating the session has expired. Inherits from `RequestHandlerError` for
     # backward compatibility with callers that rescue the generic error. Per spec,
@@ -134,7 +169,13 @@ module MCP
         )
       end
 
-      ListToolsResult.new(tools: tools, next_cursor: result["nextCursor"], meta: result["_meta"])
+      ListToolsResult.new(
+        tools: tools,
+        next_cursor: result["nextCursor"],
+        meta: result["_meta"],
+        ttl_ms: result["ttlMs"],
+        cache_scope: result["cacheScope"],
+      )
     end
 
     # Returns every tool available on the server. Iterates through all pages automatically
@@ -175,6 +216,8 @@ module MCP
         resources: result["resources"] || [],
         next_cursor: result["nextCursor"],
         meta: result["_meta"],
+        ttl_ms: result["ttlMs"],
+        cache_scope: result["cacheScope"],
       )
     end
 
@@ -208,6 +251,8 @@ module MCP
         resource_templates: result["resourceTemplates"] || [],
         next_cursor: result["nextCursor"],
         meta: result["_meta"],
+        ttl_ms: result["ttlMs"],
+        cache_scope: result["cacheScope"],
       )
     end
 
@@ -241,6 +286,8 @@ module MCP
         prompts: result["prompts"] || [],
         next_cursor: result["nextCursor"],
         meta: result["_meta"],
+        ttl_ms: result["ttlMs"],
+        cache_scope: result["cacheScope"],
       )
     end
 
@@ -352,6 +399,30 @@ module MCP
       response.dig("result", "completion") || { "values" => [], "hasMore" => false }
     end
 
+    # Registers a handler for `elicitation/create` requests the server sends while one of
+    # this client's requests is in flight. The handler receives the request `params`
+    # (message and `requestedSchema`, string keys) and must return an `ElicitResult`-shaped Hash:
+    # `{ action: "accept" | "decline" | "cancel", content: { ... } }`.
+    #
+    # Requires a transport that supports server-to-client requests (e.g. `MCP::Client::HTTP`);
+    # pass `capabilities: { elicitation: {} }` to `connect` so the server knows it may send them.
+    #
+    # @example Accept with schema defaults applied (SEP-1034)
+    #   client.on_elicitation do |params|
+    #     {
+    #       action: "accept",
+    #       content: MCP::Client::Elicitation.apply_defaults(params["requestedSchema"]),
+    #     }
+    #   end
+    # https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation
+    def on_elicitation(&handler)
+      unless transport.respond_to?(:on_server_request)
+        raise ArgumentError, "The transport does not support server-to-client requests"
+      end
+
+      transport.on_server_request(Methods::ELICITATION_CREATE, &handler)
+    end
+
     # Sends a `ping` request to the server to verify the connection is alive.
     # Per the MCP spec, the server responds with an empty result.
     #
@@ -422,9 +493,26 @@ module MCP
         raise ServerError.new(error["message"], code: error["code"], data: error["data"])
       end
 
+      raise_on_input_required(response)
+
       response
     end
 
+    # Recognizes a SEP-2322 `input_required` result and raises rather than returning it as if it were a final result.
+    # Servers on stable protocol versions never emit `resultType`, so this is a no-op for them.
+    def raise_on_input_required(response)
+      result = response.is_a?(Hash) ? response["result"] : nil
+      return unless result.is_a?(Hash) && result["resultType"] == ResultType::INPUT_REQUIRED
+
+      raise InputRequiredError.new(
+        "Server returned `input_required`; this SDK does not yet resume multi-round-trip requests (SEP-2322). " \
+          "Inspect `input_requests` to respond manually.",
+        input_requests: result["inputRequests"] || {},
+        request_state: result["requestState"],
+        result: result,
+      )
+    end
+
     # 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.

data/lib/mcp/error_codes.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module MCP
+  # MCP-specific JSON-RPC error codes, complementing the generic codes in `JsonRpcHandler::ErrorCode`.
+  #
+  # Both constants below are introduced by the stateless lifecycle of the MCP 2026-07-28 draft (SEP-2575):
+  # `UNSUPPORTED_PROTOCOL_VERSION` rejects a request whose `_meta`-carried protocol version the server does not
+  # support (`error.data: { supported: [...], requested: "..." }`), and `MISSING_REQUIRED_CLIENT_CAPABILITY`
+  # rejects a request that requires a client capability the request did not declare
+  # (`error.data: { requiredCapabilities: {...} }`). The SDK exports the vocabulary; it does not raise
+  # these codes itself yet.
+  #
+  # The values come from the spec's MCP-specific error code block, which is allocated sequentially from
+  # `-32020` toward `-32099`. `-32020` (`HEADER_MISMATCH`, SEP-2243) precedes the two codes defined here.
+  #
+  # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575
+  module ErrorCodes
+    MISSING_REQUIRED_CLIENT_CAPABILITY = -32021
+    UNSUPPORTED_PROTOCOL_VERSION = -32022
+  end
+end

data/lib/mcp/methods.rb

@@ -5,6 +5,8 @@ module MCP
     INITIALIZE = "initialize"
     PING = "ping"
     LOGGING_SET_LEVEL = "logging/setLevel"
+    # Sessionless capability discovery (MCP 2026-07-28 draft, SEP-2575).
+    SERVER_DISCOVER = "server/discover"
 
     PROMPTS_GET = "prompts/get"
     PROMPTS_LIST = "prompts/list"
@@ -47,6 +49,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
@@ -77,7 +83,7 @@ module MCP
           require_capability!(method, capabilities, :sampling)
         when ELICITATION_CREATE
           require_capability!(method, capabilities, :elicitation)
-        when INITIALIZE, PING, NOTIFICATIONS_INITIALIZED, NOTIFICATIONS_ROOTS_LIST_CHANGED,
+        when INITIALIZE, PING, SERVER_DISCOVER, NOTIFICATIONS_INITIALIZED, NOTIFICATIONS_ROOTS_LIST_CHANGED,
              NOTIFICATIONS_PROGRESS, NOTIFICATIONS_CANCELLED, NOTIFICATIONS_ELICITATION_COMPLETE
           # No specific capability required.
         end

data/lib/mcp/resource.rb

@@ -5,6 +5,141 @@ require_relative "resource/embedded"
 
 module MCP
   class Resource
+    class << self
+      NOT_SET = Object.new
+
+      attr_reader :uri_value
+      attr_reader :title_value
+      attr_reader :description_value
+      attr_reader :icons_value
+      attr_reader :mime_type_value
+      attr_reader :annotations_value
+      attr_reader :size_value
+      attr_reader :meta_value
+
+      def contents(server_context: nil)
+        raise NotImplementedError, "Subclasses must implement contents"
+      end
+
+      def to_h
+        {
+          uri: uri_value,
+          name: name_value,
+          title: title_value,
+          description: description_value,
+          icons: icons_value&.then { |icons| icons.empty? ? nil : icons.map(&:to_h) },
+          mimeType: mime_type_value,
+          annotations: annotations_value&.to_h,
+          size: size_value,
+          _meta: meta_value,
+        }.compact
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@uri_value, nil)
+        subclass.instance_variable_set(:@name_value, nil)
+        subclass.instance_variable_set(:@title_value, nil)
+        subclass.instance_variable_set(:@description_value, nil)
+        subclass.instance_variable_set(:@icons_value, nil)
+        subclass.instance_variable_set(:@mime_type_value, nil)
+        subclass.instance_variable_set(:@annotations_value, nil)
+        subclass.instance_variable_set(:@size_value, nil)
+        subclass.instance_variable_set(:@meta_value, nil)
+      end
+
+      def uri(value = NOT_SET)
+        if value == NOT_SET
+          @uri_value
+        else
+          @uri_value = value
+        end
+      end
+
+      def resource_name(value = NOT_SET)
+        if value == NOT_SET
+          name_value
+        else
+          @name_value = value
+        end
+      end
+
+      def name_value
+        @name_value || (name.nil? ? nil : StringUtils.handle_from_class_name(name))
+      end
+
+      def title(value = NOT_SET)
+        if value == NOT_SET
+          @title_value
+        else
+          @title_value = value
+        end
+      end
+
+      def description(value = NOT_SET)
+        if value == NOT_SET
+          @description_value
+        else
+          @description_value = value
+        end
+      end
+
+      def icons(value = NOT_SET)
+        if value == NOT_SET
+          @icons_value
+        else
+          @icons_value = value
+        end
+      end
+
+      def mime_type(value = NOT_SET)
+        if value == NOT_SET
+          @mime_type_value
+        else
+          @mime_type_value = value
+        end
+      end
+
+      def annotations(value = NOT_SET)
+        if value == NOT_SET
+          @annotations_value
+        else
+          @annotations_value = value.is_a?(Annotations) ? value : Annotations.new(**value)
+        end
+      end
+
+      def size(value = NOT_SET)
+        if value == NOT_SET
+          @size_value
+        else
+          @size_value = value
+        end
+      end
+
+      def meta(value = NOT_SET)
+        if value == NOT_SET
+          @meta_value
+        else
+          @meta_value = value
+        end
+      end
+
+      def define(uri: nil, name: nil, title: nil, description: nil, icons: [], mime_type: nil, annotations: nil, size: nil, meta: nil, &block)
+        Class.new(self) do
+          uri uri
+          resource_name name
+          title title
+          description description
+          icons icons
+          mime_type mime_type
+          self.annotations(annotations) if annotations
+          size size
+          meta meta
+          define_singleton_method(:contents, &block) if block
+        end
+      end
+    end
+
     attr_reader :uri, :name, :title, :description, :icons, :mime_type, :annotations, :size, :meta
 
     def initialize(uri:, name:, title: nil, description: nil, icons: [], mime_type: nil, annotations: nil, size: nil, meta: nil)

data/lib/mcp/resource_template.rb

@@ -2,6 +2,155 @@
 
 module MCP
   class ResourceTemplate
+    class << self
+      NOT_SET = Object.new
+
+      # Applied after `Regexp.escape`, which turns `{` and `}` into `\{` and `\}`.
+      # Variable names are restricted to valid Regexp named-group names,
+      # so RFC 6570 operator expressions (e.g. `{?query}`) stay literal and never match.
+      VARIABLE_PATTERN = /\\\{([A-Za-z_]\w*)\\\}/
+
+      attr_reader :uri_template_value
+      attr_reader :title_value
+      attr_reader :description_value
+      attr_reader :icons_value
+      attr_reader :mime_type_value
+      attr_reader :annotations_value
+      attr_reader :meta_value
+
+      def contents(server_context: nil, **params)
+        raise NotImplementedError, "Subclasses must implement contents"
+      end
+
+      def to_h
+        {
+          uriTemplate: uri_template_value,
+          name: name_value,
+          title: title_value,
+          description: description_value,
+          icons: icons_value&.then { |icons| icons.empty? ? nil : icons.map(&:to_h) },
+          mimeType: mime_type_value,
+          annotations: annotations_value&.to_h,
+          _meta: meta_value,
+        }.compact
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@uri_template_value, nil)
+        subclass.instance_variable_set(:@uri_template_pattern, nil)
+        subclass.instance_variable_set(:@name_value, nil)
+        subclass.instance_variable_set(:@title_value, nil)
+        subclass.instance_variable_set(:@description_value, nil)
+        subclass.instance_variable_set(:@icons_value, nil)
+        subclass.instance_variable_set(:@mime_type_value, nil)
+        subclass.instance_variable_set(:@annotations_value, nil)
+        subclass.instance_variable_set(:@meta_value, nil)
+      end
+
+      def uri_template(value = NOT_SET)
+        if value == NOT_SET
+          @uri_template_value
+        else
+          @uri_template_pattern = nil
+          @uri_template_value = value
+        end
+      end
+
+      def resource_template_name(value = NOT_SET)
+        if value == NOT_SET
+          name_value
+        else
+          @name_value = value
+        end
+      end
+
+      def name_value
+        @name_value || (name.nil? ? nil : StringUtils.handle_from_class_name(name))
+      end
+
+      def title(value = NOT_SET)
+        if value == NOT_SET
+          @title_value
+        else
+          @title_value = value
+        end
+      end
+
+      def description(value = NOT_SET)
+        if value == NOT_SET
+          @description_value
+        else
+          @description_value = value
+        end
+      end
+
+      def icons(value = NOT_SET)
+        if value == NOT_SET
+          @icons_value
+        else
+          @icons_value = value
+        end
+      end
+
+      def mime_type(value = NOT_SET)
+        if value == NOT_SET
+          @mime_type_value
+        else
+          @mime_type_value = value
+        end
+      end
+
+      def annotations(value = NOT_SET)
+        if value == NOT_SET
+          @annotations_value
+        else
+          @annotations_value = value.is_a?(Annotations) ? value : Annotations.new(**value)
+        end
+      end
+
+      def meta(value = NOT_SET)
+        if value == NOT_SET
+          @meta_value
+        else
+          @meta_value = value
+        end
+      end
+
+      # Matches a concrete URI against the template's simple RFC 6570 level-1 `{var}` expressions.
+      # Returns a symbol-keyed Hash of variable values, or `nil` if the URI does not match.
+      # Variables match one or more characters excluding `/`, and values are not percent-decoded.
+      def match_uri(uri)
+        match = uri_template_pattern&.match(uri)
+        match&.named_captures&.transform_keys(&:to_sym)
+      end
+
+      def define(uri_template: nil, name: nil, title: nil, description: nil, icons: [], mime_type: nil, annotations: nil, meta: nil, &block)
+        Class.new(self) do
+          uri_template uri_template
+          resource_template_name name
+          title title
+          description description
+          icons icons
+          mime_type mime_type
+          self.annotations(annotations) if annotations
+          meta meta
+          define_singleton_method(:contents, &block) if block
+        end
+      end
+
+      private
+
+      def uri_template_pattern
+        return if uri_template.nil?
+
+        @uri_template_pattern ||= begin
+          pattern = Regexp.escape(uri_template).gsub(VARIABLE_PATTERN) { "(?<#{Regexp.last_match(1)}>[^/]+)" }
+          Regexp.new("\\A#{pattern}\\z")
+        end
+      end
+    end
+
     attr_reader :uri_template, :name, :title, :description, :icons, :mime_type, :annotations, :meta
 
     def initialize(uri_template:, name:, title: nil, description: nil, icons: [], mime_type: nil, annotations: nil, meta: nil)

data/lib/mcp/result_type.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module MCP
+  # Values of the `resultType` result field introduced by SEP-2322 (Multi Round-Trip Requests)
+  # for the MCP 2026-07-28 draft.
+  #
+  # A result with `resultType: "input_required"` is not a final answer: it carries an `inputRequests` map
+  # of server-to-client requests (`sampling/createMessage`, `roots/list`, `elicitation/create` shapes) plus
+  # an opaque `requestState` string, and the client is expected to fulfill the requests and re-issue
+  # the original request with `inputResponses` and the echoed `requestState`. A missing `resultType`
+  # or `"complete"` is a final result.
+  #
+  # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2322
+  module ResultType
+    COMPLETE = "complete"
+    INPUT_REQUIRED = "input_required"
+  end
+end

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