mcp 0.25.0 → 1.6.0

data/lib/mcp/client/oauth/id_jag_token_exchange.rb

@@ -34,10 +34,13 @@ module MCP
           def request(token_endpoint:, id_token:, client_id:, audience:, resource:, http_client: nil)
             http_client ||= default_http_client
 
+            bounded = BoundedBody.new
+
             response = begin
-              http_client.post(token_endpoint) do |req|
+              raw_response = http_client.post(token_endpoint) do |req|
                 req.headers["Content-Type"] = "application/x-www-form-urlencoded"
                 req.headers["Accept"] = "application/json"
+                req.options.on_data = bounded.on_data
                 req.body = URI.encode_www_form(
                   "grant_type" => GRANT_TYPE,
                   "subject_token" => id_token,
@@ -48,6 +51,10 @@ module MCP
                   "client_id" => client_id,
                 )
               end
+
+              bounded.response_for(raw_response)
+            rescue BoundedBody::TooLargeError => e
+              raise ExchangeError, "#{e.message}."
             rescue Faraday::Error => e
               raise ExchangeError, "Token exchange request to #{token_endpoint} failed: #{e.class}: #{e.message}."
             end
@@ -88,8 +95,12 @@ module MCP
             assertion
           end
 
+          # `Accept-Encoding` is deliberately left unset, for the same reason as `Flow.build_http_client`:
+          # claiming that header turns Net::HTTP's `decode_content` off and would move `BoundedBody`'s cap
+          # onto compressed bytes.
           def default_http_client
             require "faraday"
+
             Faraday.new do |faraday|
               faraday.headers["Accept"] = "application/json"
             end

data/lib/mcp/client/oauth/provider.rb

@@ -48,6 +48,13 @@ module MCP
       #   The document served at the URL is a separate JSON artifact from the `client_metadata` keyword:
       #   DCR `client_metadata` MUST NOT include `client_id`, while the CIMD document MUST include `client_id` set
       #   to the URL, `client_name`, and `redirect_uris` covering `redirect_uri`.
+      # - `token_request_params` - Hash of String keys and values added to every token request this provider makes
+      #   (the authorization code exchange and refresh), for parameters the authorization server requires beyond
+      #   the grant itself. The authorization request is not affected. A key in `Flow::RESERVED_TOKEN_REQUEST_PARAMS`
+      #   raises `Flow::InvalidTokenRequestParamsError`.
+      #   The Hash is copied and frozen. See `StorageBackedProvider#token_request_params`.
+      # - `http_client_customizer` - Callable invoked with the `Faraday::Connection` the flow builds for
+      #   its own requests; see `StorageBackedProvider#http_client_customizer`.
       class Provider
         include StorageBackedProvider
 
@@ -86,7 +93,10 @@ module MCP
           callback_handler:,
           scope: nil,
           storage: nil,
-          client_id_metadata_document_url: nil
+          client_id_metadata_document_url: nil,
+          authorization_request_validator: nil,
+          token_request_params: nil,
+          http_client_customizer: nil
         )
           unless Discovery.secure_url?(redirect_uri)
             raise InsecureRedirectURIError,
@@ -108,6 +118,8 @@ module MCP
                 "per the MCP authorization specification and `draft-ietf-oauth-client-id-metadata-document`."
           end
 
+          http_client_customizer = validated_http_client_customizer(http_client_customizer)
+
           @client_metadata = client_metadata
           @redirect_uri = redirect_uri
           @redirect_handler = redirect_handler
@@ -115,6 +127,9 @@ module MCP
           @scope = scope
           @storage = storage || InMemoryStorage.new
           @client_id_metadata_document_url = client_id_metadata_document_url
+          @authorization_request_validator = authorization_request_validator
+          @token_request_params = frozen_token_request_params(token_request_params)
+          @http_client_customizer = http_client_customizer
         end
 
         # Identifies the OAuth flow this provider drives.

data/lib/mcp/client/oauth/storage_backed_provider.rb

@@ -4,16 +4,37 @@ module MCP
   class Client
     module OAuth
       # Shared token/credential persistence for the OAuth provider classes
-      # (`Provider` for the authorization-code flow and `ClientCredentialsProvider`
-      # for the client_credentials flow). The two grants differ in how they authenticate,
-      # but both read and write the same two pieces of state through a `storage` object:
-      # the token response and the client information. This module supplies that delegation
-      # so the `Flow` orchestrator can treat any provider uniformly.
+      # (`Provider` for the authorization-code flow, `ClientCredentialsProvider`
+      # for the client_credentials flow, and `CrossAppAccessProvider` for the jwt-bearer flow).
+      # The grants differ in how they authenticate, but all read and write the same two pieces of state
+      # through a `storage` object: the token response and the client information. This module supplies
+      # that delegation so the `Flow` orchestrator can treat any provider uniformly.
       #
       # Including classes must set `@storage` to an object responding to `tokens`,
       # `save_tokens(tokens)`, `client_information`, and `save_client_information(info)`
       # (see `InMemoryStorage`).
       module StorageBackedProvider
+        # Optional `->(request) { true | false }` hook, called with an `AuthorizationRequest`.
+        # An MCP server names its own authorization server and the scopes to ask for, so this is where
+        # an embedding application sees both before the request is made and can decline to proceed.
+        # `nil` (the default) authorizes whatever the server asked for, which is the behavior every
+        # MCP SDK has today.
+        attr_reader :authorization_request_validator
+
+        # Optional Hash of String keys and values added to every token request the provider makes, for parameters
+        # the authorization server requires beyond the grant itself (RFC 6749 Section 8.2 leaves room for them;
+        # Auth0's `audience` is the usual one). `nil` (the default) adds nothing.
+        # Set through `frozen_token_request_params`, which refuses a key `Flow` sets itself or a wrongly shaped value
+        # with `Flow::InvalidTokenRequestParamsError`.
+        attr_reader :token_request_params
+
+        # Optional callable invoked with the `Faraday::Connection` the flow builds for its own requests,
+        # after the SDK's defaults and before its origin guard (see `Flow.build_http_client`), so an application can
+        # add middleware to discovery, registration, and token requests or swap their adapter. `nil` (the default)
+        # keeps the default connection. The transport's own connection and customizer block never serve these requests:
+        # they are bound to the MCP server URL and carry headers meant for that server.
+        attr_reader :http_client_customizer
+
         def access_token
           tokens&.dig("access_token") || tokens&.dig(:access_token)
         end
@@ -37,6 +58,29 @@ module MCP
         def clear_tokens!
           @storage.save_tokens(nil)
         end
+
+        private
+
+        # Constructors call this before writing to `storage`, so a rejected provider leaves it untouched.
+        # The copy has its own frozen keys and values, so a later change to the caller's Hash, to a key,
+        # or to a value cannot alter what is sent to the token endpoint. Keys are copied explicitly
+        # because `Hash` copies and freezes only keys whose class is exactly `String`.
+        def frozen_token_request_params(params)
+          return if params.nil?
+
+          problem = Flow.token_request_params_problem(params)
+          raise Flow::InvalidTokenRequestParamsError, "token_request_params #{problem}" if problem
+
+          params.each_with_object({}) { |(key, value), copy| copy[key.dup.freeze] = value.dup.freeze }.freeze
+        end
+
+        # Returns `customizer` when it is `nil` or callable and raises otherwise, so a connection object passed
+        # in place of a callable fails at construction rather than at the first `401`.
+        def validated_http_client_customizer(customizer)
+          return customizer if customizer.nil? || customizer.respond_to?(:call)
+
+          raise ArgumentError, "http_client_customizer must respond to call (got #{customizer.class})."
+        end
       end
     end
   end

data/lib/mcp/client/oauth.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "oauth/authorization_request"
+require_relative "oauth/bounded_body"
 require_relative "oauth/discovery"
 require_relative "oauth/flow"
 require_relative "oauth/in_memory_storage"

data/lib/mcp/client/stdio.rb

@@ -7,7 +7,9 @@ require "timeout"
 require_relative "../../json_rpc_handler"
 require_relative "../configuration"
 require_relative "../methods"
+require_relative "../protocol_deprecations"
 require_relative "../version"
+require_relative "modern_envelope"
 
 module MCP
   class Client
@@ -26,6 +28,12 @@ module MCP
       # realistic JSON-RPC frame, including base64-embedded images.
       MAX_LINE_BYTES = 4 * 1024 * 1024
 
+      # Seconds the `server/discover` probe may wait when no `read_timeout` was configured.
+      # A compliant legacy server answers the probe with `-32601` immediately, but a non-compliant one
+      # that silently drops unknown methods would otherwise block `connect(mode: :auto)` forever.
+      # Matches the C# SDK's `DiscoverProbeTimeout` default.
+      DEFAULT_DISCOVER_PROBE_TIMEOUT = 5
+
       attr_reader :command, :args, :env, :server_info
 
       def initialize(command:, args: [], env: nil, read_timeout: nil, max_line_bytes: MAX_LINE_BYTES)
@@ -49,6 +57,9 @@ module MCP
         @started = false
         @initialized = false
         @server_info = nil
+        @modern_protocol_version = nil
+        @modern_client_info = nil
+        @modern_capabilities = 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
@@ -66,86 +77,57 @@ module MCP
       #
       # @param client_info [Hash, nil] `{ name:, version: }` identifying the client.
       #   Defaults to `{ name: "mcp-ruby-client", version: MCP::VERSION }`.
-      # @param protocol_version [String, nil] Protocol version to offer. Defaults
-      #   to `MCP::Configuration::LATEST_STABLE_PROTOCOL_VERSION`.
+      # @param protocol_version [String, nil] Protocol version to offer on the legacy handshake.
+      #   Defaults to `MCP::Configuration::LATEST_HANDSHAKE_PROTOCOL_VERSION`; a modern version
+      #   raises `ArgumentError` here (modern versions are selected via `mode: :modern`/`:auto`).
       # @param capabilities [Hash] Capabilities advertised by the client. Defaults to `{}`.
       # @return [Hash] The server's `InitializeResult`.
       # @raise [RequestHandlerError] If the server responds with a JSON-RPC error,
       #   a malformed result, or an unsupported protocol version.
+      # @param mode [Symbol] Lifecycle selection (SEP-2575): `:legacy` (default) performs
+      #   the handshake below, `:modern` skips it and probes `server/discover`,
+      #   and `:auto` probes `server/discover` first, falling back to the legacy handshake
+      #   when the server does not serve a mutually supported modern version.
       # https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#initialization
-      def connect(client_info: nil, protocol_version: nil, capabilities: {})
-        return @server_info if @initialized
+      def connect(client_info: nil, protocol_version: nil, capabilities: {}, mode: :legacy)
+        return @server_info if connected?
+
+        # Validated before `start` so a pure argument error never spawns the server process.
+        MCP::Configuration.reject_modern_handshake_version!(protocol_version) if mode == :legacy
 
         start unless @started
 
         client_info ||= { name: "mcp-ruby-client", version: MCP::VERSION }
-        protocol_version ||= MCP::Configuration::LATEST_STABLE_PROTOCOL_VERSION
 
-        init_request = {
-          jsonrpc: JsonRpcHandler::Version::V2_0,
-          id: SecureRandom.uuid,
-          method: MCP::Methods::INITIALIZE,
-          params: {
-            protocolVersion: protocol_version,
-            capabilities: capabilities,
-            clientInfo: client_info,
-          },
-        }
-
-        write_message(init_request)
-        response = read_response(init_request)
-
-        if response.key?("error")
-          error = response["error"]
-          raise RequestHandlerError.new(
-            "Server initialization failed: #{error["message"]}",
-            { method: MCP::Methods::INITIALIZE },
-            error_type: :internal_error,
-          )
-        end
-
-        unless response["result"].is_a?(Hash)
-          raise RequestHandlerError.new(
-            "Server initialization failed: missing result in response",
-            { method: MCP::Methods::INITIALIZE },
-            error_type: :internal_error,
-          )
-        end
-
-        @server_info = response["result"]
-
-        negotiated_protocol_version = @server_info["protocolVersion"]
-        unless MCP::Configuration::SUPPORTED_STABLE_PROTOCOL_VERSIONS.include?(negotiated_protocol_version)
-          # Per spec, if the client does not support the server's returned protocol version,
-          # the client SHOULD disconnect. Roll back the cached `InitializeResult` before
-          # raising so a retry starts without a stale `server_info`.
-          # https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#version-negotiation
-          @server_info = nil
-          raise RequestHandlerError.new(
-            "Server initialization failed: unsupported protocol version #{negotiated_protocol_version.inspect}",
-            { method: MCP::Methods::INITIALIZE },
-            error_type: :internal_error,
-          )
+        case mode
+        when :legacy
+          connect_legacy(client_info: client_info, protocol_version: protocol_version, capabilities: capabilities)
+        when :modern
+          connect_modern(client_info: client_info, protocol_version: protocol_version, capabilities: capabilities)
+        when :auto
+          connect_auto(client_info: client_info, protocol_version: protocol_version, capabilities: capabilities)
+        else
+          raise ArgumentError, "mode must be :legacy, :modern, or :auto"
         end
+      end
 
-        begin
-          notification = {
-            jsonrpc: JsonRpcHandler::Version::V2_0,
-            method: MCP::Methods::NOTIFICATIONS_INITIALIZED,
-          }
-          write_message(notification)
-        rescue StandardError
-          @server_info = nil
-          raise
-        end
+      # Whether the transport operates in the stateless modern lifecycle (SEP-2575):
+      # no handshake was performed and every request carries the `_meta` envelope.
+      def modern?
+        !@modern_client_info.nil?
+      end
 
-        @initialized = true
-        @server_info
+      # The protocol version in use on this connection, independent of its era:
+      # negotiated by `initialize` (legacy) or adopted via `server/discover` (modern).
+      # Returns `nil` before `connect` and after `close`.
+      def protocol_version
+        @modern_protocol_version || (@server_info && @server_info["protocolVersion"])
       end
 
-      # Returns true once `connect` has completed the handshake. Returns false before the handshake and after `close`.
+      # Returns true once `connect` has completed the handshake or adopted the modern lifecycle.
+      # Returns false before the handshake and after `close`.
       def connected?
-        @initialized
+        @initialized || modern?
       end
 
       # Transports may yield once the request line has been written to `@stdin`.
@@ -153,7 +135,16 @@ module MCP
       # 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:)
-        raise "MCP::Client#connect must be called before sending requests." unless @initialized
+        method = request[:method] || request["method"]
+        if method == MCP::Methods::SERVER_DISCOVER
+          # `server/discover` (SEP-2575) is sessionless capability discovery that
+          # works before (or instead of) `connect`.
+          start unless @started
+        elsif !connected?
+          raise "MCP::Client#connect must be called before sending requests."
+        end
+
+        request = stamp_modern(request)
 
         @write_mutex.synchronize do
           write_message(request)
@@ -166,7 +157,7 @@ module MCP
       # `notifications/cancelled` for an in-flight request.
       def send_notification(notification:)
         start unless @started
-        connect unless @initialized
+        connect unless connected?
 
         @write_mutex.synchronize { write_message(notification) }
         nil
@@ -228,10 +219,196 @@ module MCP
         @started = false
         @initialized = false
         @server_info = nil
+        leave_modern_mode
       end
 
       private
 
+      def connect_legacy(client_info:, protocol_version:, capabilities:)
+        protocol_version ||= MCP::Configuration::LATEST_HANDSHAKE_PROTOCOL_VERSION
+
+        init_request = {
+          jsonrpc: JsonRpcHandler::Version::V2_0,
+          id: SecureRandom.uuid,
+          method: MCP::Methods::INITIALIZE,
+          params: {
+            protocolVersion: protocol_version,
+            capabilities: capabilities,
+            clientInfo: client_info,
+          },
+        }
+
+        write_message(init_request)
+        response = read_response(init_request)
+
+        if response.key?("error")
+          error = response["error"]
+          raise RequestHandlerError.new(
+            "Server initialization failed: #{error["message"]}",
+            { method: MCP::Methods::INITIALIZE },
+            error_type: :internal_error,
+          )
+        end
+
+        unless response["result"].is_a?(Hash)
+          raise RequestHandlerError.new(
+            "Server initialization failed: missing result in response",
+            { method: MCP::Methods::INITIALIZE },
+            error_type: :internal_error,
+          )
+        end
+
+        @server_info = response["result"]
+
+        negotiated_protocol_version = @server_info["protocolVersion"]
+        unless MCP::Configuration::SUPPORTED_HANDSHAKE_PROTOCOL_VERSIONS.include?(negotiated_protocol_version)
+          # Per spec, if the client does not support the server's returned protocol version,
+          # the client SHOULD disconnect. A modern version is rejected along with unknown ones:
+          # the handshake settles on a legacy version by definition, and the TypeScript and Python clients refuse
+          # a modern counter-offer the same way. Roll back the cached `InitializeResult` before raising
+          # so a retry starts without a stale `server_info`.
+          # https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#version-negotiation
+          @server_info = nil
+          raise RequestHandlerError.new(
+            "Server initialization failed: unsupported protocol version #{negotiated_protocol_version.inspect}",
+            { method: MCP::Methods::INITIALIZE },
+            error_type: :internal_error,
+          )
+        end
+
+        begin
+          notification = {
+            jsonrpc: JsonRpcHandler::Version::V2_0,
+            method: MCP::Methods::NOTIFICATIONS_INITIALIZED,
+          }
+          write_message(notification)
+        rescue StandardError
+          @server_info = nil
+          raise
+        end
+
+        @initialized = true
+        @server_info
+      end
+
+      # Enters the modern lifecycle by probing `server/discover` at the requested (or latest) modern version.
+      # No `initialize` or `notifications/initialized` is sent; the probe response becomes `server_info`.
+      def connect_modern(client_info:, protocol_version:, capabilities:)
+        version = protocol_version || MCP::Configuration::LATEST_MODERN_PROTOCOL_VERSION
+        unless MCP::Configuration.modern_protocol_version?(version)
+          raise ArgumentError, "protocol_version #{version.inspect} is not a supported modern protocol version"
+        end
+
+        @modern_protocol_version = version
+        @modern_client_info = client_info
+        @modern_capabilities = capabilities || {}
+
+        begin
+          result = with_probe_read_timeout { probe_discover }
+        rescue StandardError
+          leave_modern_mode
+          raise
+        end
+
+        supported = result["supportedVersions"]
+        unless supported.is_a?(Array) && supported.include?(version)
+          leave_modern_mode
+          raise RequestHandlerError.new(
+            "Server discovery failed: no mutually supported modern protocol version " \
+              "(server supports #{supported.inspect})",
+            { method: MCP::Methods::SERVER_DISCOVER },
+            error_type: :internal_error,
+          )
+        end
+
+        # SEP-2577 deprecates roots and sampling at 2026-07-28, the revision every modern connection speaks,
+        # so the warning lives here now that the handshake cannot land on one.
+        MCP::ProtocolDeprecations.warn_for_client_capabilities(capabilities, protocol_version: version, uplevel: 1)
+
+        @server_info = result
+        @server_info
+      end
+
+      # Probes `server/discover` and adopts the modern lifecycle when the server serves
+      # a mutually supported modern version; otherwise falls back to the legacy handshake.
+      # The fallback intentionally covers a successful discovery without a mutual modern
+      # version as well: during the 2026-07-28 rollout a server may answer discovery while
+      # only serving legacy versions.
+      def connect_auto(client_info:, protocol_version:, capabilities:)
+        modern_pin = protocol_version if protocol_version && MCP::Configuration.modern_protocol_version?(protocol_version)
+        connect_modern(client_info: client_info, protocol_version: modern_pin, capabilities: capabilities)
+      rescue RequestHandlerError
+        # An explicitly requested modern version is never downgraded by the fallback: the legacy handshake cannot negotiate it,
+        # so the probe's failure is the real answer and propagates.
+        raise if modern_pin
+
+        connect_legacy(client_info: client_info, protocol_version: protocol_version, capabilities: capabilities)
+      end
+
+      def leave_modern_mode
+        @modern_protocol_version = nil
+        @modern_client_info = nil
+        @modern_capabilities = nil
+      end
+
+      # Bounds the probe read when the caller configured no `read_timeout`, and only for the probe:
+      # regular requests keep the unbounded default so long-running tools are unaffected.
+      # The timeout surfaces as a `RequestHandlerError`, which `connect_auto` treats as legacy evidence
+      # and falls back on.
+      def with_probe_read_timeout
+        return yield if @read_timeout
+
+        @read_timeout = DEFAULT_DISCOVER_PROBE_TIMEOUT
+        begin
+          yield
+        ensure
+          @read_timeout = nil
+        end
+      end
+
+      def probe_discover
+        request = {
+          jsonrpc: JsonRpcHandler::Version::V2_0,
+          id: SecureRandom.uuid,
+          method: MCP::Methods::SERVER_DISCOVER,
+        }
+
+        @write_mutex.synchronize { write_message(stamp_modern(request)) }
+        response = read_response(request)
+
+        if response.key?("error")
+          error = response["error"]
+          raise RequestHandlerError.new(
+            "Server discovery failed: #{error["message"]}",
+            { method: MCP::Methods::SERVER_DISCOVER },
+            error_type: :internal_error,
+          )
+        end
+
+        result = response["result"]
+        unless result.is_a?(Hash)
+          raise RequestHandlerError.new(
+            "Server discovery failed: missing result in response",
+            { method: MCP::Methods::SERVER_DISCOVER },
+            error_type: :internal_error,
+          )
+        end
+
+        result
+      end
+
+      # Modern requests (never notifications, whose `_meta` has no envelope) carry the SEP-2575 triple.
+      def stamp_modern(request)
+        return request unless modern? && (request[:id] || request["id"])
+
+        ModernEnvelope.stamp(
+          request,
+          protocol_version: @modern_protocol_version,
+          client_info: @modern_client_info,
+          capabilities: @modern_capabilities,
+        )
+      end
+
       def write_message(message)
         ensure_running!
         json = JSON.generate(message)
@@ -259,6 +436,18 @@ module MCP
 
           parsed = JSON.parse(line.strip)
 
+          # A frame carrying `method` is a request or notification, never the awaited response,
+          # whatever its id says: JSON-RPC id spaces are per sender, so a server-chosen ping id
+          # may legitimately collide with the awaited one. Pings are answered;
+          # other server-to-client requests over stdio stay unsupported as documented,
+          # and notifications carry no id.
+          if parsed.is_a?(Hash) && parsed.key?("method")
+            # A JSON-RPC id is a String or a Number; the reference SDKs reject other shapes at
+            # schema validation, so a ping carrying one is skipped rather than echoed back.
+            answer_ping(parsed) if parsed["method"] == MCP::Methods::PING && json_rpc_id?(parsed["id"])
+            next
+          end
+
           # A JSON-RPC message is an object; skip a non-object frame (array or scalar)
           # the same way as a frame without an id.
           next unless parsed.is_a?(Hash) && parsed.key?("id")
@@ -274,6 +463,22 @@ module MCP
         )
       end
 
+      # The ping receiver "MUST respond promptly with an empty response". Answered inline from
+      # the read loop, so a keepalive cannot stall unanswered while a response is awaited;
+      # between requests nothing reads stdout, and a queued ping is answered on the next read.
+      def answer_ping(parsed)
+        @write_mutex.synchronize do
+          write_message({ jsonrpc: JsonRpcHandler::Version::V2_0, id: parsed["id"], result: {} })
+        end
+      rescue RequestHandlerError
+        # Best effort: a pong cannot be delivered over a broken stdin, and the failure must not
+        # surface as an error of the unrelated request whose response the loop is reading.
+      end
+
+      def json_rpc_id?(id)
+        id.is_a?(String) || id.is_a?(Numeric)
+      end
+
       def ensure_running!
         return if @wait_thread.alive?
 

data/lib/mcp/client/tool.rb

@@ -3,13 +3,14 @@
 module MCP
   class Client
     class Tool
-      attr_reader :name, :description, :input_schema, :output_schema
+      attr_reader :name, :description, :input_schema, :output_schema, :annotations
 
-      def initialize(name:, description:, input_schema:, output_schema: nil)
+      def initialize(name:, description:, input_schema:, output_schema: nil, annotations: nil)
         @name = name
         @description = description
         @input_schema = input_schema
         @output_schema = output_schema
+        @annotations = annotations
       end
     end
   end