ruby-mcp-client 1.1.0 → 2.0.0

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', {})
@@ -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
           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

data/lib/mcp_client/server_stdio.rb

@@ -21,6 +21,12 @@ module MCPClient
     # Timeout in seconds for responses
     READ_TIMEOUT = 15
 
+    # Grace period in seconds allowed at each stage of the shutdown sequence
+    # (after closing stdin, then after SIGTERM) before escalating further, per
+    # MCP 2025-11-25 basic/lifecycle.mdx (Shutdown / stdio): close stdin, wait
+    # for the server to exit, send SIGTERM, then SIGKILL if it still runs.
+    SHUTDOWN_GRACE_PERIOD = 2
+
     # Chunk size (bytes) used when draining the subprocess stderr pipe
     STDERR_READ_CHUNK_SIZE = 8192
 
@@ -87,11 +93,25 @@ module MCPClient
       else
         @stdin, @stdout, @stderr, @wait_thread = Open3.popen3(@command)
       end
+      pin_pipe_encodings
       true
     rescue StandardError => e
       raise MCPClient::Errors::ConnectionError, "Failed to connect to MCP server: #{e.message}"
     end
 
+    # Pin the subprocess pipe encodings to UTF-8 instead of inheriting the
+    # process locale (Encoding.default_external). JSON-RPC messages MUST be
+    # UTF-8 encoded (MCP 2025-11-25 basic/transports.mdx); under a non-UTF-8
+    # locale (e.g. LANG=C) a valid UTF-8 message would otherwise fail to
+    # decode and kill the reader thread. The server MAY also write UTF-8 to
+    # stderr, so that pipe is pinned as well.
+    # @return [void]
+    def pin_pipe_encodings
+      [@stdin, @stdout, @stderr].each do |io|
+        io&.set_encoding(Encoding::UTF_8)
+      end
+    end
+
     # Spawn a reader thread to collect JSON-RPC responses
     # @return [Thread] the reader thread
     def start_reader
@@ -142,6 +162,13 @@ module MCPClient
       msg = JSON.parse(line)
       @logger.debug("Received line: #{line.chomp}")
 
+      # A JSON-parseable line that is not an object cannot be a JSON-RPC
+      # message; skip it rather than raising inside the reader thread
+      unless msg.is_a?(Hash)
+        @logger.debug("Skipping non-object JSON-RPC line: #{line.chomp}")
+        return
+      end
+
       # Dispatch JSON-RPC requests from server (has id AND method) - MCP 2025-06-18
       if msg['method'] && msg.key?('id')
         handle_server_request(msg)
@@ -169,8 +196,9 @@ module MCPClient
           @logger.debug("Discarding response for unknown or expired request id=#{id}")
         end
       end
-    rescue JSON::ParserError
-      # Skip non-JSONRPC lines in the output stream
+    rescue JSON::ParserError, EncodingError
+      # Skip non-JSONRPC or undecodable lines in the output stream so a single
+      # bad line cannot kill the reader thread
     end
 
     # List all prompts available from the MCP server
@@ -212,7 +240,7 @@ module MCPClient
         'jsonrpc' => '2.0',
         'id' => req_id,
         'method' => 'prompts/get',
-        'params' => { 'name' => prompt_name, 'arguments' => parameters }
+        'params' => build_named_request_params(prompt_name, parameters)
       }
       send_request(req)
       res = wait_response(req_id)
@@ -308,6 +336,7 @@ module MCPClient
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during subscription
     def subscribe_resource(uri)
       ensure_initialized
+      require_capability!('resources', 'subscribe', method: 'resources/subscribe')
       req_id = next_id
       req = {
         'jsonrpc' => '2.0',
@@ -322,6 +351,8 @@ module MCPClient
       end
 
       true
+    rescue MCPClient::Errors::CapabilityError
+      raise
     rescue StandardError => e
       raise MCPClient::Errors::ResourceReadError, "Error subscribing to resource '#{uri}': #{e.message}"
     end
@@ -333,6 +364,7 @@ module MCPClient
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during unsubscription
     def unsubscribe_resource(uri)
       ensure_initialized
+      require_capability!('resources', 'subscribe', method: 'resources/unsubscribe')
       req_id = next_id
       req = {
         'jsonrpc' => '2.0',
@@ -347,6 +379,8 @@ module MCPClient
       end
 
       true
+    rescue MCPClient::Errors::CapabilityError
+      raise
     rescue StandardError => e
       raise MCPClient::Errors::ResourceReadError, "Error unsubscribing from resource '#{uri}': #{e.message}"
     end
@@ -391,7 +425,7 @@ module MCPClient
         'jsonrpc' => '2.0',
         'id' => req_id,
         'method' => 'tools/call',
-        'params' => { 'name' => tool_name, 'arguments' => parameters }
+        'params' => build_named_request_params(tool_name, parameters)
       }
       send_request(req)
       res = wait_response(req_id)
@@ -412,6 +446,7 @@ module MCPClient
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     def complete(ref:, argument:, context: nil)
       ensure_initialized
+      require_capability!('completions', method: 'completion/complete')
       req_id = next_id
       params = { 'ref' => ref, 'argument' => argument }
       params['context'] = context if context
@@ -428,6 +463,8 @@ module MCPClient
       end
 
       res.dig('result', 'completion') || { 'values' => [] }
+    rescue MCPClient::Errors::CapabilityError
+      raise
     rescue StandardError => e
       raise MCPClient::Errors::ServerError, "Error requesting completion: #{e.message}"
     end
@@ -439,6 +476,7 @@ module MCPClient
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     def log_level=(level)
       ensure_initialized
+      require_capability!('logging', method: 'logging/setLevel')
       req_id = next_id
       req = {
         'jsonrpc' => '2.0',
@@ -453,6 +491,8 @@ module MCPClient
       end
 
       res['result'] || {}
+    rescue MCPClient::Errors::CapabilityError
+      raise
     rescue StandardError => e
       raise MCPClient::Errors::ServerError, "Error setting log level: #{e.message}"
     end
@@ -524,18 +564,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)
@@ -553,8 +594,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
 
     # Handle sampling/createMessage request from server (MCP 2025-11-25)
@@ -572,8 +613,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 roots/list response back to server (MCP 2025-06-18)
@@ -613,6 +654,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
+
       response = {
         'jsonrpc' => '2.0',
         'id' => request_id,
@@ -673,17 +722,17 @@ module MCPClient
 
     # Clean up the server connection
     # Closes all stdio handles and terminates any running processes and threads
+    # following the MCP 2025-11-25 stdio shutdown sequence (basic/lifecycle.mdx):
+    # close stdin, wait for the server to exit, send SIGTERM if it does not exit
+    # within a reasonable time, then SIGKILL if it still does not exit.
     # @return [void]
     def cleanup
       return unless @stdin
 
       @stdin.close unless @stdin.closed?
+      terminate_server_process
       @stdout.close unless @stdout.closed?
       @stderr.close unless @stderr.closed?
-      if @wait_thread&.alive?
-        Process.kill('TERM', @wait_thread.pid)
-        @wait_thread.join(1)
-      end
       @reader_thread&.kill
       @stderr_thread&.kill
     rescue StandardError
@@ -696,5 +745,31 @@ module MCPClient
       end
       @stdin = @stdout = @stderr = @wait_thread = @reader_thread = @stderr_thread = nil
     end
+
+    # Terminate the spawned server process per the MCP 2025-11-25 stdio
+    # shutdown sequence (basic/lifecycle.mdx): stdin has already been closed,
+    # so wait for the process to exit on its own; if it does not exit within
+    # the grace period send SIGTERM, wait again, and finally send SIGKILL.
+    # @return [void]
+    def terminate_server_process
+      return unless @wait_thread
+      return if @wait_thread.join(SHUTDOWN_GRACE_PERIOD)
+
+      signal_server_process('TERM')
+      return if @wait_thread.join(SHUTDOWN_GRACE_PERIOD)
+
+      signal_server_process('KILL')
+      @wait_thread.join(SHUTDOWN_GRACE_PERIOD)
+    end
+
+    # Send a signal to the server process, tolerating a process that has
+    # already exited or cannot be signalled.
+    # @param signal [String] signal name, e.g. 'TERM' or 'KILL'
+    # @return [void]
+    def signal_server_process(signal)
+      Process.kill(signal, @wait_thread.pid)
+    rescue Errno::ESRCH, Errno::EPERM => e
+      @logger.debug("Could not send SIG#{signal} to server process: #{e.class}")
+    end
   end
 end

data/lib/mcp_client/server_streamable_http/json_rpc_transport.rb

@@ -22,10 +22,11 @@ module MCPClient
 
       # Parse a Streamable HTTP JSON-RPC response (JSON or SSE format)
       # @param response [Faraday::Response] the HTTP response
+      # @param request [Hash, nil] the originating JSON-RPC request, used to match the response by id
       # @return [Hash] the parsed result
       # @raise [MCPClient::Errors::TransportError] if parsing fails
       # @raise [MCPClient::Errors::ServerError] if the response contains an error
-      def parse_response(response)
+      def parse_response(response, request = nil)
         body = response.body
         content_type = response.headers['content-type'] || response.headers['Content-Type'] || ''
         content_encoding = response.headers['content-encoding'] || response.headers['Content-Encoding'] || ''
@@ -36,7 +37,7 @@ module MCPClient
         # Determine response format based on Content-Type header per MCP 2025 spec
         data = if content_type.include?('text/event-stream')
                  # Parse SSE-formatted response for streaming
-                 parse_sse_response(body)
+                 parse_sse_response(body, request && request['id'])
                else
                  # Parse regular JSON response (default for Streamable HTTP)
                  JSON.parse(body)
@@ -47,50 +48,175 @@ module MCPClient
         raise MCPClient::Errors::TransportError, "Invalid JSON response from server: #{e.message}"
       end
 
-      # Parse Server-Sent Event formatted response with event ID tracking
+      # Parse a Server-Sent Event formatted response body.
+      #
+      # Per MCP 2025-11-25, the server MAY send JSON-RPC requests and
+      # notifications on the POST response stream before the response, and MAY
+      # send priming events carrying only an event id. Every interleaved server
+      # message is dispatched exactly like on the GET events stream; the
+      # JSON-RPC response matching the originating request id is returned.
+      #
       # @param sse_body [String] the SSE formatted response body
-      # @return [Hash] the parsed JSON data
-      # @raise [MCPClient::Errors::TransportError] if no data found in SSE response
-      def parse_sse_response(sse_body)
-        # Extract JSON data from SSE format, processing events separately
-        # SSE format: event: message\nid: 123\ndata: {...}\n\n
+      # @param request_id [Integer, String, nil] id of the originating request
+      # @return [Hash] the parsed JSON-RPC response
+      # @raise [MCPClient::Errors::TransportError] if no response is found
+      def parse_sse_response(sse_body, request_id = nil)
+        events, retry_ms = extract_sse_events(sse_body)
+
+        raise MCPClient::Errors::TransportError, 'No data found in SSE response' if events.empty?
+
+        responses, saw_invalid_json = route_sse_events(events)
+        matched = select_sse_response(responses, request_id)
+        return matched if matched
+
+        if saw_invalid_json
+          raise MCPClient::Errors::TransportError,
+                'Invalid JSON response from server: SSE stream contained no valid JSON-RPC response'
+        end
+
+        resume_or_fail(events, request_id, retry_ms)
+      end
+
+      # SEP-1699 polling pattern: the server MAY close the POST stream before
+      # delivering the response. When a cursor was received, resume via HTTP
+      # GET with Last-Event-ID instead of re-POSTing the (possibly
+      # non-idempotent) request.
+      # @param events [Array<Hash>] parsed SSE events
+      # @param request_id [Integer, String, nil] id of the originating request
+      # @param retry_ms [Integer, nil] retry directive received on THIS stream
+      # @return [Hash] the replayed JSON-RPC response
+      # @raise [MCPClient::Errors::ServerError] when resumption fails
+      # @raise [MCPClient::Errors::TransportError] when no cursor was received
+      def resume_or_fail(events, request_id, retry_ms = nil)
+        cursor = events.reverse.find { |e| e[:id] && !e[:id].empty? }&.dig(:id)
+        if request_id && cursor
+          # Resume with THIS stream's cursor and retry directive (both are
+          # per-stream), not the shared @last_event_id / @sse_retry_ms which a
+          # concurrent stream may have moved between parsing and resumption.
+          resumed = resume_response_via_get(request_id, cursor, retry_ms)
+          return resumed if resumed
+
+          # Non-retryable: the request may already be executing server-side,
+          # so a blind re-POST could run a non-idempotent operation twice.
+          raise MCPClient::Errors::ServerError,
+                'SSE stream closed before delivering the response and resumption via GET failed'
+        end
+
+        raise MCPClient::Errors::TransportError, 'No JSON-RPC response found in SSE response'
+      end
+
+      # Split an SSE body into events. An event without an explicit `event:`
+      # field has the default type "message" per the SSE specification; events
+      # carrying only an id (priming events) are kept so their id is tracked.
+      # @param sse_body [String] the SSE formatted response body
+      # @return [Array(Array<Hash>, Integer, nil)] parsed events and the last
+      #   retry directive (ms) received on this stream, if any
+      def extract_sse_events(sse_body)
         events = []
-        current_event = { type: nil, data_lines: [], id: nil }
+        retry_ms = nil
+        current_event = { type: 'message', data_lines: [], id: nil }
 
         sse_body.lines.each do |line|
           line = line.strip
 
           if line.empty?
             # Empty line marks end of an event
-            events << current_event.dup if current_event[:type] && !current_event[:data_lines].empty?
-            current_event = { type: nil, data_lines: [], id: nil }
+            events << current_event.dup if sse_event_present?(current_event)
+            current_event = { type: 'message', data_lines: [], id: nil }
           elsif line.start_with?('event:')
             current_event[:type] = line.sub(/^event:\s*/, '').strip
           elsif line.start_with?('data:')
             current_event[:data_lines] << line.sub(/^data:\s*/, '').strip
           elsif line.start_with?('id:')
             current_event[:id] = line.sub(/^id:\s*/, '').strip
+          elsif line.start_with?('retry:')
+            # SEP-1699: the client MUST respect the server's retry directive.
+            # Track it locally for this stream's resumption; the shared ivar is
+            # only a hint for the general events loop.
+            raw = line.sub(/^retry:\s*/, '').strip
+            if raw.match?(/\A\d+\z/)
+              retry_ms = raw.to_i
+              @sse_retry_ms = retry_ms
+            end
           end
         end
 
         # Handle last event if no trailing empty line
-        events << current_event if current_event[:type] && !current_event[:data_lines].empty?
+        events << current_event if sse_event_present?(current_event)
+        [events, retry_ms]
+      end
 
-        # Find the first 'message' event which contains the JSON-RPC response
-        message_event = events.find { |e| e[:type] == 'message' }
+      # @param event [Hash] a parsed SSE event
+      # @return [Boolean] whether the event carries any data or id
+      def sse_event_present?(event)
+        (event[:id] && !event[:id].empty?) || !event[:data_lines].empty?
+      end
+
+      # Track event ids for resumability, dispatch interleaved server messages
+      # (requests, notifications, pings) and collect response candidates.
+      # @param events [Array<Hash>] parsed SSE events
+      # @return [Array(Array<Hash>, Boolean)] response candidates and whether invalid JSON was seen
+      def route_sse_events(events)
+        responses = []
+        saw_invalid_json = false
+
+        events.each do |event|
+          if event[:id] && !event[:id].empty?
+            @mutex.synchronize { @last_event_id = event[:id] }
+            @logger.debug("Tracking event ID for resumability: #{event[:id]}")
+          end
+          next unless event[:type] == 'message'
+
+          message = parse_sse_event_data(event[:data_lines].join("\n"))
+          saw_invalid_json = true if message == :invalid
+          next unless message.is_a?(Hash)
+
+          if message['method']
+            dispatch_server_message(message)
+          else
+            responses << message
+          end
+        end
 
-        raise MCPClient::Errors::TransportError, 'No data found in SSE response' unless message_event
-        raise MCPClient::Errors::TransportError, 'No data found in message event' if message_event[:data_lines].empty?
+        [responses, saw_invalid_json]
+      end
+
+      # Parse the data payload of a single SSE event.
+      # @param json_data [String] the joined data lines
+      # @return [Hash, Symbol, nil] the parsed message, :invalid, or nil for empty/non-object data
+      def parse_sse_event_data(json_data)
+        return nil if json_data.empty?
+
+        message = JSON.parse(json_data)
+        return message if message.is_a?(Hash)
+
+        @logger.warn("Skipping non-object JSON-RPC message in SSE event: #{message.inspect}")
+        nil
+      rescue JSON::ParserError => e
+        @logger.warn("Skipping invalid JSON in SSE event: #{e.message}")
+        :invalid
+      end
 
-        # Track the event ID for resumability
-        if message_event[:id] && !message_event[:id].empty?
-          @last_event_id = message_event[:id]
-          @logger.debug("Tracking event ID for resumability: #{message_event[:id]}")
+      # Choose the JSON-RPC response answering the originating request.
+      # @param responses [Array<Hash>] response candidates from the stream
+      # @param request_id [Integer, String, nil] id of the originating request
+      # @return [Hash, nil] the selected response, if any
+      def select_sse_response(responses, request_id)
+        matched = if request_id.nil?
+                    responses.first
+                  else
+                    responses.find { |msg| msg['id'] == request_id || msg['id'].to_s == request_id.to_s }
+                  end
+
+        if matched.nil? && responses.length == 1
+          matched = responses.first
+          @logger.warn(
+            "SSE response id #{matched['id'].inspect} does not match request id #{request_id.inspect}; " \
+            'accepting the only response on the stream'
+          )
         end
 
-        # Join multiline data fields according to SSE spec
-        json_data = message_event[:data_lines].join("\n")
-        JSON.parse(json_data)
+        matched
       end
     end
   end