ruby-mcp-client 2.1.0 → 3.0.0

data/lib/mcp_client/server_sse/json_rpc_transport.rb

@@ -11,6 +11,14 @@ module MCPClient
       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
@@ -22,20 +30,31 @@ module MCPClient
       def rpc_request(method, params = {}, timeout: nil)
         ensure_initialized
 
-        with_retry(method) 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
@@ -89,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
@@ -122,6 +149,10 @@ 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)
+        # 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
@@ -130,14 +161,23 @@ module MCPClient
         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: #{describe_parse_error(e)}"
@@ -167,6 +207,7 @@ module MCPClient
         @mutex.synchronize do
           @pending_request_ids.delete(request_id)
           @sse_results.delete(request_id)
+          @sse_result_arrivals&.delete(request_id)
         end
       end
 
@@ -177,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)
 
@@ -187,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
@@ -231,8 +284,14 @@ 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 += " (#{describe_body_size(response.body)})" if response.respond_to?(:body)
@@ -276,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,
@@ -294,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

data/lib/mcp_client/server_sse/sse_parser.rb

@@ -12,7 +12,8 @@ module MCPClient
 
       # 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?
 
@@ -22,23 +23,27 @@ 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
@@ -85,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.
@@ -110,14 +133,24 @@ module MCPClient
             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