ruby-mcp-client 2.0.0 → 3.0.0

data/lib/mcp_client/server_sse/json_rpc_transport.rb

@@ -2,12 +2,23 @@
 
 require_relative '../json_rpc_common'
 
+require_relative 'origin_policy'
+
 module MCPClient
   class ServerSSE
     # JSON-RPC request/notification plumbing for SSE transport
     module JsonRpcTransport
+      include OriginPolicy
       include JsonRpcCommon
 
+      # Returned by #check_for_result when nothing has arrived for the
+      # request yet. The stored result is whatever `result` member the
+      # response carried, so `null` and `false` are answers the client must
+      # deliver (and validate) rather than truthiness the waiter can read as
+      # "still outstanding" — doing that waited out the whole read timeout
+      # and cancelled a request the server had already answered.
+      NO_RESULT = Object.new.freeze
+
       # Generic JSON-RPC request: send method with params and return result
       # @param method [String] JSON-RPC method name
       # @param params [Hash] parameters for the request
@@ -19,20 +30,31 @@ module MCPClient
       def rpc_request(method, params = {}, timeout: nil)
         ensure_initialized
 
-        with_retry do
-          request_id = @mutex.synchronize { @request_id += 1 }
-          request = build_jsonrpc_request(method, params, request_id)
-          begin
-            send_jsonrpc_request(request, timeout: timeout)
-          rescue MCPClient::Errors::RequestTimeoutError
-            # MCP lifecycle: on timeout the sender SHOULD issue a cancellation
-            # notification for the abandoned request and stop waiting.
-            send_cancellation_notification(request_id) if cancellable_request?(method, params)
-            raise
-          end
+        # The multi round-trip resolver sits outside the per-attempt retry, so
+        # a retry carrying inputResponses/requestState keeps them through
+        # transport retries — the same shape as the other transports, so an
+        # input_required answer is validated and fulfilled here as well.
+        resolve_input_round_trips(method, params, timeout) do |attempt_params|
+          with_retry(method) { send_one_request(method, attempt_params, timeout) }
         end
       end
 
+      # One request on the wire: build it, send it and wait for its answer.
+      # @param method [String] JSON-RPC method
+      # @param params [Hash] the params of this attempt
+      # @param timeout [Numeric, nil] per-request timeout
+      # @return [Object] the result
+      def send_one_request(method, params, timeout)
+        request_id = @mutex.synchronize { @request_id += 1 }
+        request = build_jsonrpc_request(method, params, request_id)
+        send_jsonrpc_request(request, timeout: timeout)
+      rescue MCPClient::Errors::RequestTimeoutError
+        # MCP lifecycle: on timeout the sender SHOULD issue a cancellation
+        # notification for the abandoned request and stop waiting.
+        send_cancellation_notification(request_id) if request_id && cancellable_request?(method, params)
+        raise
+      end
+
       # Best-effort notifications/cancelled for a request the client stopped
       # waiting on. Failures are swallowed.
       # @param request_id [Integer] id of the abandoned request
@@ -86,7 +108,15 @@ module MCPClient
         request_id = @mutex.synchronize { @request_id += 1 }
         json_rpc_request = build_jsonrpc_request('initialize', initialization_params, request_id)
         @logger.debug("Performing initialize RPC: #{json_rpc_request}")
-        result = send_jsonrpc_request(json_rpc_request)
+        begin
+          result = send_jsonrpc_request(json_rpc_request)
+        rescue MCPClient::Errors::UnsupportedProtocolVersionError => e
+          # As on the HTTP transports: the versions a modern-only server
+          # names in `data` are the diagnostic a legacy configuration needs,
+          # so they are spelled out rather than dropped by connect's wrap.
+          raise MCPClient::Errors::ConnectionError,
+                "Initialize failed: #{e.message} (server supports: #{e.supported.join(', ')})"
+        end
         unless result.is_a?(Hash)
           # A non-object initialize result means the handshake did not succeed.
           # Continuing would enter the Operation phase without ever sending the
@@ -119,26 +149,65 @@ module MCPClient
       # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
       # @raise [MCPClient::Errors::ToolCallError] for other errors during request execution
       def send_jsonrpc_request(request, timeout: nil)
-        @logger.debug("Sending JSON-RPC request: #{request.to_json}")
+        # As late as a request pinned to a session can be held back: every
+        # reconnect on the way here (ensure_initialized, a retry after the
+        # stream dropped) has happened by now.
+        check_session_pin!
+        @logger.debug("Sending JSON-RPC request: #{describe_jsonrpc_message(request)}")
         record_activity
+        # Register the id BEFORE posting: the SSE stream may deliver the
+        # response before the POST returns, and only responses to registered
+        # (outstanding) requests are accepted into @sse_results.
+        register_pending_request(request['id'])
 
         begin
+          clear_response_received_at if respond_to?(:clear_response_received_at, true)
           response = post_json_rpc_request(request)
 
           if @use_sse
+            # Dated by check_for_result from the stream's arrival time.
             wait_for_sse_result(request, timeout: timeout)
           else
+            # Dated from receipt, before the body is decoded.
+            note_response_received_at if respond_to?(:note_response_received_at, true)
             parse_direct_response(response)
           end
-        rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+        # A pre-write refusal keeps its type: the late pin check inside the
+        # POST turns a request down (or the caller's own guard does, see
+        # {MCPClient::SessionPin#guarded_writes}) and nothing was written,
+        # which is not an error of executing the request.
+        rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError,
+               MCPClient::Errors::ServerError, MCPClient::Errors::TaskReplacedError
           raise
         rescue JSON::ParserError => e
-          raise MCPClient::Errors::TransportError, "Invalid JSON response from server: #{e.message}"
+          raise MCPClient::Errors::TransportError, "Invalid JSON response from server: #{describe_parse_error(e)}"
         rescue Errno::ECONNREFUSED => e
           raise MCPClient::Errors::ConnectionError, "Server connection lost: #{e.message}"
         rescue StandardError => e
           method_name = request['method']
           raise MCPClient::Errors::ToolCallError, "Error executing request '#{method_name}': #{e.message}"
+        ensure
+          unregister_pending_request(request['id'])
+        end
+      end
+
+      # Mark a request id as awaiting its response.
+      # @param request_id [Integer, String] id of the outgoing request
+      # @return [void]
+      def register_pending_request(request_id)
+        @mutex.synchronize { @pending_request_ids.add(request_id) }
+      end
+
+      # Stop accepting responses for a request id (completed, failed or timed
+      # out) and drop any result that was never consumed — a late or duplicate
+      # response must not accumulate in @sse_results.
+      # @param request_id [Integer, String] id of the finished request
+      # @return [void]
+      def unregister_pending_request(request_id)
+        @mutex.synchronize do
+          @pending_request_ids.delete(request_id)
+          @sse_results.delete(request_id)
+          @sse_result_arrivals&.delete(request_id)
         end
       end
 
@@ -149,7 +218,15 @@ module MCPClient
       def post_json_rpc_request(request)
         uri = URI.parse(@base_url)
         base = "#{uri.scheme}://#{uri.host}:#{uri.port}"
-        rpc_ep = @mutex.synchronize { @rpc_endpoint }
+        # The endpoint this request goes to, and the pin checked in the same
+        # critical section: a reconnect completing between the check in
+        # #send_jsonrpc_request and this capture would otherwise post a
+        # request of the ended session to the session that replaced it
+        # (cleanup bumps the epoch before it takes this monitor).
+        rpc_ep = @mutex.synchronize do
+          check_session_pin!
+          @rpc_endpoint
+        end
 
         @rpc_conn ||= create_json_rpc_connection(base)
 
@@ -159,9 +236,13 @@ module MCPClient
 
           unless response.success?
             # 5xx failures are plausibly transient (retryable); 4xx and other
-            # statuses are deterministic and raise a plain (non-retryable) error.
-            error_class = (500..599).cover?(response.status) ? MCPClient::Errors::TransientServerError : MCPClient::Errors::ServerError
-            raise error_class, "Server returned error: #{response.status} #{response.reason_phrase}"
+            # statuses are deterministic and raise a plain (non-retryable)
+            # error — typed when the body carries a JSON-RPC error (MCP
+            # 2026-07-28 protocol errors ride in 400/404 bodies).
+            message = "Server returned error: #{response.status} #{response.reason_phrase}"
+            raise MCPClient::Errors::TransientServerError, message if (500..599).cover?(response.status)
+
+            raise jsonrpc_error_from_http_response(response, message)
           end
 
           response
@@ -178,7 +259,7 @@ module MCPClient
       def create_json_rpc_connection(base_url)
         Faraday.new(url: base_url) do |f|
           f.request :retry, max: @max_retries, interval: @retry_backoff, backoff_factor: 2
-          f.response :follow_redirects, limit: 3
+          f.response :follow_redirects, limit: 3, callback: method(:reject_cross_origin_redirect!)
           f.options.open_timeout = @read_timeout
           f.options.timeout = @read_timeout
           f.adapter Faraday.default_adapter
@@ -203,11 +284,17 @@ module MCPClient
             h.delete('Accept')
             h.delete('Cache-Control')
           end).each { |k, v| req.headers[k] = v }
+          # MCP 2026-07-28 caching: the result is bound to the credentials
+          # this very request carries.
+          if respond_to?(:note_request_authorization, true)
+            note_request_authorization(authorization_header_value(req.headers))
+          end
           req.body = request.to_json
         end
+        note_sent_authorization(response) if respond_to?(:note_sent_authorization, true)
 
         msg = "Received JSON-RPC response: #{response.status}"
-        msg += " #{response.body}" if response.respond_to?(:body)
+        msg += " (#{describe_body_size(response.body)})" if response.respond_to?(:body)
         @logger.debug(msg)
         response
       end
@@ -248,7 +335,7 @@ module MCPClient
       def wait_for_result_with_timeout(request_id, start_time, timeout)
         loop do
           result = check_for_result(request_id)
-          return result if result
+          return result unless result.equal?(NO_RESULT)
 
           unless connection_active?
             raise MCPClient::Errors::ConnectionError,
@@ -266,35 +353,64 @@ module MCPClient
 
       # Check if a result is available for the given request ID
       # @param request_id [Integer] the request ID to check
-      # @return [Hash, nil] the result if available, nil otherwise
+      # @return [Object] the result if one has arrived, NO_RESULT otherwise
       # @raise [MCPClient::Errors::ServerError] if the stored result is a JSON-RPC error response
       def check_for_result(request_id)
+        arrived = false
         result = nil
+        arrival = nil
         @mutex.synchronize do
-          result = @sse_results.delete(request_id) if @sse_results.key?(request_id)
+          if @sse_results.key?(request_id)
+            arrived = true
+            result = @sse_results.delete(request_id)
+          end
+          arrival = @sse_result_arrivals&.delete(request_id)
         end
+        return NO_RESULT unless arrived
 
-        if result
+        if arrived
           record_activity
+          note_response_received_at(arrival || monotonic_now) if respond_to?(:note_response_received_at, true)
           # SseParser#process_response? stores JSON-RPC error responses under
           # the Symbol :error key; deliver them to the caller as ServerError
           # (MCP lifecycle "Error Handling") instead of timing out.
           raise_sse_error_response(result[:error]) if result.is_a?(Hash) && result.key?(:error)
+          # …and an envelope that carried neither member under :no_answer.
+          if result.is_a?(Hash) && result[:no_answer]
+            raise MCPClient::Errors::InvalidResultError,
+                  "Invalid result: the response to request #{request_id} carried neither a result nor an error member"
+          end
+          # Same resultType invariant as process_jsonrpc_response on the
+          # other transports: an unrecognized value is an invalid response.
+          validate_result_type!(result)
           return result
         end
 
         nil
       end
 
+      # The legacy HTTP+SSE transport never negotiates a modern revision, so
+      # subscriptions/listen (which requires one) is refused by the shared
+      # implementation after this readiness check.
+      # @return [void]
+      def ensure_session_ready
+        ensure_connected if respond_to?(:ensure_connected, true)
+      end
+
+      # @param _subscription [MCPClient::Subscription]
+      # @return [void]
+      def cancel_subscription(_subscription)
+        nil
+      end
+
       # Raise a ServerError for a JSON-RPC error response received over SSE,
       # mirroring JsonRpcCommon#process_jsonrpc_response for the other transports.
       # @param error [Hash, nil] the JSON-RPC error object ('code', 'message', 'data')
       # @raise [MCPClient::Errors::ServerError] always
       def raise_sse_error_response(error)
-        error ||= {}
-        message = error['message'] || 'Unknown server error'
-        message = "#{message} (code #{error['code']})" if error['code']
-        raise MCPClient::Errors::ServerError, message
+        typed = MCPClient::Errors::ServerError.from_jsonrpc(error)
+        message = typed.code ? "#{typed.message} (code #{typed.code})" : typed.message
+        raise typed.class.new(message, code: typed.code, data: typed.data)
       end
 
       # Parse a direct (non-SSE) JSON-RPC response
@@ -306,7 +422,7 @@ module MCPClient
         data = JSON.parse(response.body)
         process_jsonrpc_response(data)
       rescue JSON::ParserError => e
-        raise MCPClient::Errors::TransportError, "Invalid JSON response from server: #{e.message}"
+        raise MCPClient::Errors::TransportError, "Invalid JSON response from server: #{describe_parse_error(e)}"
       end
     end
   end

data/lib/mcp_client/server_sse/origin_policy.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module MCPClient
+  class ServerSSE
+    # Origin pinning for the legacy HTTP+SSE transport.
+    #
+    # Everything this transport sends carries the caller's configured headers
+    # (Authorization, API keys, cookies), and callback responses carry
+    # roots/sampling/elicitation data, so no request may leave the origin the
+    # caller connected to — neither by a server-chosen endpoint URI nor by a
+    # redirect.
+    module OriginPolicy
+      # @param base [URI::Generic] the SSE connection URL
+      # @param other [URI::Generic] the URL to compare
+      # @return [Boolean] whether both share scheme, host and port
+      def same_origin?(base, other)
+        base.scheme == other.scheme &&
+          base.host&.downcase == other.host&.downcase &&
+          base.port == other.port
+      end
+
+      # @param uri [URI::Generic]
+      # @return [String] scheme://host:port of the URI
+      def origin_of(uri)
+        "#{uri.scheme}://#{uri.host}:#{uri.port}"
+      end
+
+      # Refuse to follow a redirect that leaves the SSE connection's origin.
+      #
+      # Pinning the endpoint event's origin is not sufficient on its own: a
+      # same-origin endpoint can answer a POST with a 307/308 to another
+      # origin, and faraday-follow_redirects replays the request there. It
+      # strips only the literal Authorization header, so configured API-key
+      # and other custom headers — plus the JSON-RPC body — would still reach
+      # the foreign origin.
+      #
+      # Raises ConnectionError rather than TransportError because the server
+      # has already received the original request; with_retry must not re-send
+      # it.
+      # @param _old_env [Faraday::Env] the redirecting response environment
+      # @param new_env [Faraday::Env] environment of the request about to be replayed
+      # @return [void]
+      # @raise [MCPClient::Errors::ConnectionError] if the redirect changes origin
+      def reject_cross_origin_redirect!(_old_env, new_env)
+        base = URI.parse(@base_url)
+        target = new_env.url
+        return if same_origin?(base, target)
+
+        message = "Refusing cross-origin redirect from #{origin_of(base)} to #{origin_of(target)}"
+        @logger.error(message)
+        raise MCPClient::Errors::ConnectionError, message
+      end
+    end
+  end
+end

data/lib/mcp_client/server_sse/reconnect_monitor.rb

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
 
+require_relative 'origin_policy'
+
 module MCPClient
   class ServerSSE
     # Extracted module for back-off, ping, and reconnection logic
     module ReconnectMonitor
+      include OriginPolicy
+
       # Start an activity monitor thread to maintain the connection
       # @return [void]
       def start_activity_monitor
@@ -202,7 +206,9 @@ module MCPClient
           f.options.open_timeout = 10
           f.options.timeout = nil
           f.request :retry, max: @max_retries, interval: @retry_backoff, backoff_factor: 2
-          f.response :follow_redirects, limit: 3
+          # Same origin pinning as the RPC connection: the SSE stream carries
+          # the configured credential headers too.
+          f.response :follow_redirects, limit: 3, callback: method(:reject_cross_origin_redirect!)
           f.adapter Faraday.default_adapter
         end
 

data/lib/mcp_client/server_sse/sse_parser.rb

@@ -2,14 +2,18 @@
 
 require 'json'
 require 'uri'
+require_relative 'origin_policy'
 
 module MCPClient
   class ServerSSE
     # === Wire-level SSE parsing & dispatch ===
     module SseParser
+      include OriginPolicy
+
       # Parse and handle a raw SSE event payload.
       # @param event_data [String] the raw event chunk
-      def parse_and_handle_sse_event(event_data)
+      # @param arrived [Float, nil] monotonic time the chunk carrying it arrived
+      def parse_and_handle_sse_event(event_data, arrived = nil)
         event = parse_sse_event(event_data)
         return if event.nil?
 
@@ -19,27 +23,31 @@ module MCPClient
         when 'ping'
           # no-op
         when 'message'
-          handle_message_event(event)
+          handle_message_event(event, arrived)
         end
       end
 
       # Handle a "message" SSE event (payload is JSON-RPC over SSE)
       # @param event [Hash] the parsed SSE event (with :data, :id, etc)
-      def handle_message_event(event)
+      # @param arrived [Float, nil] monotonic time the chunk carrying it arrived
+      def handle_message_event(event, arrived = nil)
         return if event[:data].empty?
 
         begin
+          # Dated from the arrival of the chunk it came in, before any event
+          # of that chunk was decoded or dispatched.
+          arrived ||= monotonic_now if respond_to?(:monotonic_now, true)
           data = JSON.parse(event[:data])
 
           return if process_error_in_message?(data)
           return if process_server_request?(data)
           return if process_notification?(data)
 
-          process_response?(data)
+          process_response?(data, arrived)
         rescue MCPClient::Errors::ConnectionError
           raise
         rescue JSON::ParserError => e
-          @logger.warn("Failed to parse JSON from event data: #{e.message}")
+          @logger.warn("Failed to parse JSON from event data: #{describe_parse_error(e, event[:data])}")
         rescue StandardError => e
           @logger.error("Error processing SSE event: #{e.message}")
         end
@@ -82,14 +90,32 @@ module MCPClient
       def process_notification?(data)
         return false unless data['method'] && !data.key?('id')
 
+        # notifications/message is the Logging utility, Deprecated as a whole
+        # in 2026-07-28 (SEP-2577). The notice belongs to the transport, not
+        # to MCPClient::Client: a host that registered on_notification on a
+        # ServerSSE receives log messages without a Client ever existing. It
+        # is raised here rather than only in
+        # {MCPClient::SubscriptionSupport#route_notification} because this
+        # transport is the one that does not go through it — see below.
+        warn_logging_deprecated if data['method'] == 'notifications/message'
+        # The legacy SSE transport carries no subscriptions/listen stream, so
+        # there is no delivery to run ahead of — but the transport's own caches
+        # and a host that registered its invalidation on the dedicated hook
+        # must still be told, in the order routing uses them
+        # (see {MCPClient::ServerBase#on_cache_invalidation}).
+        invalidate_cache_for_notification(data['method'], data['params']) if respond_to?(
+          :invalidate_cache_for_notification, true
+        )
+        notify_cache_invalidation(data['method'], data['params'])
         @notification_callback&.call(data['method'], data['params'])
         true
       end
 
       # Process a JSON-RPC response (id => response)
       # @param data [Hash] the parsed JSON payload
+      # @param arrived [Float, nil] monotonic time the event arrived
       # @return [Boolean] true if we saw & handled a response
-      def process_response?(data)
+      def process_response?(data, arrived = nil)
         return false unless data['id']
 
         # Deliver the response to the waiting caller via @sse_results only.
@@ -98,14 +124,33 @@ module MCPClient
         # paginated list. Writing each page as it arrives would let a concurrent
         # list_tools observe a partial (page-1-only) cache mid-pagination.
         @mutex.synchronize do
+          # The stream is peer-controlled: only ids some caller is actually
+          # waiting on are stored. Without this check a server could stream
+          # unsolicited responses with fresh ids and grow @sse_results without
+          # bound for the lifetime of the client.
+          unless @pending_request_ids.include?(data['id'])
+            @logger.debug("Discarding unsolicited response id #{data['id'].inspect}")
+            return true
+          end
+
+          # Dated from arrival: the waiter polls and may wake much later.
+          (@sse_result_arrivals ||= {})[data['id']] = arrived || monotonic_now if respond_to?(:monotonic_now, true)
           @sse_results[data['id']] =
             if data['error']
               # JSON-RPC error response: store the error under a Symbol key
               # (JSON.parse only produces String keys, so this cannot collide
               # with a success result) for the waiter to raise ServerError.
               { error: data['error'] }
-            else
+            elsif data.key?('result')
+              # An explicit null (or false) result is an answer; only the
+              # member's presence decides that.
               data['result']
+            else
+              # JSON-RPC 2.0 section 5: "Either the result member or error
+              # member MUST be included". An envelope carrying neither answers
+              # nothing, and reading its absent result as a delivered nil
+              # would turn a malformed response into a successful call.
+              { no_answer: true }
             end
         end
 
@@ -156,20 +201,39 @@ module MCPClient
         end
       end
 
-      # Resolve an endpoint URI reference against the SSE connection URL
+      # Resolve an endpoint URI reference against the SSE connection URL.
+      # The resolved endpoint MUST stay on the SSE connection's origin: the
+      # event payload is server-controlled input, and honoring a cross-origin
+      # target would redirect every JSON-RPC POST — including the configured
+      # Authorization/API-key headers and callback response bodies — to a
+      # server the caller never chose.
       # @param data [String] the endpoint event payload (absolute or relative URI)
       # @return [String] the absolute endpoint URL
       def resolve_endpoint_uri(data)
-        URI.join(@base_url, data).to_s
+        endpoint = URI.join(@base_url, data)
+        base = URI.parse(@base_url)
+        unless same_origin?(base, endpoint)
+          fail_endpoint_handshake!(
+            "Cross-origin endpoint in SSE endpoint event: #{data.inspect} " \
+            "does not match the connection origin #{origin_of(base)}"
+          )
+        end
+        endpoint.to_s
       rescue URI::Error => e
         # The endpoint event is the handshake's core payload; an unresolvable
         # URI must fail the handshake rather than deferring a broken POST
         # target to the first request.
         @logger.error("Failed to resolve endpoint URI #{data.inspect} against #{@base_url}: #{e.message}")
-        message = "Invalid endpoint URI in SSE endpoint event: #{data.inspect} (#{e.message})"
-        # The SSE worker thread swallows this exception with a generic rescue,
-        # so also record the failure cause (mirroring @auth_error) for the
-        # connect caller blocked in wait_for_connection to surface promptly.
+        fail_endpoint_handshake!("Invalid endpoint URI in SSE endpoint event: #{data.inspect} (#{e.message})")
+      end
+
+      # Record the handshake failure cause and raise. The SSE worker thread
+      # swallows this exception with a generic rescue, so also record the
+      # failure (mirroring @auth_error) for the connect caller blocked in
+      # wait_for_connection to surface promptly.
+      # @param message [String] the failure description
+      # @raise [MCPClient::Errors::TransportError] always
+      def fail_endpoint_handshake!(message)
         @mutex.synchronize do
           @connection_error = message
           @connection_established = false