ruby-mcp-client 1.0.0 → 1.1.0

data/lib/mcp_client/auth.rb

@@ -86,21 +86,38 @@ module MCPClient
 
     # OAuth client metadata for registration and authorization
     class ClientMetadata
-      attr_reader :redirect_uris, :token_endpoint_auth_method, :grant_types, :response_types, :scope
+      attr_reader :redirect_uris, :token_endpoint_auth_method, :grant_types, :response_types, :scope,
+                  :client_name, :client_uri, :logo_uri, :tos_uri, :policy_uri, :contacts
 
       # @param redirect_uris [Array<String>] List of valid redirect URIs
       # @param token_endpoint_auth_method [String] Authentication method for token endpoint
       # @param grant_types [Array<String>] Supported grant types
       # @param response_types [Array<String>] Supported response types
       # @param scope [String, nil] Requested scope
+      # @param client_name [String, nil] Human-readable client name
+      # @param client_uri [String, nil] URL of the client home page
+      # @param logo_uri [String, nil] URL of the client logo
+      # @param tos_uri [String, nil] URL of the client terms of service
+      # @param policy_uri [String, nil] URL of the client privacy policy
+      # @param contacts [Array<String>, nil] List of contact emails for the client
+      # rubocop:disable Metrics/ParameterLists
       def initialize(redirect_uris:, token_endpoint_auth_method: 'none',
                      grant_types: %w[authorization_code refresh_token],
-                     response_types: ['code'], scope: nil)
+                     response_types: ['code'], scope: nil,
+                     client_name: nil, client_uri: nil, logo_uri: nil,
+                     tos_uri: nil, policy_uri: nil, contacts: nil)
+        # rubocop:enable Metrics/ParameterLists
         @redirect_uris = redirect_uris
         @token_endpoint_auth_method = token_endpoint_auth_method
         @grant_types = grant_types
         @response_types = response_types
         @scope = scope
+        @client_name = client_name
+        @client_uri = client_uri
+        @logo_uri = logo_uri
+        @tos_uri = tos_uri
+        @policy_uri = policy_uri
+        @contacts = contacts
       end
 
       # Convert to hash for HTTP requests
@@ -111,7 +128,13 @@ module MCPClient
           token_endpoint_auth_method: @token_endpoint_auth_method,
           grant_types: @grant_types,
           response_types: @response_types,
-          scope: @scope
+          scope: @scope,
+          client_name: @client_name,
+          client_uri: @client_uri,
+          logo_uri: @logo_uri,
+          tos_uri: @tos_uri,
+          policy_uri: @policy_uri,
+          contacts: @contacts
         }.compact
       end
     end
@@ -180,7 +203,13 @@ module MCPClient
           grant_types: metadata_data[:grant_types] || metadata_data['grant_types'] ||
                        %w[authorization_code refresh_token],
           response_types: metadata_data[:response_types] || metadata_data['response_types'] || ['code'],
-          scope: metadata_data[:scope] || metadata_data['scope']
+          scope: metadata_data[:scope] || metadata_data['scope'],
+          client_name: metadata_data[:client_name] || metadata_data['client_name'],
+          client_uri: metadata_data[:client_uri] || metadata_data['client_uri'],
+          logo_uri: metadata_data[:logo_uri] || metadata_data['logo_uri'],
+          tos_uri: metadata_data[:tos_uri] || metadata_data['tos_uri'],
+          policy_uri: metadata_data[:policy_uri] || metadata_data['policy_uri'],
+          contacts: metadata_data[:contacts] || metadata_data['contacts']
         )
       end
 
@@ -196,7 +225,8 @@ module MCPClient
     # OAuth authorization server metadata
     class ServerMetadata
       attr_reader :issuer, :authorization_endpoint, :token_endpoint, :registration_endpoint,
-                  :scopes_supported, :response_types_supported, :grant_types_supported
+                  :scopes_supported, :response_types_supported, :grant_types_supported,
+                  :code_challenge_methods_supported
 
       # @param issuer [String] Issuer identifier URL
       # @param authorization_endpoint [String] Authorization endpoint URL
@@ -205,8 +235,10 @@ module MCPClient
       # @param scopes_supported [Array<String>, nil] Supported OAuth scopes
       # @param response_types_supported [Array<String>, nil] Supported response types
       # @param grant_types_supported [Array<String>, nil] Supported grant types
+      # @param code_challenge_methods_supported [Array<String>, nil] Supported PKCE code challenge methods (RFC 8414)
       def initialize(issuer:, authorization_endpoint:, token_endpoint:, registration_endpoint: nil,
-                     scopes_supported: nil, response_types_supported: nil, grant_types_supported: nil)
+                     scopes_supported: nil, response_types_supported: nil, grant_types_supported: nil,
+                     code_challenge_methods_supported: nil)
         @issuer = issuer
         @authorization_endpoint = authorization_endpoint
         @token_endpoint = token_endpoint
@@ -214,6 +246,7 @@ module MCPClient
         @scopes_supported = scopes_supported
         @response_types_supported = response_types_supported
         @grant_types_supported = grant_types_supported
+        @code_challenge_methods_supported = code_challenge_methods_supported
       end
 
       # Check if dynamic client registration is supported
@@ -232,7 +265,8 @@ module MCPClient
           registration_endpoint: @registration_endpoint,
           scopes_supported: @scopes_supported,
           response_types_supported: @response_types_supported,
-          grant_types_supported: @grant_types_supported
+          grant_types_supported: @grant_types_supported,
+          code_challenge_methods_supported: @code_challenge_methods_supported
         }.compact
       end
 
@@ -247,7 +281,9 @@ module MCPClient
           registration_endpoint: data[:registration_endpoint] || data['registration_endpoint'],
           scopes_supported: data[:scopes_supported] || data['scopes_supported'],
           response_types_supported: data[:response_types_supported] || data['response_types_supported'],
-          grant_types_supported: data[:grant_types_supported] || data['grant_types_supported']
+          grant_types_supported: data[:grant_types_supported] || data['grant_types_supported'],
+          code_challenge_methods_supported: data[:code_challenge_methods_supported] ||
+            data['code_challenge_methods_supported']
         )
       end
     end
@@ -288,10 +324,41 @@ module MCPClient
       attr_reader :code_verifier, :code_challenge, :code_challenge_method
 
       # Generate PKCE parameters
-      def initialize
-        @code_verifier = generate_code_verifier
-        @code_challenge = generate_code_challenge(@code_verifier)
-        @code_challenge_method = 'S256'
+      # @param code_verifier [String, nil] Existing code verifier (for deserialization)
+      # @param code_challenge [String, nil] Existing code challenge (for deserialization)
+      # @param code_challenge_method [String] Challenge method (default: 'S256')
+      def initialize(code_verifier: nil, code_challenge: nil, code_challenge_method: nil)
+        @code_verifier = code_verifier || generate_code_verifier
+        @code_challenge = code_challenge || generate_code_challenge(@code_verifier)
+        @code_challenge_method = code_challenge_method || 'S256'
+      end
+
+      # Convert to hash for serialization
+      # @return [Hash] Hash representation
+      def to_h
+        {
+          code_verifier: @code_verifier,
+          code_challenge: @code_challenge,
+          code_challenge_method: @code_challenge_method
+        }
+      end
+
+      # Create PKCE instance from hash
+      # @param data [Hash] Hash with PKCE parameters (symbol or string keys)
+      # @return [PKCE] New PKCE instance
+      # @raise [ArgumentError] If required parameters are missing
+      # @note code_challenge_method is optional and defaults to 'S256'.
+      #   The code_challenge is not re-validated against code_verifier;
+      #   callers are expected to provide values from a prior to_h round-trip.
+      def self.from_h(data)
+        verifier = data[:code_verifier] || data['code_verifier']
+        challenge = data[:code_challenge] || data['code_challenge']
+        method = data[:code_challenge_method] || data['code_challenge_method']
+
+        raise ArgumentError, 'Missing code_verifier' unless verifier
+        raise ArgumentError, 'Missing code_challenge' unless challenge
+
+        new(code_verifier: verifier, code_challenge: challenge, code_challenge_method: method)
       end
 
       private

data/lib/mcp_client/client.rb

@@ -27,9 +27,18 @@ module MCPClient
     # @param roots [Array<MCPClient::Root, Hash>, nil] optional list of roots (MCP 2025-06-18)
     # @param sampling_handler [Proc, nil] optional handler for sampling requests (MCP 2025-11-25)
     def initialize(mcp_server_configs: [], logger: nil, elicitation_handler: nil, roots: nil, sampling_handler: nil)
-      @logger = logger || Logger.new($stdout, level: Logger::WARN)
-      @logger.progname = self.class.name
-      @logger.formatter = proc { |severity, _datetime, progname, msg| "#{severity} [#{progname}] #{msg}\n" }
+      # Preserve a caller-supplied logger's formatter (only tag progname), and
+      # install the default formatter solely on a logger we create ourselves.
+      # Overwriting the formatter of an application's logger would silently
+      # reformat every log line it emits elsewhere.
+      if logger
+        @logger = logger
+        @logger.progname = self.class.name
+      else
+        @logger = Logger.new($stdout, level: Logger::WARN)
+        @logger.progname = self.class.name
+        @logger.formatter = proc { |severity, _datetime, progname, msg| "#{severity} [#{progname}] #{msg}\n" }
+      end
       @servers = mcp_server_configs.map do |config|
         @logger.debug("Creating server with config: #{config.inspect}")
         MCPClient::ServerFactory.create(config, logger: @logger)
@@ -281,6 +290,7 @@ module MCPClient
 
       # Validate parameters against tool schema
       validate_params!(tool, parameters)
+      reject_task_required!(tool, tool_name)
 
       # Use the tool's associated server
       server = tool.server
@@ -426,6 +436,7 @@ module MCPClient
 
       # Validate parameters against tool schema
       validate_params!(tool, parameters)
+      reject_task_required!(tool, tool_name)
 
       # Use the tool's associated server
       server = tool.server
@@ -497,32 +508,59 @@ module MCPClient
       srv.complete(ref: ref, argument: argument, context: context)
     end
 
-    # Create a new task on a server (MCP 2025-11-25)
-    # Tasks represent long-running operations that can report progress
-    # @param method [String] the method to execute as a task
-    # @param params [Hash] parameters for the task method
-    # @param progress_token [String, nil] optional token for receiving progress notifications
-    # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
-    # @return [MCPClient::Task] the created task
-    # @raise [MCPClient::Errors::ServerNotFound] if no server is available
-    # @raise [MCPClient::Errors::TaskError] if task creation fails
-    def create_task(method, params: {}, progress_token: nil, server: nil)
-      srv = select_server(server)
-      rpc_params = { method: method, params: params }
-      rpc_params[:progressToken] = progress_token if progress_token
+    # Call a tool as a task (task-augmented tools/call, MCP 2025-11-25).
+    #
+    # Instead of blocking for the result, the server accepts the request and
+    # immediately returns a task handle; the actual result is retrieved later
+    # via {#get_task_result} once the task reaches a terminal status. The server
+    # must advertise the tasks.requests.tools.call capability, and the tool must
+    # declare execution.taskSupport of 'optional' or 'required'.
+    # @param tool_name [String] the name of the tool to call
+    # @param parameters [Hash] the parameters to pass to the tool
+    # @param ttl [Integer, nil] optional requested task lifetime in milliseconds
+    # @param server [String, Symbol, Integer, MCPClient::ServerBase, nil] optional server to use
+    # @return [MCPClient::Task] the created task (status typically 'working')
+    # @raise [MCPClient::Errors::ToolNotFound] if the tool is not found
+    # @raise [MCPClient::Errors::ValidationError] if required parameters are missing
+    # @raise [MCPClient::Errors::TaskError] if the server or tool does not support tasks, or creation fails
+    def call_tool_as_task(tool_name, parameters, ttl: nil, server: nil)
+      tool = resolve_tool(tool_name, server: server)
+      validate_params!(tool, parameters)
+
+      srv = tool.server
+      raise MCPClient::Errors::ServerNotFound, "No server found for tool '#{tool_name}'" unless srv
+
+      unless server_supports_task_tool_call?(srv)
+        raise MCPClient::Errors::TaskError,
+              'Server does not support task-augmented tools/call (no tasks.requests.tools.call capability)'
+      end
+      unless tool.supports_task?
+        raise MCPClient::Errors::TaskError,
+              "Tool '#{tool_name}' does not support task execution (execution.taskSupport is forbidden/unset)"
+      end
+
+      task_params = {}
+      task_params[:ttl] = ttl if ttl
+      # Keep _meta (string or symbol key) as a top-level request field rather
+      # than a tool argument, so request metadata is preserved and does not fail
+      # tool input-schema validation.
+      meta_key = [:_meta, '_meta'].find { |k| parameters.key?(k) }
+      arguments = meta_key ? parameters.reject { |k, _| k == meta_key } : parameters
+      rpc_params = { name: tool_name, arguments: arguments, task: task_params }
+      rpc_params[:_meta] = parameters[meta_key] if meta_key
 
       begin
-        result = srv.rpc_request('tasks/create', rpc_params)
-        MCPClient::Task.from_json(result, server: srv)
+        result = srv.rpc_request('tools/call', rpc_params)
+        MCPClient::Task.from_create_result(result, server: srv)
       rescue MCPClient::Errors::ServerError, MCPClient::Errors::TransportError, MCPClient::Errors::ConnectionError => e
-        raise MCPClient::Errors::TaskError, "Error creating task: #{e.message}"
+        raise MCPClient::Errors::TaskError, "Error creating task for tool '#{tool_name}': #{e.message}"
       end
     end
 
-    # Get the current state of a task (MCP 2025-11-25)
+    # Get the current state of a task (tasks/get, MCP 2025-11-25)
     # @param task_id [String] the ID of the task to query
     # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
-    # @return [MCPClient::Task] the task with current state
+    # @return [MCPClient::Task] the task with current status
     # @raise [MCPClient::Errors::ServerNotFound] if no server is available
     # @raise [MCPClient::Errors::TaskNotFound] if the task does not exist
     # @raise [MCPClient::Errors::TaskError] if retrieving the task fails
@@ -530,38 +568,75 @@ module MCPClient
       srv = select_server(server)
 
       begin
-        result = srv.rpc_request('tasks/get', { id: task_id })
+        result = srv.rpc_request('tasks/get', { taskId: task_id })
         MCPClient::Task.from_json(result, server: srv)
       rescue MCPClient::Errors::ServerError => e
-        if e.message.include?('not found') || e.message.include?('unknown task')
-          raise MCPClient::Errors::TaskNotFound, "Task '#{task_id}' not found"
-        end
-
-        raise MCPClient::Errors::TaskError, "Error getting task '#{task_id}': #{e.message}"
+        raise task_error_from(e, task_id, 'getting')
       rescue MCPClient::Errors::TransportError, MCPClient::Errors::ConnectionError => e
         raise MCPClient::Errors::TaskError, "Error getting task '#{task_id}': #{e.message}"
       end
     end
 
-    # Cancel a running task (MCP 2025-11-25)
+    # Retrieve the result of a completed task (tasks/result, MCP 2025-11-25).
+    # Returns exactly what the underlying request would have returned (e.g. a
+    # CallToolResult hash with 'content'/'isError'/'structuredContent'); it is
+    # NOT wrapped in a Task. Blocks on the server until the task is terminal.
+    # @param task_id [String] the ID of the task
+    # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
+    # @return [Object] the underlying task result
+    # @raise [MCPClient::Errors::TaskNotFound] if the task does not exist
+    # @raise [MCPClient::Errors::TaskError] if retrieval fails
+    def get_task_result(task_id, server: nil)
+      srv = select_server(server)
+
+      begin
+        srv.rpc_request('tasks/result', { taskId: task_id })
+      rescue MCPClient::Errors::ServerError => e
+        raise task_error_from(e, task_id, 'getting result for')
+      rescue MCPClient::Errors::TransportError, MCPClient::Errors::ConnectionError => e
+        raise MCPClient::Errors::TaskError, "Error getting result for task '#{task_id}': #{e.message}"
+      end
+    end
+
+    # List tasks known to a server (tasks/list, paginated, MCP 2025-11-25)
+    # @param cursor [String, nil] optional pagination cursor
+    # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
+    # @return [Hash] { tasks: Array<MCPClient::Task>, next_cursor: String, nil }
+    # @raise [MCPClient::Errors::TaskError] if listing fails
+    def list_tasks(cursor: nil, server: nil)
+      srv = select_server(server)
+      params = cursor ? { cursor: cursor } : {}
+
+      begin
+        result = srv.rpc_request('tasks/list', params) || {}
+        tasks = (result['tasks'] || []).map { |t| MCPClient::Task.from_json(t, server: srv) }
+        { tasks: tasks, next_cursor: result['nextCursor'] }
+      rescue MCPClient::Errors::ServerError, MCPClient::Errors::TransportError, MCPClient::Errors::ConnectionError => e
+        raise MCPClient::Errors::TaskError, "Error listing tasks: #{e.message}"
+      end
+    end
+
+    # Cancel a task (tasks/cancel, MCP 2025-11-25)
     # @param task_id [String] the ID of the task to cancel
     # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
-    # @return [MCPClient::Task] the task with updated (cancelled) state
+    # @return [MCPClient::Task] the task with updated (cancelled) status
     # @raise [MCPClient::Errors::ServerNotFound] if no server is available
     # @raise [MCPClient::Errors::TaskNotFound] if the task does not exist
-    # @raise [MCPClient::Errors::TaskError] if cancellation fails
+    # @raise [MCPClient::Errors::TaskError] if cancellation fails (including cancelling a terminal task)
     def cancel_task(task_id, server: nil)
       srv = select_server(server)
 
       begin
-        result = srv.rpc_request('tasks/cancel', { id: task_id })
+        result = srv.rpc_request('tasks/cancel', { taskId: task_id })
         MCPClient::Task.from_json(result, server: srv)
       rescue MCPClient::Errors::ServerError => e
-        if e.message.include?('not found') || e.message.include?('unknown task')
-          raise MCPClient::Errors::TaskNotFound, "Task '#{task_id}' not found"
+        # A terminal task cannot be cancelled (-32602); that is an error, not a
+        # missing task, so keep it as a TaskError.
+        if e.message.match?(/terminal/i)
+          raise MCPClient::Errors::TaskError, "Error cancelling task '#{task_id}': #{e.message}"
         end
 
-        raise MCPClient::Errors::TaskError, "Error cancelling task '#{task_id}': #{e.message}"
+        raise task_error_from(e, task_id, 'cancelling')
       rescue MCPClient::Errors::TransportError, MCPClient::Errors::ConnectionError => e
         raise MCPClient::Errors::TaskError, "Error cancelling task '#{task_id}': #{e.message}"
       end
@@ -601,6 +676,9 @@ module MCPClient
       when 'notifications/message'
         # MCP 2025-06-18: Handle logging messages from server
         handle_log_message(server_id, params)
+      when 'notifications/tasks/status'
+        # MCP 2025-11-25: task status update (params are a flat Task)
+        handle_task_status_notification(server_id, params)
       else
         # Log unknown notification types for debugging purposes
         logger.debug("[#{server_id}] Received unknown notification: #{method} - #{params}")
@@ -700,6 +778,91 @@ module MCPClient
       end
     end
 
+    # Resolve a tool by name (optionally scoped to a server), raising the same
+    # not-found / ambiguity errors as call_tool.
+    # @param tool_name [String] the tool name
+    # @param server [String, Symbol, Integer, MCPClient::ServerBase, nil] optional server selector
+    # @return [MCPClient::Tool] the resolved tool
+    # @raise [MCPClient::Errors::ToolNotFound, MCPClient::Errors::AmbiguousToolName]
+    def resolve_tool(tool_name, server: nil)
+      tools = list_tools
+
+      if server
+        srv = select_server(server)
+        tool = tools.find { |t| t.name == tool_name && t.server == srv }
+        unless tool
+          raise MCPClient::Errors::ToolNotFound,
+                "Tool '#{tool_name}' not found on server '#{srv.name || srv.class.name}'"
+        end
+        return tool
+      end
+
+      matching_tools = tools.select { |t| t.name == tool_name }
+      if matching_tools.empty?
+        raise MCPClient::Errors::ToolNotFound, "Tool '#{tool_name}' not found"
+      elsif matching_tools.size > 1
+        server_names = matching_tools.map { |t| t.server&.name || 'unnamed' }
+        raise MCPClient::Errors::AmbiguousToolName,
+              "Multiple tools named '#{tool_name}' found across servers (#{server_names.join(', ')}). " \
+              "Please specify a server using the 'server' parameter."
+      end
+
+      matching_tools.first
+    end
+
+    # Reject a plain (synchronous) call for a tool whose execution.taskSupport is
+    # 'required'. A compliant server would reject a non-task-augmented tools/call
+    # for such a tool, so fail fast and point the caller at call_tool_as_task.
+    # @param tool [MCPClient::Tool] the resolved tool
+    # @param tool_name [String] the tool name (for the message)
+    # @raise [MCPClient::Errors::ToolCallError] if the tool requires task execution
+    def reject_task_required!(tool, tool_name)
+      return unless tool.task_required?
+
+      raise MCPClient::Errors::ToolCallError,
+            "Tool '#{tool_name}' requires task-augmented execution; call it with call_tool_as_task instead"
+    end
+
+    # Whether a server advertised support for task-augmented tools/call, i.e.
+    # capabilities.tasks.requests.tools.call.
+    # @param srv [MCPClient::ServerBase] the server
+    # @return [Boolean]
+    def server_supports_task_tool_call?(srv)
+      caps = srv.respond_to?(:capabilities) ? srv.capabilities : nil
+      return false unless caps.is_a?(Hash)
+
+      tasks = caps['tasks'] || caps[:tasks]
+      requests = tasks && (tasks['requests'] || tasks[:requests])
+      tools = requests && (requests['tools'] || requests[:tools])
+      call = tools && (tools['call'] || tools[:call])
+      !call.nil?
+    end
+
+    # Map a ServerError from a task operation to TaskNotFound or TaskError.
+    # @param error [MCPClient::Errors::ServerError] the server error
+    # @param task_id [String] the task id
+    # @param action [String] a verb phrase for the error message (e.g. 'getting')
+    # @return [MCPClient::Errors::TaskNotFound, MCPClient::Errors::TaskError]
+    def task_error_from(error, task_id, action)
+      if error.message.match?(/not found|unknown task|expired/i)
+        return MCPClient::Errors::TaskNotFound.new("Task '#{task_id}' not found")
+      end
+
+      MCPClient::Errors::TaskError.new("Error #{action} task '#{task_id}': #{error.message}")
+    end
+
+    # Handle a notifications/tasks/status notification (MCP 2025-11-25).
+    # The params are a flat Task.
+    # @param server_id [String] server identifier for the log prefix
+    # @param params [Hash] the flat task params
+    # @return [void]
+    def handle_task_status_notification(server_id, params)
+      task = MCPClient::Task.from_json(params)
+      logger.info("[#{server_id}] Task #{task.task_id} status: #{task.status}")
+    rescue StandardError => e
+      logger.debug("[#{server_id}] Failed to parse task status notification: #{e.message}")
+    end
+
     # Generate a cache key for server-specific items
     # @param server [MCPClient::ServerBase] the server
     # @param item_id [String] the item identifier (name or URI)

data/lib/mcp_client/errors.rb

@@ -33,6 +33,15 @@ module MCPClient
     # Raised when the MCP server returns an error response
     class ServerError < MCPError; end
 
+    # Raised for a server-side failure that is plausibly transient and safe to
+    # retry — chiefly HTTP 5xx responses, where the request likely did not
+    # complete at the application layer. It is a subclass of ServerError so that
+    # existing `rescue MCPClient::Errors::ServerError` handlers keep catching it,
+    # while the retry logic can single it out. Application-level failures
+    # (JSON-RPC error responses, HTTP 4xx) use plain ServerError and are NOT
+    # retried, since the server already processed/rejected the request.
+    class TransientServerError < ServerError; end
+
     # Raised when there's an error in the MCP server transport
     class TransportError < MCPError; end
 

data/lib/mcp_client/http_transport_base.rb

@@ -243,9 +243,13 @@ module MCPClient
       when 401, 403
         raise MCPClient::Errors::ConnectionError, "Authorization failed: HTTP #{response.status}"
       when 400..499
+        # Deterministic client errors: the request was processed/rejected and
+        # will not succeed on retry, so raise a plain (non-retryable) ServerError.
         raise MCPClient::Errors::ServerError, "Client error: HTTP #{response.status}#{reason_text}"
       when 500..599
-        raise MCPClient::Errors::ServerError, "Server error: HTTP #{response.status}#{reason_text}"
+        # Server-side failures are plausibly transient: raise the retryable
+        # subclass so with_retry can re-attempt them.
+        raise MCPClient::Errors::TransientServerError, "Server error: HTTP #{response.status}#{reason_text}"
       else
         raise MCPClient::Errors::ServerError, "HTTP error: #{response.status}#{reason_text}"
       end

data/lib/mcp_client/json_rpc_common.rb

@@ -3,16 +3,26 @@
 module MCPClient
   # Shared retry/backoff logic for JSON-RPC transports
   module JsonRpcCommon
-    # Execute the block with retry/backoff for transient errors
+    # Execute the block with retry/backoff for transient errors only.
+    #
+    # Retries genuinely transient failures where the request most likely did not
+    # complete at the server: transport/network errors (TransportError, IOError,
+    # Errno::ETIMEDOUT/ECONNRESET/EPIPE) and TransientServerError (HTTP 5xx).
+    #
+    # It deliberately does NOT retry a plain ServerError. A plain ServerError is
+    # raised for a JSON-RPC error response or an HTTP 4xx — cases where the
+    # server received and processed (or deterministically rejected) the request.
+    # Re-sending those would silently re-execute a non-idempotent operation
+    # (e.g. a tools/call), which JSON-RPC provides no way to make safe.
     # @yield block to execute
     # @return [Object] result of block
-    # @raise original exception if max retries exceeded
+    # @raise original exception if max retries exceeded or the error is not retryable
     def with_retry
       attempts = 0
       begin
         yield
-      rescue MCPClient::Errors::ServerError, MCPClient::Errors::TransportError, IOError, Errno::ETIMEDOUT,
-             Errno::ECONNRESET => e
+      rescue MCPClient::Errors::TransientServerError, MCPClient::Errors::TransportError, IOError,
+             Errno::ETIMEDOUT, Errno::ECONNRESET, Errno::EPIPE => e
         attempts += 1
         if attempts <= @max_retries
           delay = @retry_backoff * (2**(attempts - 1))
@@ -66,6 +76,11 @@ module MCPClient
         'elicitation' => {}, # MCP 2025-11-25: Support for server-initiated user interactions
         'roots' => { 'listChanged' => true }, # MCP 2025-11-25: Support for roots
         'sampling' => {} # MCP 2025-11-25: Support for server-initiated LLM sampling
+        # NOTE: we intentionally do NOT declare a client `tasks` capability. That
+        # capability marks the client as a RECEIVER of task-augmented
+        # sampling/elicitation requests, which is not implemented here — this
+        # client only acts as a task REQUESTOR for tools/call (see
+        # Client#call_tool_as_task), which requires no client-side declaration.
       }
 
       {

data/lib/mcp_client/server_base.rb

@@ -133,8 +133,81 @@ module MCPClient
       @notification_callback = block
     end
 
+    # Safety bound on the number of pages followed when auto-paginating a
+    # cursor-based list operation, to protect against a server that returns
+    # a nextCursor indefinitely.
+    MAX_LIST_PAGES = 1000
+
     protected
 
+    # Follow cursor-based pagination across pages, collecting every item.
+    #
+    # Yields the current cursor (nil for the first page) and expects the block
+    # to return a two-element array: [items_for_this_page, next_cursor]. The
+    # loop stops when next_cursor is nil or empty, when a cursor repeats
+    # (malformed server), or when MAX_LIST_PAGES pages have been fetched.
+    #
+    # @param kind [String] label used in diagnostic log messages
+    # @yieldparam cursor [String, nil] cursor for the page to fetch
+    # @yieldreturn [Array(Array, String), Array(Array, nil)] page items and next cursor
+    # @return [Array] all items collected across pages
+    def collect_paginated(kind = 'items')
+      items = []
+      cursor = nil
+      seen_cursors = {}
+      pages = 0
+
+      loop do
+        page_items, next_cursor = yield(cursor)
+        items.concat(Array(page_items))
+        pages += 1
+
+        break if next_cursor.nil? || next_cursor.to_s.empty?
+
+        if seen_cursors[next_cursor]
+          @logger.warn("Pagination for #{kind} stopped: server returned a repeated cursor #{next_cursor.inspect}")
+          break
+        end
+        if pages >= MAX_LIST_PAGES
+          @logger.warn("Pagination for #{kind} stopped after #{pages} pages (safety bound reached)")
+          break
+        end
+
+        seen_cursors[next_cursor] = true
+        cursor = next_cursor
+      end
+
+      items
+    end
+
+    # Fetch a full, cursor-paginated list result via rpc_request, following
+    # nextCursor across pages until the server stops returning one.
+    #
+    # Accepts either a spec-shaped Hash ({ key => [...], 'nextCursor' => ... })
+    # or, leniently, a bare Array (a single unpaginated page). A response that
+    # is neither (e.g. a null/missing result or a scalar) is a malformed list
+    # response and raises, rather than being silently treated as an empty list.
+    #
+    # @param method [String] the list method, e.g. 'tools/list'
+    # @param key [String] the result array key, e.g. 'tools'
+    # @return [Array<Hash>] all raw item hashes collected across pages
+    # @raise [MCPClient::Errors::TransportError] if a page result is not a Hash or Array
+    def request_paginated_list(method, key)
+      collect_paginated(key) do |cursor|
+        params = cursor ? { cursor: cursor } : {}
+        result = rpc_request(method, params)
+        case result
+        when Hash
+          [result[key] || [], result['nextCursor']]
+        when Array
+          [result, nil]
+        else
+          raise MCPClient::Errors::TransportError,
+                "Invalid #{method} response: expected an object or array, got #{result.class}"
+        end
+      end
+    end
+
     # Initialize logger with proper formatter handling
     # Preserves custom formatter if logger is provided, otherwise sets a default formatter
     # @param logger [Logger, nil] custom logger to use, or nil to create a default one