mcp 1.0.0 → 1.2.0

data/lib/mcp/client/http.rb

@@ -4,7 +4,10 @@ require "securerandom"
 require_relative "../../json_rpc_handler"
 require_relative "../configuration"
 require_relative "../methods"
+require_relative "../protocol_deprecations"
 require_relative "../version"
+require_relative "mcp_param_headers"
+require_relative "modern_envelope"
 
 module MCP
   class Client
@@ -24,6 +27,29 @@ module MCP
       DEFAULT_RECONNECTION_DELAY_MS = 1000
       MAX_RECONNECTION_ATTEMPTS = 2
 
+      # Floor on the effective reconnection delay. `listen_for_server_requests` treats a graceful close as success
+      # and resets `consecutive_failures`, so `retry: 0` never reaches the attempt cap and reconnects in a tight loop.
+      # Waiting longer than the server asked for is explicitly allowed: the `retry` field the spec points at is
+      # the one defined by WHATWG HTML, whose reconnection algorithm reads "Wait a delay equal to the reconnection time
+      # of the event source. Optionally, wait some more." Waiting *less* is what the spec's MUST rules out,
+      # and nothing here ever does that.
+      #
+      # https://html.spec.whatwg.org/multipage/server-sent-events.html#reconnection-time
+      MIN_RECONNECTION_DELAY_MS = 100
+
+      # Budget in seconds for `await_response_after_disconnect`: it gates every wait between reconnection attempts,
+      # and whatever is left of it becomes the read timeout of each resumed stream. That method runs on the calling thread,
+      # so without a deadline a server answering with a large `retry:` parks a thread of the embedding application for
+      # as long as it likes; `MAX_RECONNECTION_ATTEMPTS` caps how many times the client reconnects,
+      # not how long it waits for each. A delay that would run past the deadline is not shortened - the client stops
+      # reconnecting instead, the same kind of decision the attempt cap already makes, so the server's `retry:` is
+      # always honored in full or not acted on at all.
+      #
+      # Matches `SSE_LISTENER_READ_TIMEOUT`, this client's other "how long to wait on a quiet SSE stream" value.
+      # `listen_for_server_requests` has no such deadline: it runs on a thread this client owns and is meant
+      # to poll indefinitely, so a long `retry:` there idles the SDK's own listener rather than the application.
+      MAX_RECONNECTION_WAIT = 300
+
       # How long the standalone GET listening stream may stay idle before the read times out
       # and the connection is counted as a failure and retried. Matches the Python SDK's
       # `sse_read_timeout` default of 5 minutes; without this, the adapter's default read timeout
@@ -37,6 +63,12 @@ module MCP
       # and the server transports' request cap.
       MAX_MESSAGE_BYTES = 4 * 1024 * 1024
 
+      # Upper bound on the tools whose `x-mcp-header` declarations are retained for
+      # `Mcp-Param-*` mirroring (SEP-2243). Past the cap, newly listed tools mirror nothing
+      # (the spec's guidance to send without custom headers), so a server rotating tool names across
+      # `tools/list` responses cannot grow the registry without bound.
+      MAX_MCP_PARAM_TOOLS = 1000
+
       # 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
       # is trivially observed and stolen.
@@ -207,13 +239,24 @@ module MCP
 
       attr_reader :url, :session_id, :protocol_version, :server_info, :oauth
 
-      def initialize(url:, headers: {}, oauth: nil, max_message_bytes: MAX_MESSAGE_BYTES, &block)
+      def initialize(
+        url:,
+        headers: {},
+        oauth: nil,
+        max_message_bytes: MAX_MESSAGE_BYTES,
+        max_reconnection_wait: MAX_RECONNECTION_WAIT,
+        &block
+      )
         # `nil` or a non-positive value would make the buffering unbounded and silently
         # disable the protection, so reject it up front.
         unless max_message_bytes.is_a?(Integer) && max_message_bytes > 0
           raise ArgumentError, "max_message_bytes must be a positive Integer"
         end
 
+        unless max_reconnection_wait.is_a?(Numeric) && max_reconnection_wait > 0
+          raise ArgumentError, "max_reconnection_wait must be a positive number"
+        end
+
         if oauth && !MCP::Client::OAuth::Discovery.secure_url?(url)
           # Mask credentials (userinfo) and query parameters before quoting the URL in the error message
           # so they cannot leak into logs.
@@ -228,6 +271,7 @@ module MCP
         @faraday_customizer = block
         @oauth = oauth
         @max_message_bytes = max_message_bytes
+        @max_reconnection_wait = max_reconnection_wait
         # Snapshot the canonical URL at construction time. This single value
         # serves two related roles, both of which need to see the query string:
         #
@@ -251,6 +295,9 @@ module MCP
         @connected = false
         @server_request_handlers = {}
         @listener_thread = nil
+        @modern_client_info = nil
+        @modern_capabilities = nil
+        @mcp_param_declarations = {}
       end
 
       # Registers a handler for a server-to-client request (e.g. `elicitation/create`) delivered on an SSE stream.
@@ -280,77 +327,47 @@ 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
       #   or a malformed result.
+      # @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: {})
+      def connect(client_info: nil, protocol_version: nil, capabilities: {}, mode: :legacy)
         return @server_info if connected?
 
-        client_info ||= { name: "mcp-ruby-client", version: MCP::VERSION }
-        protocol_version ||= MCP::Configuration::LATEST_STABLE_PROTOCOL_VERSION
-
-        response = send_request(request: {
-          jsonrpc: JsonRpcHandler::Version::V2_0,
-          id: SecureRandom.uuid,
-          method: MCP::Methods::INITIALIZE,
-          params: {
-            protocolVersion: protocol_version,
-            capabilities: capabilities,
-            clientInfo: client_info,
-          },
-        })
+        # Per the SEP-2575 era model, a modern version cannot ride the legacy `initialize` handshake.
+        MCP::Configuration.reject_modern_handshake_version!(protocol_version) if mode == :legacy
 
-        if response.is_a?(Hash) && response.key?("error")
-          clear_session
-          error = response["error"]
-          raise RequestHandlerError.new(
-            "Server initialization failed: #{error["message"]}",
-            { method: MCP::Methods::INITIALIZE },
-            error_type: :internal_error,
-          )
-        end
-
-        unless response.is_a?(Hash) && response["result"].is_a?(Hash)
-          clear_session
-          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)
-          clear_session
-          raise RequestHandlerError.new(
-            "Server initialization failed: unsupported protocol version #{negotiated_protocol_version.inspect}",
-            { method: MCP::Methods::INITIALIZE },
-            error_type: :internal_error,
-          )
-        end
+        client_info ||= { name: "mcp-ruby-client", version: MCP::VERSION }
 
-        begin
-          send_request(request: {
-            jsonrpc: JsonRpcHandler::Version::V2_0,
-            method: MCP::Methods::NOTIFICATIONS_INITIALIZED,
-          })
-        rescue StandardError
-          clear_session
-          raise
+        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
 
-        @connected = true
-        start_listening if @server_request_handlers.any?
-        @server_info
+      # 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
 
       # Returns true once `connect` has completed the full handshake
-      # (`initialize` response received and `notifications/initialized` sent).
+      # (`initialize` response received and `notifications/initialized` sent),
+      # or once the modern lifecycle was adopted via `server/discover`.
       # Returns false before the first handshake and after `close`.
       def connected?
         @connected
@@ -370,6 +387,18 @@ module MCP
       # 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:)
+        # Modern requests (never notifications, whose `_meta` has no envelope) carry
+        # the SEP-2575 triple; the `MCP-Protocol-Version` header from `session_headers`
+        # matches it by construction.
+        if modern? && (request[:id] || request["id"])
+          request = ModernEnvelope.stamp(
+            request,
+            protocol_version: @protocol_version,
+            client_info: @modern_client_info,
+            capabilities: @modern_capabilities,
+          )
+        end
+
         method = request[:method] || request["method"]
         params = request[:params] || request["params"]
         oauth_retried = false
@@ -398,6 +427,7 @@ module MCP
           body = resolve_response_body(stream, response, method, params)
 
           capture_session_info(method, response, body) if response
+          capture_mcp_param_declarations(method, params, body)
 
           body
         rescue MessageTooLargeError => e
@@ -532,6 +562,163 @@ module MCP
 
       attr_reader :headers
 
+      def connect_legacy(client_info:, protocol_version:, capabilities:)
+        protocol_version ||= MCP::Configuration::LATEST_HANDSHAKE_PROTOCOL_VERSION
+
+        response = send_request(request: {
+          jsonrpc: JsonRpcHandler::Version::V2_0,
+          id: SecureRandom.uuid,
+          method: MCP::Methods::INITIALIZE,
+          params: {
+            protocolVersion: protocol_version,
+            capabilities: capabilities,
+            clientInfo: client_info,
+          },
+        })
+
+        if response.is_a?(Hash) && response.key?("error")
+          clear_session
+          error = response["error"]
+          raise RequestHandlerError.new(
+            "Server initialization failed: #{error["message"]}",
+            { method: MCP::Methods::INITIALIZE },
+            error_type: :internal_error,
+          )
+        end
+
+        unless response.is_a?(Hash) && response["result"].is_a?(Hash)
+          clear_session
+          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"]
+        # A modern version in an `InitializeResult` 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.
+        unless MCP::Configuration::SUPPORTED_HANDSHAKE_PROTOCOL_VERSIONS.include?(negotiated_protocol_version)
+          clear_session
+          raise RequestHandlerError.new(
+            "Server initialization failed: unsupported protocol version #{negotiated_protocol_version.inspect}",
+            { method: MCP::Methods::INITIALIZE },
+            error_type: :internal_error,
+          )
+        end
+
+        begin
+          send_request(request: {
+            jsonrpc: JsonRpcHandler::Version::V2_0,
+            method: MCP::Methods::NOTIFICATIONS_INITIALIZED,
+          })
+        rescue StandardError
+          clear_session
+          raise
+        end
+
+        @connected = true
+        start_listening if @server_request_handlers.any?
+        @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
+
+        enter_modern_mode(protocol_version: version, client_info: client_info, capabilities: capabilities)
+
+        begin
+          result = 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
+        @connected = true
+        @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 enter_modern_mode(protocol_version:, client_info:, capabilities:)
+        @modern_client_info = client_info
+        @modern_capabilities = capabilities || {}
+        # `session_headers` sends `@protocol_version` as the `MCP-Protocol-Version` header,
+        # which the modern lifecycle requires to match the `_meta`-carried version.
+        @protocol_version = protocol_version
+      end
+
+      def leave_modern_mode
+        @modern_client_info = nil
+        @modern_capabilities = nil
+        @protocol_version = nil
+      end
+
+      def probe_discover
+        response = send_request(request: {
+          jsonrpc: JsonRpcHandler::Version::V2_0,
+          id: SecureRandom.uuid,
+          method: MCP::Methods::SERVER_DISCOVER,
+        })
+
+        if response.is_a?(Hash) && 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.is_a?(Hash) ? response["result"] : nil
+        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
+
       def client
         require_faraday!
         @client ||= Faraday.new(url) do |faraday|
@@ -583,11 +770,56 @@ module MCP
           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)
+
+          if method == MCP::Methods::TOOLS_CALL && (declarations = @mcp_param_declarations[params[:name] || params["name"]])
+            arguments = params[:arguments] || params["arguments"]
+
+            metadata_headers.merge!(McpParamHeaders.build(declarations, arguments))
+          end
         end
 
         metadata_headers
       end
 
+      # Learns the `x-mcp-header` declarations of the tools a `tools/list` response advertises,
+      # so later `tools/call` requests can mirror the annotated arguments into `Mcp-Param-*` headers (SEP-2243).
+      # The custom headers exist on the modern lifecycle only, matching the TypeScript and Python SDKs,
+      # so legacy connections learn nothing. Only a valid, non-empty declaration set is kept:
+      # an invalid tool definition mirrors nothing,
+      # following the spec's guidance to send without custom headers when no reliable declarations are available.
+      def capture_mcp_param_declarations(method, params, body)
+        return unless modern?
+        return unless method.to_s == MCP::Methods::TOOLS_LIST && body.is_a?(Hash)
+
+        tools = body.dig("result", "tools")
+        return unless tools.is_a?(Array)
+
+        # An uncursored request answered without `nextCursor` is the complete tool universe,
+        # so knowledge about unlisted tools is stale; the registry is rebuilt from this listing,
+        # the same pruning the Python SDK applies to complete listings.
+        cursor = params.is_a?(Hash) && (params[:cursor] || params["cursor"])
+        complete = !cursor && body.dig("result", "nextCursor").nil?
+        registry = complete ? {} : @mcp_param_declarations
+
+        tools.each do |tool|
+          next unless tool.is_a?(Hash)
+
+          name = tool["name"]
+          next unless name.is_a?(String)
+
+          scan = McpParamHeaders.scan(tool["inputSchema"])
+          if scan[:valid] && !scan[:declarations].empty?
+            next if !registry.key?(name) && registry.size >= MAX_MCP_PARAM_TOOLS
+
+            registry[name] = scan[:declarations]
+          else
+            registry.delete(name)
+          end
+        end
+
+        @mcp_param_declarations = registry if complete
+      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.
@@ -727,6 +959,8 @@ module MCP
         @protocol_version = nil
         @server_info = nil
         @connected = false
+        @modern_client_info = nil
+        @modern_capabilities = nil
       end
 
       # Opens the standalone GET SSE listening stream on a background thread so server-to-client requests
@@ -780,10 +1014,26 @@ module MCP
 
           stream.reset_parser!
 
-          sleep((stream.retry_ms || DEFAULT_RECONNECTION_DELAY_MS) / 1000.0)
+          sleep(reconnection_delay_seconds(stream))
         end
       end
 
+      # The reconnection delay in seconds: the server's `retry:` value when it sent one and
+      # the default otherwise, never shortened, raised to `MIN_RECONNECTION_DELAY_MS` when the server
+      # asked for less than that. A `retry:` that is negative or not a run of digits is not a value at all;
+      # the SSE parser drops it, so those arrive here as the default rather than as something to guard.
+      def reconnection_delay_seconds(stream)
+        delay_ms = stream.retry_ms || DEFAULT_RECONNECTION_DELAY_MS
+
+        [delay_ms, MIN_RECONNECTION_DELAY_MS].max / 1000.0
+      end
+
+      # Seconds left before `deadline`, floored just above zero so a budget consumed down to the last instant
+      # still asks the adapter for a timeout rather than for "no timeout".
+      def remaining_reconnection_budget(deadline)
+        [deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0.001].max
+      end
+
       def require_faraday!
         require "faraday"
       rescue LoadError
@@ -900,23 +1150,43 @@ module MCP
 
       # SEP-1699 resumability: the server closed the SSE stream after a priming event
       # without delivering the response. Treat the graceful close like a network failure:
-      # wait the server-specified `retry:` interval (default 1000ms), then reconnect with
+      # wait the `retry:` interval the server asked for (default 1000ms), then reconnect with
       # a GET carrying `Last-Event-ID` so the server can replay the pending response on
       # the standalone stream. Mirrors the TypeScript SDK's `StreamableHTTPClientTransport`
       # reconnection and the Python SDK's `_handle_reconnection` (including its 2-attempt cap).
+      #
+      # This runs on the caller's thread, so the attempts are bounded by `max_reconnection_wait` as well as
+      # by their count: the deadline gates each wait, and what is left of it becomes the read timeout of
+      # the resumed stream. A delay that would run past the deadline is never shortened: the client stops
+      # reconnecting instead, so the server's `retry:` is honored in full or not acted on at all.
       # https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1699
       def await_response_after_disconnect(stream, method, params)
         stream.abortable = true
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @max_reconnection_wait
+        gave_up_waiting = false
 
         MAX_RECONNECTION_ATTEMPTS.times do
-          sleep((stream.retry_ms || DEFAULT_RECONNECTION_DELAY_MS) / 1000.0)
+          delay = reconnection_delay_seconds(stream)
+          if Process.clock_gettime(Process::CLOCK_MONOTONIC) + delay > deadline
+            gave_up_waiting = true
+            break
+          end
+
+          sleep(delay)
           stream.reset_parser!
 
+          # Bound the resumed stream's idle time by what is left of the budget, rather than leaving it to
+          # whatever the Faraday adapter defaults to. `listen_for_server_requests` guards its own GET the same way;
+          # without this, a caller-supplied adapter with no default read timeout would let a server hold
+          # the connection open past the budget by simply sending nothing.
+          read_timeout = remaining_reconnection_budget(deadline)
+
           reconnect_response = begin
             client.get("") do |req|
               req.headers.update(session_headers)
               req.headers["Accept"] = SSE_ACCEPT_HEADER
               req.headers[LAST_EVENT_ID_HEADER] = stream.last_event_id if stream.last_event_id
+              req.options.read_timeout = read_timeout
               req.options.on_data = stream.on_data
             end
           rescue StreamAbort
@@ -932,9 +1202,14 @@ module MCP
           return stream.response if stream.response
         end
 
+        reason = if gave_up_waiting
+          "the reconnection delay it asked for would exceed the #{@max_reconnection_wait} second reconnection budget"
+        else
+          "#{MAX_RECONNECTION_ATTEMPTS} reconnection attempts"
+        end
+
         raise RequestHandlerError.new(
-          "Server closed the SSE stream without a response for #{method} " \
-            "after #{MAX_RECONNECTION_ATTEMPTS} reconnection attempts",
+          "Server closed the SSE stream without a response for #{method} after #{reason}",
           { method: method, params: params },
           error_type: :internal_error,
         )