ruby-mcp-client 1.0.1 → 2.0.0

data/lib/mcp_client/server_stdio/json_rpc_transport.rb

@@ -16,6 +16,7 @@ module MCPClient
 
         connect
         start_reader
+        start_stderr_reader
         perform_initialize
 
         @initialized = true
@@ -34,22 +35,28 @@ 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', {})
         @stdin.puts(notif.to_json)
       end
 
-      # Generate a new unique request ID
+      # Generate a new unique request ID and mark it as awaiting a response.
+      # Registering the id before the request is sent lets the reader thread
+      # distinguish expected responses from late/unsolicited ones.
       # @return [Integer] a unique request ID
       def next_id
         @mutex.synchronize do
           id = @next_id
           @next_id += 1
+          @awaiting[id] = true
           id
         end
       end
@@ -62,6 +69,10 @@ module MCPClient
         @logger.debug("Sending JSONRPC request: #{req.to_json}")
         @stdin.puts(req.to_json)
       rescue StandardError => e
+        # A request that failed to send will never receive a response, so drop
+        # its awaiting marker; otherwise a broken transport (e.g. the server
+        # exited) would leak an entry per retry/attempt into @awaiting.
+        @mutex.synchronize { @awaiting.delete(req['id']) } if req.is_a?(Hash) && req['id']
         raise MCPClient::Errors::TransportError, "Failed to send JSONRPC request: #{e.message}"
       end
 
@@ -69,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
@@ -78,9 +89,11 @@ module MCPClient
 
             @cond.wait(@mutex, remaining)
           end
-          msg = @pending[id]
-          @pending[id] = nil
-          raise MCPClient::Errors::TransportError, "Timeout waiting for JSONRPC response id=#{id}" unless msg
+          # Remove the response and the awaiting marker on both success and
+          # timeout so neither @pending nor @awaiting accumulates entries.
+          msg = @pending.delete(id)
+          @awaiting.delete(id)
+          raise MCPClient::Errors::RequestTimeoutError, "Timeout waiting for JSONRPC response id=#{id}" unless msg
 
           msg
         end
@@ -103,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,20 @@ 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
+
+    # Maximum bytes buffered for a single unterminated stderr line before it is
+    # flushed. Bounds memory when a server writes to stderr without newlines
+    # (e.g. progress output using carriage returns).
+    STDERR_MAX_LINE_SIZE = 64 * 1024
+
     # Initialize a new ServerStdio instance
     # @param command [String, Array] the stdio command to launch the MCP JSON-RPC server
     #   For improved security, passing an Array is recommended to avoid shell injection issues
@@ -38,6 +52,9 @@ module MCPClient
       @cond = ConditionVariable.new
       @next_id = 1
       @pending = {}
+      # Ids of requests awaiting a response; used to drop late/unsolicited
+      # responses so @pending cannot grow without bound on a long-lived session
+      @awaiting = {}
       @initialized = false
       @server_info = nil
       @capabilities = nil
@@ -49,6 +66,8 @@ module MCPClient
       @elicitation_request_callback = nil # MCP 2025-06-18
       @roots_list_request_callback = nil # MCP 2025-06-18
       @sampling_request_callback = nil # MCP 2025-11-25
+      @reader_thread = nil
+      @stderr_thread = nil
     end
 
     # Server info from the initialize response
@@ -74,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
@@ -91,6 +124,36 @@ module MCPClient
       end
     end
 
+    # Spawn a thread to continuously drain the subprocess stderr.
+    #
+    # The child's stderr pipe has a fixed OS buffer (typically 64KB). If it is
+    # never read, a server that logs verbosely to stderr eventually blocks on
+    # write once the buffer fills, which stalls the whole subprocess (it stops
+    # producing stdout / reading stdin) and deadlocks the client. Draining
+    # stderr keeps the pipe empty; lines are surfaced at debug level.
+    #
+    # Reads happen in bounded chunks (not IO#each_line) so that a server which
+    # writes to stderr without newline delimiters cannot make the client buffer
+    # a single "line" without limit: any pending fragment larger than
+    # STDERR_MAX_LINE_SIZE is flushed rather than retained.
+    # @return [Thread] the stderr reader thread
+    def start_stderr_reader
+      @stderr_thread = Thread.new do
+        buffer = +''
+        loop do
+          buffer << @stderr.readpartial(STDERR_READ_CHUNK_SIZE)
+          flush_stderr_lines(buffer)
+          flush_stderr_overflow(buffer)
+        end
+      rescue IOError
+        # EOFError (a subclass of IOError) on EOF, or IOError on close;
+        # emit any trailing partial line before exiting
+        @logger.debug("[stderr] #{buffer.chomp}") if buffer && !buffer.empty?
+      rescue StandardError
+        # reader aborted unexpectedly; nothing actionable
+      end
+    end
+
     # Handle a line of output from the stdio server
     # Parses JSON-RPC messages and adds them to pending responses
     # @param line [String] line of output to parse
@@ -99,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)
@@ -116,11 +186,19 @@ module MCPClient
       return unless id
 
       @mutex.synchronize do
-        @pending[id] = msg
-        @cond.broadcast
+        # Only retain a response that corresponds to an outstanding request.
+        # Late responses (arriving after the caller timed out) and unsolicited
+        # responses are dropped so @pending cannot grow without bound.
+        if @awaiting.key?(id)
+          @pending[id] = msg
+          @cond.broadcast
+        else
+          @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
@@ -129,15 +207,21 @@ module MCPClient
     # @raise [MCPClient::Errors::PromptGetError] for other errors during prompt listing
     def list_prompts
       ensure_initialized
-      req_id = next_id
-      req = { 'jsonrpc' => '2.0', 'id' => req_id, 'method' => 'prompts/list', 'params' => {} }
-      send_request(req)
-      res = wait_response(req_id)
-      if (err = res['error'])
-        raise MCPClient::Errors::ServerError, err['message']
-      end
+      collect_paginated('prompts') do |cursor|
+        params = {}
+        params['cursor'] = cursor if cursor
+        req_id = next_id
+        req = { 'jsonrpc' => '2.0', 'id' => req_id, 'method' => 'prompts/list', 'params' => params }
+        send_request(req)
+        res = wait_response(req_id)
+        if (err = res['error'])
+          raise MCPClient::Errors::ServerError, err['message']
+        end
 
-      (res.dig('result', 'prompts') || []).map { |td| MCPClient::Prompt.from_json(td, server: self) }
+        result = res['result'] || {}
+        prompts = (result['prompts'] || []).map { |td| MCPClient::Prompt.from_json(td, server: self) }
+        [prompts, result['nextCursor']]
+      end
     rescue StandardError => e
       raise MCPClient::Errors::PromptGetError, "Error listing prompts: #{e.message}"
     end
@@ -156,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)
@@ -252,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',
@@ -266,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
@@ -277,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',
@@ -291,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
@@ -301,16 +391,22 @@ module MCPClient
     # @raise [MCPClient::Errors::ToolCallError] for other errors during tool listing
     def list_tools
       ensure_initialized
-      req_id = next_id
-      # JSON-RPC method for listing tools
-      req = { 'jsonrpc' => '2.0', 'id' => req_id, 'method' => 'tools/list', 'params' => {} }
-      send_request(req)
-      res = wait_response(req_id)
-      if (err = res['error'])
-        raise MCPClient::Errors::ServerError, err['message']
-      end
+      collect_paginated('tools') do |cursor|
+        params = {}
+        params['cursor'] = cursor if cursor
+        req_id = next_id
+        # JSON-RPC method for listing tools
+        req = { 'jsonrpc' => '2.0', 'id' => req_id, 'method' => 'tools/list', 'params' => params }
+        send_request(req)
+        res = wait_response(req_id)
+        if (err = res['error'])
+          raise MCPClient::Errors::ServerError, err['message']
+        end
 
-      (res.dig('result', 'tools') || []).map { |td| MCPClient::Tool.from_json(td, server: self) }
+        result = res['result'] || {}
+        tools = (result['tools'] || []).map { |td| MCPClient::Tool.from_json(td, server: self) }
+        [tools, result['nextCursor']]
+      end
     rescue StandardError => e
       raise MCPClient::Errors::ToolCallError, "Error listing tools: #{e.message}"
     end
@@ -329,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)
@@ -350,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
@@ -366,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
@@ -377,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',
@@ -391,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
@@ -427,6 +529,8 @@ module MCPClient
       @logger.debug("Received server request: #{method} (id: #{request_id})")
 
       case method
+      when 'ping'
+        handle_ping(request_id)
       when 'elicitation/create'
         handle_elicitation_create(request_id, params)
       when 'roots/list'
@@ -442,23 +546,37 @@ module MCPClient
       send_error_response(request_id, -32_603, "Internal error: #{e.message}")
     end
 
+    # Handle a server-initiated ping request (MCP ping utility)
+    # The receiver MUST respond promptly with an empty result.
+    # @param request_id [String, Integer] the JSON-RPC request ID
+    # @return [void]
+    def handle_ping(request_id)
+      response = {
+        'jsonrpc' => '2.0',
+        'id' => request_id,
+        'result' => {}
+      }
+      send_message(response)
+    end
+
     # Handle elicitation/create request from server (MCP 2025-06-18)
     # @param request_id [String, Integer] the JSON-RPC request ID
     # @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)
@@ -476,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)
@@ -495,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)
@@ -536,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,
@@ -573,24 +699,77 @@ module MCPClient
       @logger.error("Error sending message: #{e.message}")
     end
 
+    # Emit and remove all newline-terminated lines from the stderr buffer.
+    # @param buffer [String] mutable buffer of accumulated stderr bytes
+    # @return [void]
+    def flush_stderr_lines(buffer)
+      while (newline_index = buffer.index("\n"))
+        line = buffer.slice!(0, newline_index + 1)
+        @logger.debug("[stderr] #{line.chomp}")
+      end
+    end
+
+    # Flush an unterminated stderr fragment that has grown past the size cap,
+    # so a newline-less stderr stream cannot buffer without bound.
+    # @param buffer [String] mutable buffer of accumulated stderr bytes
+    # @return [void]
+    def flush_stderr_overflow(buffer)
+      return if buffer.bytesize <= STDERR_MAX_LINE_SIZE
+
+      @logger.debug("[stderr] #{buffer}")
+      buffer.clear
+    end
+
     # 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
       # Clean up resources during unexpected termination
     ensure
-      @stdin = @stdout = @stderr = @wait_thread = @reader_thread = nil
+      # Release any buffered responses / awaiting markers
+      @mutex.synchronize do
+        @pending.clear
+        @awaiting.clear
+      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