ruby-mcp-client 1.1.0 → 2.1.0

data/lib/mcp_client/server_sse/json_rpc_transport.rb

@@ -2,10 +2,13 @@
 
 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
 
       # Generic JSON-RPC request: send method with params and return result
@@ -16,16 +19,35 @@ module MCPClient
       # @raise [MCPClient::Errors::ServerError] if server returns an error
       # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
       # @raise [MCPClient::Errors::ToolCallError] for other errors during request execution
-      def rpc_request(method, params = {})
+      def rpc_request(method, params = {}, timeout: nil)
         ensure_initialized
 
-        with_retry do
+        with_retry(method) do
           request_id = @mutex.synchronize { @request_id += 1 }
           request = build_jsonrpc_request(method, params, request_id)
-          send_jsonrpc_request(request)
+          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
         end
       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
+      # @return [void]
+      def send_cancellation_notification(request_id)
+        notif = build_jsonrpc_notification('notifications/cancelled',
+                                           { 'requestId' => request_id, 'reason' => 'Request timed out' })
+        post_json_rpc_request(notif)
+      rescue StandardError => e
+        @logger.debug("Failed to send cancellation notification: #{e.message}")
+      end
+
       # Send a JSON-RPC notification (no response expected)
       # @param method [String] JSON-RPC method name
       # @param params [Hash] parameters for the notification
@@ -62,15 +84,28 @@ module MCPClient
 
       # Perform JSON-RPC initialize handshake with the MCP server
       # @return [void]
+      # @raise [MCPClient::Errors::ConnectionError] if the initialize result is malformed
       def perform_initialize
         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)
-        return unless result.is_a?(Hash)
+        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
+          # mandatory notifications/initialized (MCP lifecycle "Initialization":
+          # "After successful initialization, the client MUST send an
+          # `initialized` notification"), so fail the connection instead.
+          cleanup
+          raise MCPClient::Errors::ConnectionError,
+                "Invalid initialize response from server: expected an object, got #{result.inspect}"
+        end
 
+        # Disconnects if the server negotiated a version we cannot speak.
+        @protocol_version = validate_protocol_version!(result)
         @server_info = result['serverInfo']
         @capabilities = result['capabilities']
+        @instructions = result['instructions']
 
         # Send initialized notification to acknowledge completion of initialization
         initialized_notification = build_jsonrpc_notification('notifications/initialized', {})
@@ -86,27 +121,52 @@ module MCPClient
       # @raise [MCPClient::Errors::ConnectionError] if connection fails
       # @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)
-        @logger.debug("Sending JSON-RPC request: #{request.to_json}")
+      def send_jsonrpc_request(request, timeout: nil)
+        @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
           response = post_json_rpc_request(request)
 
           if @use_sse
-            wait_for_sse_result(request)
+            wait_for_sse_result(request, timeout: timeout)
           else
             parse_direct_response(response)
           end
         rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
           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)
         end
       end
 
@@ -133,6 +193,8 @@ module MCPClient
           end
 
           response
+        rescue Faraday::TimeoutError => e
+          raise MCPClient::Errors::RequestTimeoutError, "Request timed out: #{e.message}"
         rescue Faraday::ConnectionFailed => e
           raise MCPClient::Errors::ConnectionError, "Server connection lost: #{e.message}"
         end
@@ -144,7 +206,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
@@ -160,6 +222,11 @@ module MCPClient
         response = conn.post(endpoint) do |req|
           req.headers['Content-Type'] = 'application/json'
           req.headers['Accept'] = 'application/json'
+          # MCP lifecycle "Version Negotiation": the client MUST include the
+          # MCP-Protocol-Version header on all requests after the initialize
+          # handshake. The guard naturally skips the initialize POST itself,
+          # since the negotiated version is only known from its result.
+          req.headers['Mcp-Protocol-Version'] = @protocol_version if @protocol_version
           (@headers.dup.tap do |h|
             h.delete('Accept')
             h.delete('Cache-Control')
@@ -168,7 +235,7 @@ module MCPClient
         end
 
         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
@@ -177,10 +244,10 @@ module MCPClient
       # @param request [Hash] the original JSON-RPC request
       # @return [Hash] the result data
       # @raise [MCPClient::Errors::ConnectionError, MCPClient::Errors::ToolCallError] on errors
-      def wait_for_sse_result(request)
+      def wait_for_sse_result(request, timeout: nil)
         request_id = request['id']
         start_time = Time.now
-        timeout = @read_timeout || 10
+        timeout ||= @read_timeout || 10
 
         ensure_sse_connection_active
 
@@ -222,12 +289,13 @@ module MCPClient
           sleep 0.1
         end
 
-        raise MCPClient::Errors::ToolCallError, "Timeout waiting for SSE result for request #{request_id}"
+        raise MCPClient::Errors::RequestTimeoutError, "Timeout waiting for SSE result for request #{request_id}"
       end
 
       # 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
+      # @raise [MCPClient::Errors::ServerError] if the stored result is a JSON-RPC error response
       def check_for_result(request_id)
         result = nil
         @mutex.synchronize do
@@ -236,12 +304,27 @@ module MCPClient
 
         if result
           record_activity
+          # 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)
           return result
         end
 
         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
+      end
+
       # Parse a direct (non-SSE) JSON-RPC response
       # @param response [Faraday::Response] the HTTP response
       # @return [Hash] the parsed result
@@ -251,7 +334,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
@@ -88,9 +92,13 @@ module MCPClient
 
             cleanup
 
-            # Clear any stale auth error from the previous connection so it does
-            # not spuriously abort this reconnect via wait_for_connection.
-            @mutex.synchronize { @auth_error = nil }
+            # Clear any stale auth/connection error from the previous connection
+            # so it does not spuriously abort this reconnect via
+            # wait_for_connection.
+            @mutex.synchronize do
+              @auth_error = nil
+              @connection_error = nil
+            end
 
             connect
             @logger.info('Successfully reconnected after ping failures')
@@ -169,11 +177,14 @@ module MCPClient
           deadline = Time.now + timeout
 
           until @connection_established
+            break if @connection_error
+
             remaining = [1, deadline - Time.now].min
             break if remaining <= 0 || @connection_cv.wait(remaining) { @connection_established }
           end
 
           raise MCPClient::Errors::ConnectionError, @auth_error if @auth_error
+          raise MCPClient::Errors::ConnectionError, @connection_error if @connection_error
 
           unless @connection_established
             cleanup
@@ -195,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

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
 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)
@@ -30,7 +34,7 @@ module MCPClient
         begin
           data = JSON.parse(event[:data])
 
-          return if process_error_in_message(data)
+          return if process_error_in_message?(data)
           return if process_server_request?(data)
           return if process_notification?(data)
 
@@ -38,17 +42,23 @@ module MCPClient
         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
       end
 
-      # Process a JSON-RPC error() in the SSE stream.
+      # Process a connection-level JSON-RPC error payload in the SSE stream.
+      # Error RESPONSES (id-bearing) belong to a pending request and are
+      # delivered to the waiting caller via process_response? instead, per the
+      # MCP lifecycle "Error Handling" section (implementations SHOULD handle
+      # error cases such as protocol version mismatch), so they must not be
+      # swallowed here.
       # @param data [Hash] the parsed JSON payload
-      # @return [Boolean] true if we saw & handled an error
-      def process_error_in_message(data)
-        return unless data['error']
+      # @return [Boolean] true if we saw & handled an id-less error
+      def process_error_in_message?(data)
+        return false unless data['error']
+        return false if data['id']
 
         error_message = data['error']['message'] || 'Unknown server error'
         error_code    = data['error']['code']
@@ -91,10 +101,21 @@ 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
+
           @sse_results[data['id']] =
             if data['error']
-              { 'isError' => true,
-                'content' => [{ 'type' => 'text', 'text' => data['error'].to_json }] }
+              # 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
               data['result']
             end
@@ -130,16 +151,63 @@ module MCPClient
         has_content ? event : nil
       end
 
-      # Handle the special "endpoint" control frame (for SSE handshake)
+      # Handle the special "endpoint" control frame (for SSE handshake).
+      # The event data is a URI reference (MCP 2024-11-05 HTTP with SSE: the
+      # server sends "an `endpoint` event containing a URI for the client to
+      # use for sending messages") which must be resolved against the SSE
+      # connection URL per RFC 3986 section 5.1.3, so relative endpoint URIs
+      # POST to the URL the server actually designated.
       # @param data [String] the raw endpoint payload
       def handle_endpoint_event(data)
+        endpoint = resolve_endpoint_uri(data)
         @mutex.synchronize do
-          @rpc_endpoint = data
+          @rpc_endpoint = endpoint
           @sse_connected = true
           @connection_established = true
           @connection_cv.broadcast
         end
       end
+
+      # 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)
+        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}")
+        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
+          @connection_cv.broadcast
+        end
+        raise MCPClient::Errors::TransportError, message
+      end
     end
   end
 end