mcp 0.23.0 → 0.24.0

data/lib/mcp/client/http.rb

@@ -8,16 +8,27 @@ require_relative "../version"
 
 module MCP
   class Client
-    # TODO: HTTP GET for SSE streaming is not yet implemented.
-    #   https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#listening-for-messages-from-the-server
-    # TODO: Resumability and redelivery with Last-Event-ID is not yet implemented.
-    #   https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#resumability-and-redelivery
     class HTTP
       ACCEPT_HEADER = "application/json, text/event-stream"
+      SSE_ACCEPT_HEADER = "text/event-stream"
       SESSION_ID_HEADER = "Mcp-Session-Id"
       PROTOCOL_VERSION_HEADER = "MCP-Protocol-Version"
       METHOD_HEADER = "Mcp-Method"
       NAME_HEADER = "Mcp-Name"
+      LAST_EVENT_ID_HEADER = "Last-Event-ID"
+
+      # SEP-1699 reconnection tuning: the SSE `retry:` field from the server takes precedence;
+      # this default applies when the server sent none. Both values match the Python SDK
+      # (`DEFAULT_RECONNECTION_DELAY_MS`, `MAX_RECONNECTION_ATTEMPTS`); the TypeScript SDK uses
+      # an exponential backoff that the `retry:` field likewise overrides.
+      DEFAULT_RECONNECTION_DELAY_MS = 1000
+      MAX_RECONNECTION_ATTEMPTS = 2
+
+      # 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
+      # (60 seconds for Net::HTTP) would recycle quiet streams too eagerly.
+      SSE_LISTENER_READ_TIMEOUT = 300
 
       # 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
@@ -54,6 +65,108 @@ module MCP
         end
       end
 
+      # Internal control-flow signal raised inside the streaming callback to stop reading
+      # an SSE stream once the awaited JSON-RPC response has arrived; servers may hold
+      # a stream open indefinitely (notably the standalone GET stream), so EOF cannot be relied on.
+      class StreamAbort < StandardError; end
+      private_constant :StreamAbort
+
+      # Per-exchange SSE state shared between the initial POST stream and any SEP-1699 reconnection GET streams:
+      # the incrementally parsed JSON-RPC response, the last received SSE event id (for `Last-Event-ID`),
+      # and the server's `retry:` reconnection delay. Non-SSE bodies accumulate in `buffer` for the JSON path.
+      class SSEStream
+        attr_reader :buffer, :response, :last_event_id, :retry_ms
+        attr_accessor :abortable
+
+        def initialize(abortable:, on_request: nil)
+          @abortable = abortable
+          @on_request = on_request
+          @buffer = +""
+          @parser = nil
+          @response = nil
+          @last_event_id = nil
+          @retry_ms = nil
+        end
+
+        # Whether the server sent a SEP-1699 priming event (any event carrying an id),
+        # which marks the stream as resumable after a graceful close.
+        def primed?
+          !@last_event_id.nil?
+        end
+
+        # Faraday `on_data` streaming callback. SSE chunks are parsed incrementally;
+        # anything else (JSON bodies) accumulates in `buffer`.
+        def on_data
+          proc do |chunk, _received_bytes, env|
+            if event_stream?(env)
+              feed(chunk)
+              raise StreamAbort if @abortable && @response
+            else
+              @buffer << chunk
+            end
+          end
+        end
+
+        # A fresh parser for a new HTTP connection (reconnection GET),
+        # so a partial line from the previous stream cannot corrupt the next one.
+        def reset_parser!
+          @parser = nil
+        end
+
+        # Parses an SSE body that was delivered outside the streaming callback:
+        # Faraday versions that do not pass `env` to `on_data` leave SSE chunks in `buffer`
+        # (consumed here so they are not parsed twice), and adapters without `on_data` support
+        # yield the whole body only via `fallback_body` (the Faraday `response.body`).
+        def ingest_pending!(fallback_body)
+          text = @buffer.empty? ? fallback_body : @buffer.slice!(0..-1)
+          feed(text) if text.is_a?(String) && !text.empty?
+        end
+
+        private
+
+        def event_stream?(env)
+          headers = env&.response_headers
+          content_type = headers && (headers["content-type"] || headers["Content-Type"])
+          !!content_type&.include?("text/event-stream")
+        end
+
+        def feed(chunk)
+          parser.feed(chunk) do |_type, data, id, reconnection_time|
+            @last_event_id = id if id && !id.empty?
+            @retry_ms = reconnection_time if reconnection_time
+            next if data.nil? || data.empty?
+
+            begin
+              parsed = JSON.parse(data)
+            rescue JSON::ParserError
+              next
+            end
+
+            next unless parsed.is_a?(Hash)
+
+            if parsed.key?("result") || parsed.key?("error")
+              @response ||= parsed
+            elsif parsed["method"] && parsed.key?("id")
+              # A server-to-client request (e.g. `elicitation/create`) delivered
+              # on the stream while the original request is still pending.
+              @on_request&.call(parsed)
+            end
+          end
+        end
+
+        def parser
+          @parser ||= begin
+            require "event_stream_parser"
+            EventStreamParser::Parser.new
+          rescue LoadError
+            raise LoadError, "The 'event_stream_parser' gem is required to parse SSE responses. " \
+              "Add it to your Gemfile: gem 'event_stream_parser', '>= 1.0'. " \
+              "See https://rubygems.org/gems/event_stream_parser for more details."
+          end
+        end
+      end
+      private_constant :SSEStream
+
       attr_reader :url, :session_id, :protocol_version, :server_info, :oauth
 
       def initialize(url:, headers: {}, oauth: nil, &block)
@@ -91,6 +204,24 @@ module MCP
         @protocol_version = nil
         @server_info = nil
         @connected = false
+        @server_request_handlers = {}
+        @listener_thread = nil
+      end
+
+      # Registers a handler for a server-to-client request (e.g. `elicitation/create`) delivered on an SSE stream.
+      # The handler receives the request's `params` (a Hash with string keys, possibly empty) and its return value is
+      # sent back to the server as the JSON-RPC `result`.
+      # The handler may raise `MCP::Client::ServerRequestError` to answer with a specific JSON-RPC error code.
+      # Requests for methods without a registered handler are answered with a JSON-RPC "method not found" (-32601) error.
+      # Registering a handler opens a standalone GET SSE listening stream (once connected), since servers send requests
+      # that are not tied to a client request on that stream - matching the TypeScript and Python SDK clients,
+      # which start listening after the `initialize` handshake.
+      # https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#listening-for-messages-from-the-server
+      def on_server_request(method, &handler)
+        raise ArgumentError, "A handler block is required" unless handler
+
+        @server_request_handlers[method.to_s] = handler
+        start_listening if connected?
       end
 
       # Performs the MCP `initialize` handshake: sends an `initialize` request
@@ -169,6 +300,7 @@ module MCP
         end
 
         @connected = true
+        start_listening if @server_request_handlers.any?
         @server_info
       end
 
@@ -199,11 +331,27 @@ module MCP
         step_up_retried = false
 
         begin
+          # The response is consumed incrementally so that an SSE stream the server holds open
+          # (or closes early per SEP-1699) can be handled; `initialize` streams are read to EOF
+          # so the response object (and its `Mcp-Session-Id` header) is always available for capture.
+          stream = SSEStream.new(
+            abortable: method.to_s != MCP::Methods::INITIALIZE,
+            on_request: ->(message) { dispatch_server_request(message) },
+          )
+
           yield if block_given?
-          response = client.post("", request, session_headers.merge(request_metadata_headers(method, params)))
-          body = parse_response_body(response, method, params)
 
-          capture_session_info(method, response, body)
+          response = begin
+            client.post("", request, session_headers.merge(request_metadata_headers(method, params))) do |req|
+              req.options.on_data = stream.on_data
+            end
+          rescue StreamAbort
+            nil
+          end
+
+          body = resolve_response_body(stream, response, method, params)
+
+          capture_session_info(method, response, body) if response
 
           body
         rescue Faraday::BadRequestError => e
@@ -522,12 +670,64 @@ module MCP
       end
 
       def clear_session
+        stop_listening
         @session_id = nil
         @protocol_version = nil
         @server_info = nil
         @connected = false
       end
 
+      # Opens the standalone GET SSE listening stream on a background thread so server-to-client requests
+      # can arrive while the main thread is blocked on its own request (e.g. a tools/call awaiting elicitation).
+      # Like the TypeScript and Python SDK clients, the GET is fired without waiting for it to be established.
+      def start_listening
+        return if @listener_thread&.alive?
+
+        @listener_thread = Thread.new { listen_for_server_requests }
+      end
+
+      def stop_listening
+        @listener_thread&.kill
+        @listener_thread = nil
+      end
+
+      # Reconnection semantics match the TypeScript and Python SDK clients: a stream that was established and
+      # then closed gracefully is retried indefinitely after the server's `retry:` interval (SSE semantics),
+      # while consecutive connection failures - HTTP errors and idle read timeouts both count - stop the listener
+      # once they reach `MAX_RECONNECTION_ATTEMPTS`; a successful stream in between resets the count.
+      # A 405 stops immediately without retrying, since it is the spec's answer from a server that offers no listening stream.
+      def listen_for_server_requests
+        stream = SSEStream.new(
+          abortable: false,
+          on_request: ->(message) { dispatch_server_request(message) },
+        )
+        consecutive_failures = 0
+
+        loop do
+          begin
+            client.get("") do |request|
+              request.headers.update(session_headers)
+              request.headers["Accept"] = SSE_ACCEPT_HEADER
+              request.headers[LAST_EVENT_ID_HEADER] = stream.last_event_id if stream.last_event_id
+              request.options.read_timeout = SSE_LISTENER_READ_TIMEOUT
+              request.options.on_data = stream.on_data
+            end
+
+            consecutive_failures = 0
+          rescue Faraday::Error => e
+            break if e.response&.dig(:status) == 405
+
+            consecutive_failures += 1
+
+            break if consecutive_failures >= MAX_RECONNECTION_ATTEMPTS
+          end
+
+          stream.reset_parser!
+
+          sleep((stream.retry_ms || DEFAULT_RECONNECTION_DELAY_MS) / 1000.0)
+        end
+      end
+
       def require_faraday!
         require "faraday"
       rescue LoadError
@@ -536,15 +736,11 @@ module MCP
           "See https://rubygems.org/gems/faraday for more details."
       end
 
-      def require_event_stream_parser!
-        require "event_stream_parser"
-      rescue LoadError
-        raise LoadError, "The 'event_stream_parser' gem is required to parse SSE responses. " \
-          "Add it to your Gemfile: gem 'event_stream_parser', '>= 1.0'. " \
-          "See https://rubygems.org/gems/event_stream_parser for more details."
-      end
+      # Determines the logical JSON-RPC body of the exchange after the POST stream finished
+      # (or was aborted because the response already arrived).
+      def resolve_response_body(stream, response, method, params)
+        return stream.response if stream.response
 
-      def parse_response_body(response, method, params)
         # 202 Accepted is the server's ACK for a JSON-RPC notification or response; no body is expected.
         # https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#sending-messages-to-the-server
         return if response.status == 202
@@ -552,9 +748,29 @@ module MCP
         content_type = response.headers["Content-Type"]
 
         if content_type&.include?("text/event-stream")
-          parse_sse_response(response.body, method, params)
+          # Nothing was parsed during streaming: either the adapter does not support `on_data`
+          # (the whole body sits in `response.body`) or Faraday did not pass `env` to `on_data`
+          # (Faraday < 2.1; the SSE chunks sit in `buffer`). Parse whichever holds the body.
+          unless stream.primed?
+            stream.ingest_pending!(response.body)
+            return stream.response if stream.response
+          end
+
+          # SEP-1699: a graceful close after a priming event (an event with an id) but before
+          # the response means "reconnect via GET to resume".
+          return await_response_after_disconnect(stream, method, params) if stream.primed?
+
+          raise RequestHandlerError.new(
+            "No valid JSON-RPC response found in SSE stream",
+            { method: method, params: params },
+            error_type: :parse_error,
+          )
         elsif content_type&.include?("application/json")
-          response.body
+          return parse_json_buffer(stream.buffer, method, params) unless stream.buffer.empty?
+
+          # Adapters without `on_data` support deliver the body via `response.body`,
+          # already parsed by the json response middleware.
+          response.body.is_a?(String) ? parse_json_buffer(response.body, method, params) : response.body
         else
           raise RequestHandlerError.new(
             "Unsupported Content-Type: #{content_type.inspect}. Expected application/json or text/event-stream.",
@@ -564,30 +780,109 @@ module MCP
         end
       end
 
-      def parse_sse_response(body, method, params)
-        require_event_stream_parser!
-
-        json_rpc_response = nil
-        parser = EventStreamParser::Parser.new
-        parser.feed(body.to_s) do |_type, data, _id|
-          next if data.empty?
-
+      # Answers a server-to-client request received on an SSE stream by invoking the handler registered via
+      # `on_server_request` and POSTing its return value back as a JSON-RPC response; the server ACKs with
+      # 202 Accepted. Requests without a registered handler are answered with a "method not found" error.
+      # A handler may raise `ServerRequestError` to answer with a specific JSON-RPC error code
+      # (e.g. `-1` for a rejected sampling request); any other error is answered with an "internal error".
+      # In every case the server is not left waiting, matching how the TypeScript and Python SDKs convert handler
+      # failures into JSON-RPC error responses.
+      def dispatch_server_request(message)
+        handler = @server_request_handlers[message["method"]]
+        response = if handler
           begin
-            parsed = JSON.parse(data)
-            json_rpc_response = parsed if parsed.is_a?(Hash) && (parsed.key?("result") || parsed.key?("error"))
-          rescue JSON::ParserError
-            next
+            {
+              jsonrpc: JsonRpcHandler::Version::V2_0,
+              id: message["id"],
+              result: handler.call(message["params"] || {}),
+            }
+          rescue ServerRequestError => e
+            {
+              jsonrpc: JsonRpcHandler::Version::V2_0,
+              id: message["id"],
+              error: { code: e.code, message: e.message },
+            }
+          rescue StandardError => e
+            {
+              jsonrpc: JsonRpcHandler::Version::V2_0,
+              id: message["id"],
+              error: {
+                code: JsonRpcHandler::ErrorCode::INTERNAL_ERROR,
+                message: "Internal error handling #{message["method"]} request: #{e.message}",
+              },
+            }
           end
+        else
+          {
+            jsonrpc: JsonRpcHandler::Version::V2_0,
+            id: message["id"],
+            error: {
+              code: JsonRpcHandler::ErrorCode::METHOD_NOT_FOUND,
+              message: "Method not found: #{message["method"]}",
+            },
+          }
         end
 
-        return json_rpc_response if json_rpc_response
+        send_client_response(response)
+      end
+
+      def send_client_response(response)
+        client.post("", response, session_headers)
+      end
+
+      def parse_json_buffer(buffer, method, params)
+        return if buffer.empty?
 
+        JSON.parse(buffer)
+      rescue JSON::ParserError => e
         raise RequestHandlerError.new(
-          "No valid JSON-RPC response found in SSE stream",
+          "Failed to parse JSON response: #{e.message}",
           { method: method, params: params },
           error_type: :parse_error,
         )
       end
+
+      # 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
+      # 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).
+      # https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1699
+      def await_response_after_disconnect(stream, method, params)
+        stream.abortable = true
+
+        MAX_RECONNECTION_ATTEMPTS.times do
+          sleep((stream.retry_ms || DEFAULT_RECONNECTION_DELAY_MS) / 1000.0)
+          stream.reset_parser!
+
+          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.on_data = stream.on_data
+            end
+          rescue StreamAbort
+            # The awaited response arrived on the reconnected stream.
+            nil
+          end
+
+          # Same fallback as `resolve_response_body` for adapters that do not stream via `on_data`.
+          if reconnect_response && stream.response.nil?
+            stream.ingest_pending!(reconnect_response.body)
+          end
+
+          return stream.response if stream.response
+        end
+
+        raise RequestHandlerError.new(
+          "Server closed the SSE stream without a response for #{method} " \
+            "after #{MAX_RECONNECTION_ATTEMPTS} reconnection attempts",
+          { method: method, params: params },
+          error_type: :internal_error,
+        )
+      end
     end
   end
 end

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

@@ -15,14 +15,26 @@ module MCP
       # Required keyword arguments:
       #
       # - `client_id`     - String identifying the pre-registered confidential client.
-      # - `client_secret` - String shared secret. The `client_credentials` grant
-      #   is for confidential clients, so a credential is mandatory.
+      # - `client_secret` - String shared secret for the `client_secret_basic` /
+      #   `client_secret_post` methods. The `client_credentials` grant is for
+      #   confidential clients, so a credential is mandatory; with
+      #   `private_key_jwt` the credential is the `private_key` instead.
       #
       # Optional keyword arguments:
       #
-      # - `token_endpoint_auth_method` - `"client_secret_basic"` (default) or
-      #   `"client_secret_post"`. `"none"` is rejected: an unauthenticated
+      # - `token_endpoint_auth_method` - `"client_secret_basic"` (default),
+      #   `"client_secret_post"`, or `"private_key_jwt"` (RFC 7523 JWT client
+      #   assertion, per the `io.modelcontextprotocol/oauth-client-credentials`
+      #   extension / SEP-1046). `"none"` is rejected: an unauthenticated
       #   `client_credentials` request is meaningless.
+      # - `private_key` - PEM string (or `OpenSSL::PKey::PKey`) used to sign
+      #   the JWT client assertion. Required with `private_key_jwt`.
+      #   The key is held on the provider and never written to `storage`.
+      # - `signing_algorithm` - `"ES256"` or `"RS256"`. Required with
+      #   `private_key_jwt`; there is no default, so a mismatch with
+      #   the server's `token_endpoint_auth_signing_alg_values_supported` fails
+      #   loudly at construction instead of as a 401 (the TypeScript and Python SDKs
+      #   also take the algorithm as an explicit option).
       # - `scope`   - String of space-separated scopes to request when the server's
       #   `WWW-Authenticate` and the Protected Resource Metadata do not specify one.
       # - `storage` - Object responding to `tokens`, `save_tokens(tokens)`,
@@ -37,14 +49,16 @@ module MCP
         # missing or the requested client authentication method cannot carry them.
         class InvalidCredentialsError < ArgumentError; end
 
-        SUPPORTED_AUTH_METHODS = ["client_secret_basic", "client_secret_post"].freeze
+        SUPPORTED_AUTH_METHODS = ["client_secret_basic", "client_secret_post", "private_key_jwt"].freeze
 
         attr_reader :scope, :storage
 
         def initialize(
           client_id:,
-          client_secret:,
+          client_secret: nil,
           token_endpoint_auth_method: "client_secret_basic",
+          private_key: nil,
+          signing_algorithm: nil,
           scope: nil,
           storage: nil
         )
@@ -59,18 +73,37 @@ module MCP
                 "client_credentials request is not allowed."
           end
 
-          if blank?(client_secret)
-            raise InvalidCredentialsError,
-              "client_secret is required for the client_credentials grant with #{token_endpoint_auth_method}."
+          client_information = { "client_id" => client_id, "token_endpoint_auth_method" => token_endpoint_auth_method }
+
+          if token_endpoint_auth_method == "private_key_jwt"
+            validate_private_key_jwt_arguments!(
+              client_secret: client_secret,
+              private_key: private_key,
+              signing_algorithm: signing_algorithm,
+            )
+
+            # Fail fast on an unparseable key or a key/algorithm mismatch by
+            # signing a throwaway assertion now rather than at token time.
+            JWTClientAssertion.generate(
+              client_id: client_id,
+              audience: "urn:mcp:credential-validation",
+              private_key: private_key,
+              signing_algorithm: signing_algorithm,
+            )
+          else
+            if blank?(client_secret)
+              raise InvalidCredentialsError, "client_secret is required for the client_credentials grant with #{token_endpoint_auth_method}."
+            end
+
+            client_information["client_secret"] = client_secret
           end
 
+          @client_id = client_id
+          @private_key = private_key
+          @signing_algorithm = signing_algorithm
           @scope = scope
           @storage = storage || InMemoryStorage.new
-          @storage.save_client_information(
-            "client_id" => client_id,
-            "client_secret" => client_secret,
-            "token_endpoint_auth_method" => token_endpoint_auth_method,
-          )
+          @storage.save_client_information(client_information)
         end
 
         # See `Provider#authorization_flow`.
@@ -78,8 +111,33 @@ module MCP
           :client_credentials
         end
 
+        # Returns a freshly signed RFC 7523 JWT client assertion for the `private_key_jwt` method.
+        # `audience` is the authorization server's issuer identifier. Called by `Flow#post_to_token_endpoint`.
+        def client_assertion(audience:)
+          JWTClientAssertion.generate(
+            client_id: @client_id,
+            audience: audience,
+            private_key: @private_key,
+            signing_algorithm: @signing_algorithm,
+          )
+        end
+
         private
 
+        def validate_private_key_jwt_arguments!(client_secret:, private_key:, signing_algorithm:)
+          unless client_secret.nil?
+            raise InvalidCredentialsError, "client_secret must not be set with private_key_jwt; the private key is the credential."
+          end
+
+          if private_key.nil?
+            raise InvalidCredentialsError, "private_key is required for the client_credentials grant with private_key_jwt."
+          end
+
+          return unless blank?(signing_algorithm)
+
+          raise InvalidCredentialsError, "signing_algorithm is required with private_key_jwt (one of #{JWTClientAssertion::SUPPORTED_ALGORITHMS.inspect})."
+        end
+
         def blank?(value)
           value.nil? || (value.is_a?(String) && value.strip.empty?)
         end