ruby-mcp-client 1.1.0 → 2.1.0

data/lib/mcp_client/server_sse.rb

@@ -40,6 +40,13 @@ module MCPClient
     MAX_RECONNECT_DELAY = 30
     JITTER_FACTOR = 0.25
 
+    # Maximum bytes the SSE parse buffer may hold while waiting for an event
+    # terminator. The stream is peer-controlled: without a cap, a hostile
+    # server could withhold the blank-line delimiter forever and grow the
+    # buffer until the host runs out of memory. Generous enough for any
+    # legitimate JSON-RPC response event.
+    MAX_SSE_BUFFER_BYTES = 32 * 1024 * 1024
+
     # @!attribute [r] base_url
     #   @return [String] The base URL of the MCP server
     # @!attribute [r] tools
@@ -91,13 +98,25 @@ module MCPClient
       @tools_data = nil
       @request_id = 0
       @sse_results = {}
+      # Ids of requests a caller is actively waiting on. Only responses for
+      # these ids are stored in @sse_results — everything else on the peer
+      # controlled stream is unsolicited and discarded.
+      @pending_request_ids = Set.new
       @mutex = Monitor.new
-      @buffer = ''
+      @buffer = +''
+      # How much of @buffer has already been searched for an event terminator
+      @buffer_scanned = 0
       @sse_connected = false
       @connection_established = false
       @connection_cv = @mutex.new_cond
       @initialized = false
+      # Negotiated protocol version captured from the initialize result
+      # (sent as the MCP-Protocol-Version header on post-initialize requests)
+      @protocol_version = nil
       @auth_error = nil
+      # Non-auth connection failure cause (e.g. invalid endpoint event URI)
+      # recorded by the SSE worker for wait_for_connection to surface
+      @connection_error = nil
       # Whether to use SSE transport; may disable if handshake fails
       @use_sse = true
 
@@ -157,10 +176,7 @@ module MCPClient
     # @raise [MCPClient::Errors::PromptGetError] for other errors during prompt interpolation
     # @raise [MCPClient::Errors::ConnectionError] if server is disconnected
     def get_prompt(prompt_name, parameters)
-      rpc_request('prompts/get', {
-                    name: prompt_name,
-                    arguments: parameters
-                  })
+      rpc_request('prompts/get', build_named_request_params(prompt_name, parameters))
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       # Re-raise connection/transport errors directly to match test expectations
       raise
@@ -254,9 +270,11 @@ module MCPClient
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during subscription
     def subscribe_resource(uri)
       ensure_initialized
+      require_capability!('resources', 'subscribe', method: 'resources/subscribe')
       rpc_request('resources/subscribe', { uri: uri })
       true
-    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError,
+           MCPClient::Errors::CapabilityError
       raise
     rescue StandardError => e
       raise MCPClient::Errors::ResourceReadError, "Error subscribing to resource '#{uri}': #{e.message}"
@@ -269,9 +287,11 @@ module MCPClient
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during unsubscription
     def unsubscribe_resource(uri)
       ensure_initialized
+      require_capability!('resources', 'subscribe', method: 'resources/unsubscribe')
       rpc_request('resources/unsubscribe', { uri: uri })
       true
-    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError,
+           MCPClient::Errors::CapabilityError
       raise
     rescue StandardError => e
       raise MCPClient::Errors::ResourceReadError, "Error unsubscribing from resource '#{uri}': #{e.message}"
@@ -315,10 +335,7 @@ module MCPClient
     # @raise [MCPClient::Errors::ToolCallError] for other errors during tool execution
     # @raise [MCPClient::Errors::ConnectionError] if server is disconnected
     def call_tool(tool_name, parameters)
-      rpc_request('tools/call', {
-                    name: tool_name,
-                    arguments: parameters
-                  })
+      rpc_request('tools/call', build_named_request_params(tool_name, parameters))
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       # Re-raise connection/transport errors directly to match test expectations
       raise
@@ -334,11 +351,14 @@ module MCPClient
     # @return [Hash] completion result with 'values', optional 'total', and 'hasMore' fields
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     def complete(ref:, argument:, context: nil)
+      ensure_initialized
+      require_capability!('completions', method: 'completion/complete')
       params = { ref: ref, argument: argument }
       params[:context] = context if context
       result = rpc_request('completion/complete', params)
       result['completion'] || { 'values' => [] }
-    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError,
+           MCPClient::Errors::CapabilityError
       raise
     rescue StandardError => e
       raise MCPClient::Errors::ServerError, "Error requesting completion: #{e.message}"
@@ -350,8 +370,11 @@ module MCPClient
     # @return [Hash] empty result on success
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     def log_level=(level)
+      ensure_initialized
+      require_capability!('logging', method: 'logging/setLevel')
       rpc_request('logging/setLevel', { level: level })
-    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError,
+           MCPClient::Errors::CapabilityError
       raise
     rescue StandardError => e
       raise MCPClient::Errors::ServerError, "Error setting log level: #{e.message}"
@@ -369,6 +392,8 @@ module MCPClient
       begin
         # Don't reset auth error if it's pre-existing
         @mutex.synchronize { @auth_error = nil } unless pre_existing_auth_error
+        # Clear any stale connection failure cause from a previous attempt
+        @mutex.synchronize { @connection_error = nil }
 
         start_sse_thread
         effective_timeout = [@read_timeout || 30, 30].min
@@ -404,10 +429,25 @@ module MCPClient
         @connection_established = false
         @sse_connected = false
         @initialized = false # Reset initialization state for reconnection
+        # A fresh session negotiates its own protocol version; keeping the old
+        # one would leak the previous session's version into the next
+        # initialize POST's MCP-Protocol-Version header.
+        @protocol_version = nil
 
         # Reset the SSE parse buffer so a reconnect never inherits a leftover
         # partial event from the previous connection.
-        @buffer = ''
+        @buffer = +''
+        @buffer_scanned = 0
+
+        # Drop results nobody is waiting for, so peer-supplied state cannot
+        # accumulate across reconnects. Results for still-pending requests are
+        # KEPT: a response can arrive while its POST is still returning, and
+        # the waiter (which reconnects through ensure_sse_connection_active)
+        # is about to consume it. Discarding those reported a timeout for a
+        # tool call the server had already executed — inviting a duplicate
+        # manual retry. unregister_pending_request clears each entry when its
+        # request finishes, so nothing lingers.
+        @sse_results.select! { |id, _| @pending_request_ids.include?(id) }
 
         # Log cleanup for debugging
         @logger.debug('Cleaning up SSE connection')
@@ -503,8 +543,11 @@ module MCPClient
         send_error_response(request_id, -32_601, "Method not found: #{method}")
       end
     rescue StandardError => e
+      # The exception message is host-internal (file paths, connection
+      # strings, library internals): log it locally, but answer the peer with
+      # a constant message so failures cannot be used to probe the host.
       @logger.error("Error handling server request: #{e.message}")
-      send_error_response(request_id, -32_603, "Internal error: #{e.message}")
+      send_error_response(request_id, -32_603, 'Internal error')
     end
 
     # Handle a server-initiated ping request (MCP ping utility)
@@ -527,18 +570,19 @@ module MCPClient
     # @param params [Hash] the elicitation parameters
     # @return [void]
     def handle_elicitation_create(request_id, params)
-      # If no callback is registered, decline the request
+      # Without a callback there is no user to interact with: answer with a
+      # JSON-RPC error rather than fabricating a user "decline".
       unless @elicitation_request_callback
-        @logger.warn('Received elicitation request but no callback registered, declining')
-        send_elicitation_response(request_id, { 'action' => 'decline' })
+        @logger.warn('Received elicitation request but no callback registered')
+        send_error_response(request_id, -32_601, 'Elicitation not supported: no handler configured')
         return
       end
 
       # Call the registered callback
       result = @elicitation_request_callback.call(request_id, params)
 
-      # Send the response back to the server
-      send_elicitation_response(request_id, result)
+      # Send the response back to the server (echoing related-task _meta)
+      send_elicitation_response(request_id, merge_related_task_meta(result, params))
     end
 
     # Handle roots/list request from server (MCP 2025-06-18)
@@ -556,8 +600,8 @@ module MCPClient
       # Call the registered callback
       result = @roots_list_request_callback.call(request_id, params)
 
-      # Send the response back to the server
-      send_roots_list_response(request_id, result)
+      # Send the response back to the server (echoing related-task _meta)
+      send_roots_list_response(request_id, merge_related_task_meta(result, params))
     end
 
     # Send roots/list response back to server via HTTP POST (MCP 2025-06-18)
@@ -594,8 +638,8 @@ module MCPClient
       # Call the registered callback
       result = @sampling_request_callback.call(request_id, params)
 
-      # Send the response back to the server
-      send_sampling_response(request_id, result)
+      # Send the response back to the server (echoing related-task _meta)
+      send_sampling_response(request_id, merge_related_task_meta(result, params))
     end
 
     # Send sampling response back to server via HTTP POST (MCP 2025-11-25)
@@ -628,6 +672,14 @@ module MCPClient
     # @param result [Hash] the elicitation result (action and optional content)
     # @return [void]
     def send_elicitation_response(request_id, result)
+      # Error-shaped results become JSON-RPC error responses (e.g. -32602 for
+      # an undeclared elicitation mode), mirroring the sampling error path.
+      if result.is_a?(Hash) && result['error']
+        send_error_response(request_id, result['error']['code'] || -32_603,
+                            result['error']['message'] || 'Elicitation error')
+        return
+      end
+
       ensure_initialized
 
       response = {
@@ -685,11 +737,14 @@ module MCPClient
       @rpc_conn.post do |req|
         req.url @rpc_endpoint
         req.headers['Content-Type'] = 'application/json'
+        # MCP lifecycle "Version Negotiation": include the MCP-Protocol-Version
+        # header on all HTTP requests after the initialize handshake.
+        req.headers['Mcp-Protocol-Version'] = @protocol_version if @protocol_version
         @headers.each { |k, v| req.headers[k] = v }
         req.body = json_body
       end
 
-      @logger.debug("Sent response via HTTP POST: #{json_body}")
+      @logger.debug("Sent response via HTTP POST: #{describe_jsonrpc_message(response)}")
     rescue StandardError => e
       @logger.error("Failed to send response via HTTP POST: #{e.message}")
     end
@@ -811,7 +866,9 @@ module MCPClient
     # Process an SSE chunk from the server
     # @param chunk [String] the chunk to process
     def process_sse_chunk(chunk)
-      @logger.debug("Processing SSE chunk: #{chunk.inspect}")
+      # Size only: the chunk is raw wire data carrying sampling prompts,
+      # elicitation content and tool results.
+      @logger.debug("Processing SSE chunk (#{describe_body_size(chunk)})")
 
       # Only record activity for real events
       record_activity if chunk.include?('event:')
@@ -869,21 +926,61 @@ module MCPClient
     # @return [Array<String>, nil] array of complete events or nil if none
     # @private
     def extract_complete_events(chunk)
-      event_buffers = nil
+      event_buffers = []
       @mutex.synchronize do
-        @buffer += chunk
-
-        # Extract all complete events from the buffer
-        # Handle both Unix (\n\n) and Windows (\r\n\r\n) line endings
-        event_buffers = []
-        while (event_end = @buffer.index("\n\n") || @buffer.index("\r\n\r\n"))
-          event_data = extract_single_event(event_end)
-          event_buffers << event_data
+        # Append in place. `@buffer += chunk` allocates and copies the whole
+        # buffer on every callback, so an unterminated event delivered in N
+        # chunks costs O(N^2) copying — memory stays capped but a peer can
+        # still burn CPU and thrash the allocator on the way there.
+        @buffer << chunk
+
+        # Rescan only the newly arrived bytes, backing up by the longest
+        # delimiter minus one so one split across two chunks is still found.
+        scan_from = [@buffer_scanned - 3, 0].max
+        while (event_end = next_event_end(scan_from))
+          event_buffers << extract_single_event(event_end)
+          # The buffer shifted; what remains is short (one event at most).
+          scan_from = 0
+          @buffer_scanned = 0
         end
+        @buffer_scanned = @buffer.length
+
+        # Whatever is left is a partial event still awaiting its terminator.
+        # The cap is applied here rather than before appending so a single
+        # oversized chunk that DOES contain complete events is still parsed.
+        fail_oversized_sse_buffer! if @buffer.bytesize > MAX_SSE_BUFFER_BYTES
       end
       event_buffers
     end
 
+    # Index of the earliest event terminator at or after an offset.
+    # @param offset [Integer] character offset to start searching from
+    # @return [Integer, nil] index of the terminator, or nil if none yet
+    def next_event_end(offset)
+      lf = @buffer.index("\n\n", offset)
+      crlf = @buffer.index("\r\n\r\n", offset)
+      [lf, crlf].compact.min
+    end
+
+    # Drop an oversized partial event and fail the connection.
+    #
+    # Recording the cause matters: this runs inside Faraday's on_data callback
+    # on the SSE worker thread, whose generic rescue would otherwise leave
+    # callers with a bare "connection lost" and no reason. Mirrors the
+    # endpoint-URI failure path so wait_for_connection surfaces it promptly.
+    # @raise [MCPClient::Errors::ConnectionError] always
+    def fail_oversized_sse_buffer!
+      message = "SSE event exceeded the maximum buffered size (#{MAX_SSE_BUFFER_BYTES} bytes) " \
+                'without a terminator'
+      @buffer = +''
+      @buffer_scanned = 0
+      @connection_error = message
+      @connection_established = false
+      @connection_cv.broadcast
+      @logger.error(message)
+      raise MCPClient::Errors::ConnectionError, message
+    end
+
     # Extract a single event from the buffer
     # @param event_end [Integer] the position where the event ends
     # @return [String] the extracted event data

data/lib/mcp_client/server_stdio/json_rpc_transport.rb

@@ -35,10 +35,13 @@ module MCPClient
           raise MCPClient::Errors::ConnectionError, "Initialize failed: #{err['message']}"
         end
 
-        # Store server info and capabilities
+        # Store negotiated protocol version, server info and capabilities.
+        # Disconnects if the server negotiated a version we cannot speak.
         result = res['result'] || {}
+        @protocol_version = validate_protocol_version!(result)
         @server_info = result['serverInfo']
         @capabilities = result['capabilities']
+        @instructions = result['instructions']
 
         # Send initialized notification
         notif = build_jsonrpc_notification('notifications/initialized', {})
@@ -63,7 +66,7 @@ module MCPClient
       # @return [void]
       # @raise [MCPClient::Errors::TransportError] on write errors
       def send_request(req)
-        @logger.debug("Sending JSONRPC request: #{req.to_json}")
+        @logger.debug("Sending JSONRPC request: #{describe_jsonrpc_message(req)}")
         @stdin.puts(req.to_json)
       rescue StandardError => e
         # A request that failed to send will never receive a response, so drop
@@ -77,8 +80,8 @@ module MCPClient
       # @param id [Integer] the request ID
       # @return [Hash] the JSON-RPC response message
       # @raise [MCPClient::Errors::TransportError] on timeout
-      def wait_response(id)
-        deadline = Time.now + @read_timeout
+      def wait_response(id, timeout: nil)
+        deadline = Time.now + (timeout || @read_timeout)
         @mutex.synchronize do
           until @pending.key?(id)
             remaining = deadline - Time.now
@@ -90,7 +93,7 @@ module MCPClient
           # timeout so neither @pending nor @awaiting accumulates entries.
           msg = @pending.delete(id)
           @awaiting.delete(id)
-          raise MCPClient::Errors::TransportError, "Timeout waiting for JSONRPC response id=#{id}" unless msg
+          raise MCPClient::Errors::RequestTimeoutError, "Timeout waiting for JSONRPC response id=#{id}" unless msg
 
           msg
         end
@@ -113,17 +116,37 @@ module MCPClient
       # @raise [MCPClient::Errors::ServerError] if server returns an error
       # @raise [MCPClient::Errors::TransportError] on transport errors
       # @raise [MCPClient::Errors::ToolCallError] on tool call errors
-      def rpc_request(method, params = {})
+      def rpc_request(method, params = {}, timeout: nil)
         ensure_initialized
-        with_retry do
+        with_retry(method) do
           req_id = next_id
           req = build_jsonrpc_request(method, params, req_id)
           send_request(req)
-          res = wait_response(req_id)
+          begin
+            res = wait_response(req_id, 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(req_id) if cancellable_request?(method, params)
+            raise
+          end
           process_jsonrpc_response(res)
         end
       end
 
+      # Best-effort notifications/cancelled for a request the client stopped
+      # waiting on. Failures are swallowed: the transport may be the reason
+      # the request timed out in the first place.
+      # @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' })
+        @stdin.puts(notif.to_json)
+      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
       # @param params [Hash] parameters for the notification