ruby-mcp-client 2.1.0 → 3.0.0

data/lib/mcp_client/input_round_trips.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
+module MCPClient
+  # Fulfilment of the input requests an `input_required` result carries
+  # (MCP 2026-07-28 multi-round tool requests). Mixed into
+  # {MCPClient::JsonRpcCommon}, whose host supplies the registered handlers.
+  module InputRoundTrips
+    # Input request methods and the transport callback that fulfils each.
+    INPUT_REQUEST_HANDLERS = {
+      'elicitation/create' => :@elicitation_request_callback,
+      'sampling/createMessage' => :@sampling_request_callback,
+      'roots/list' => :@roots_list_request_callback
+    }.freeze
+
+    # Fulfil every input request through the handler registered for its
+    # method. There is no per-key error channel in InputResponses, so any
+    # request this client cannot honour fails the whole round trip.
+    #
+    # The answers produced before the failure travel with the error
+    # ({MCPClient::Errors::InputRequiredError#answered_so_far}): a request the
+    # host already answered has been put to a person, and a caller that can
+    # keep it — the tasks extension's poll loop — must not ask them again.
+    # @param input_requests [Hash] the InputRequests map
+    # @param result [Hash] the InputRequiredResult (for error data)
+    # @return [Hash] the InputResponses map
+    # @raise [MCPClient::Errors::InputRequiredError]
+    def fulfil_input_requests(input_requests, result)
+      unless input_requests.is_a?(Hash)
+        raise MCPClient::Errors::InputRequiredError.new('Malformed InputRequiredResult: inputRequests is not an object',
+                                                        data: result)
+      end
+
+      responses = {}
+      input_requests.each do |key, request|
+        responses[key] = fulfil_input_request(key, request, result)
+      rescue MCPClient::Errors::InputRequiredError => e
+        raise e.with_answered_so_far(responses)
+      end
+      responses
+    end
+
+    # @param key [String] the server-assigned request key
+    # @param request [Hash] the input request ({ 'method' => ..., 'params' => ... })
+    # @param result [Hash] the InputRequiredResult (for error data)
+    # @return [Hash] the handler's result
+    # @raise [MCPClient::Errors::InputRequiredError]
+    def fulfil_input_request(key, request, result)
+      shown_key = sanitize_log_text(key.to_s.inspect)
+      unless request.is_a?(Hash) && request['method'].is_a?(String) &&
+             (request['params'].nil? || request['params'].is_a?(Hash))
+        raise MCPClient::Errors::InputRequiredError.new("Malformed input request #{shown_key} (method/params)",
+                                                        data: result)
+      end
+
+      request_method = request['method']
+      shown_method = sanitize_log_text(request_method.inspect)
+      handler_ivar = INPUT_REQUEST_HANDLERS[request_method]
+      unless handler_ivar
+        raise MCPClient::Errors::InputRequiredError.new(
+          "Unsupported input request method #{shown_method} for key #{shown_key}", data: result
+        )
+      end
+      unless registered_callback?(handler_ivar)
+        raise MCPClient::Errors::InputRequiredError.new(
+          "Server requested #{shown_method} (key #{shown_key}) but no handler is registered for it " \
+          '(the capability was not declared)', data: result
+        )
+      end
+
+      # The handler this reaches is the same callback a legacy
+      # server-initiated request would have used, so Roots and Sampling are
+      # just as deprecated here (SEP-2577). The notice precedes the
+      # sampling.tools refusal below, as it precedes the handler's own
+      # -32602 on the server-initiated path: the deprecated values were on
+      # the wire and a host with a handler asked for them, whichever
+      # sub-capability the request then trips over.
+      warn_input_request_deprecated(request_method, request['params'])
+      if undeclared_sampling_tool_use?(request_method, request['params'])
+        raise MCPClient::Errors::InputRequiredError.new(
+          "Server requested tool-enabled #{shown_method} (key #{shown_key}) but the sampling.tools " \
+          'capability was not declared', data: result
+        )
+      end
+
+      begin
+        response = instance_variable_get(handler_ivar).call(key, request['params'] || {})
+      rescue StandardError => e
+        # The exception text is host-internal; it stays in the local log.
+        @logger.error("Handler for #{shown_method} (key #{shown_key}) raised: #{e.message}")
+        raise MCPClient::Errors::InputRequiredError.new(
+          "Handler for #{shown_method} (key #{shown_key}) failed", data: result
+        )
+      end
+      unless response.is_a?(Hash)
+        raise MCPClient::Errors::InputRequiredError.new(
+          "Handler for #{shown_method} (key #{shown_key}) returned #{response.class}, expected a result object",
+          data: result
+        )
+      end
+      if (error = response['error'] || response[:error])
+        message = error.is_a?(Hash) ? (error['message'] || error[:message]) : error
+        raise MCPClient::Errors::InputRequiredError.new(
+          "Handler for #{shown_method} (key #{shown_key}) failed: #{sanitize_log_text(message)}", data: result
+        )
+      end
+
+      warn_input_request_answer_deprecated(request_method, response)
+      response
+    end
+
+    # SEP-1577 (sampling tool calling): a server MUST NOT send `tools` or
+    # `toolChoice` to a client that did not declare the sampling.tools
+    # sub-capability. On a server-initiated request the client answers -32602;
+    # InputResponses has no per-request error channel, so on the multi
+    # round-trip path the whole round trip fails instead — the sampler is
+    # never invoked with a request this client never advertised support for.
+    # @param method [String] the input request method
+    # @param params [Hash, nil] the input request params
+    # @return [Boolean] whether this is tool-enabled sampling without the declaration
+    def undeclared_sampling_tool_use?(method, params)
+      return false unless method == 'sampling/createMessage' && !sampling_tools_supported?
+
+      params.is_a?(Hash) && (params.key?('tools') || params.key?('toolChoice'))
+    end
+  end
+end

data/lib/mcp_client/json_rpc_common/envelopes.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module MCPClient
+  module JsonRpcCommon
+    # Reading the members of a decoded JSON-RPC envelope. A host's JSON
+    # middleware may hand the envelope over keyed by Symbol, and its members
+    # are the peer's rather than the host's, so both spellings name the same
+    # thing. Mixed into {MCPClient::JsonRpcCommon}; private there.
+    module Envelopes
+      private
+
+      # Read a member of a decoded JSON-RPC envelope.
+      #
+      # The README offers Faraday's JSON middleware for reading a server's error
+      # bodies, and that middleware decodes every response — under
+      # `symbolize_names` the envelope arrives keyed by Symbol. The members are
+      # the peer's, not the host's, so both spellings name the same thing: read
+      # the wire spelling first and fall back to the Symbol one. Anything that
+      # is no Hash is indexed as before, so a malformed envelope fails where it
+      # always did.
+      # @param response [Object] the decoded JSON-RPC envelope
+      # @param name [String] the member's name in its wire spelling
+      # @return [Object, nil] the member, or nil when the envelope carries none
+      def envelope_member(response, name)
+        return response[name] unless response.is_a?(Hash)
+        return response[name] if response.key?(name)
+
+        response[name.to_sym]
+      end
+    end
+  end
+end

data/lib/mcp_client/json_rpc_common/error_bodies.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'zlib'
+require 'stringio'
+
+module MCPClient
+  module JsonRpcCommon
+    # Reading a JSON-RPC error object out of an HTTP error response body,
+    # bounded in size and inflated only within that bound. Mixed into
+    # {MCPClient::JsonRpcCommon}, so every transport that includes it has
+    # these helpers.
+    module ErrorBodies
+      # Build the error for a 4xx response: the typed JSON-RPC error when the
+      # body is a JSON-RPC error response (with the HTTP status prefixed to the
+      # peer's message), otherwise a plain ServerError with the fallback text.
+      # @param response [Faraday::Response] the 4xx response
+      # @param fallback [String] message when the body carries no JSON-RPC error
+      # @return [MCPClient::Errors::ServerError]
+      def jsonrpc_error_from_http_response(response, fallback)
+        status = response.status
+        error = jsonrpc_error_in_body(response)
+        return MCPClient::Errors::ServerError.new(fallback).tap { |e| e.http_status = status } unless error
+
+        typed = MCPClient::Errors::ServerError.from_jsonrpc(error)
+        typed.class.new("#{fallback}: #{typed.message}", code: typed.code, data: typed.data)
+             .tap { |e| e.http_status = status }
+      end
+
+      # Ceiling on the size of an HTTP error body inspected for a JSON-RPC
+      # error. A protocol error response is a few hundred bytes; the body is
+      # peer-controlled, so anything larger is not parsed at all rather than
+      # handed to JSON.parse.
+      MAX_ERROR_BODY_BYTES = 64 * 1024
+
+      # Extract a JSON-RPC error object from an HTTP error body, if there is one.
+      # Only a JSON-RPC 2.0 error response is recognized; anything else is
+      # ignored.
+      # @param response [Faraday::Response] the HTTP response
+      # @return [Hash, nil] the JSON-RPC `error` member, or nil
+      def jsonrpc_error_in_body(response)
+        return nil unless response.respond_to?(:body)
+
+        data = decoded_error_body(response)
+        # Only a JSON-RPC 2.0 error response counts; an arbitrary JSON body
+        # with an "error" member is not a protocol error.
+        return nil unless data.is_a?(Hash) && (data['jsonrpc'] || data[:jsonrpc]) == '2.0'
+
+        error = data['error'] || data[:error]
+        error.is_a?(Hash) ? error : nil
+      end
+
+      # The error body as a decoded object.
+      #
+      # A host may configure the connection (faraday_config) with response
+      # middleware — `conn.response :json` — that decodes the body before it
+      # reaches this transport, on the exception path (`raise_error`) as well
+      # as the response path. That already-parsed body carries the same
+      # protocol error, so it is accepted as-is; only a raw String body is
+      # size-bounded, gunzipped and parsed here (the middleware has already
+      # spent the memory for the ones it decoded).
+      # @param response [Faraday::Response] the HTTP response
+      # @return [Object, nil] the decoded body, or nil when it cannot be read
+      def decoded_error_body(response)
+        body = response.body
+        return body if body.is_a?(Hash)
+        return nil unless body.is_a?(String) && !body.empty?
+        return nil if oversized_error_body?(body)
+
+        headers = response.respond_to?(:headers) ? response.headers || {} : {}
+        encoding = headers['content-encoding'] || headers['Content-Encoding'] || ''
+        body = gunzip_bounded(body) if encoding.include?('gzip')
+        return nil if body.nil?
+
+        JSON.parse(body)
+      rescue JSON::ParserError, Zlib::Error => e
+        @logger.debug("HTTP error body is not a JSON-RPC error: #{e.class}")
+        nil
+      end
+
+      # @param body [String] an HTTP error body
+      # @return [Boolean] whether it exceeds the inspection ceiling (logged)
+      def oversized_error_body?(body)
+        return false if body.bytesize <= MAX_ERROR_BODY_BYTES
+
+        @logger.debug("Ignoring HTTP error body of #{body.bytesize} bytes (over #{MAX_ERROR_BODY_BYTES})")
+        true
+      end
+
+      # Decompress a gzip error body, giving up once the expansion passes the
+      # inspection ceiling (a compressed 4xx body is peer-controlled too).
+      # @param body [String] gzip data
+      # @return [String, nil] the decompressed body, or nil when too large
+      def gunzip_bounded(body)
+        reader = Zlib::GzipReader.new(StringIO.new(body))
+        expanded = reader.read(MAX_ERROR_BODY_BYTES + 1) || ''
+        return expanded if expanded.bytesize <= MAX_ERROR_BODY_BYTES
+
+        @logger.debug("Ignoring gzip HTTP error body expanding past #{MAX_ERROR_BODY_BYTES} bytes")
+        nil
+      ensure
+        reader&.close
+      end
+    end
+  end
+end

data/lib/mcp_client/json_rpc_common/input_waits.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module MCPClient
+  module JsonRpcCommon
+    # The host's hand on a multi round-trip request that waits on an
+    # interaction happening out of band (MCP 2026-07-28 client/elicitation
+    # "URL Mode": "Clients SHOULD provide manual controls that let the user
+    # retry or cancel the original request"): the pause before each retry of
+    # a requestState-only answer is the host's to steer, it never runs past
+    # the request timeout, and a stopped request resumes from the
+    # continuation its error carries. Mixed into {MCPClient::JsonRpcCommon}.
+    module InputWaits
+      # What the host is told before each paced retry of a continuation that
+      # asked for nothing (an out-of-band interaction still in progress): the
+      # request, how many round trips it has taken, the pause about to be
+      # taken, the server's requestState, the InputRequiredResult itself and
+      # the seconds spent waiting so far.
+      InputRequiredWait = Struct.new(:rpc_method, :round_trip, :delay, :request_state, :result, :elapsed,
+                                     keyword_init: true)
+
+      # An InputRequiredResult is defined only for tools/call, resources/read
+      # and prompts/get (MCP 2026-07-28 basic/patterns/mrtr "Supported
+      # Requests"). server/discover is not one of them, so an input_required
+      # discover answer is invalid and MUST NOT be applied or cached: the probe
+      # would otherwise adopt a protocol version out of an unfinished result
+      # and hand that result back as the first heartbeat. The rejection is a
+      # ModernServerError, not an InvalidResultError, because a server
+      # answering server/discover with a 2026-07-28-only discriminator is
+      # modern: the era is settled, so it must never be retried with the
+      # initialize handshake, and MCPClient.connect must not send it on to the
+      # legacy SSE and HTTP+POST transports either.
+      # @param result [Hash] the server/discover result
+      # @return [void]
+      # @raise [MCPClient::Errors::ModernServerError] if the result is an InputRequiredResult
+      def reject_input_required_discover!(result)
+        return unless MCPClient::JsonRpcCommon.result_type(result) == 'input_required'
+
+        raise MCPClient::Errors::ModernServerError,
+              'Server answered server/discover with an input_required result; multi round-trip requests are ' \
+              "only valid for #{MRTR_METHODS.join(', ')}"
+      end
+
+      # Register the host's control over an out-of-band wait (MCP 2026-07-28
+      # client/elicitation "URL Mode": "Clients SHOULD provide manual controls
+      # that let the user retry or cancel the original request"). The block is
+      # called with an {InputRequiredWait} before each paced retry of a
+      # continuation that asked for nothing; it returns `:retry` to retry at
+      # once, `:cancel` to stop with an {MCPClient::Errors::InputRequiredError}
+      # the host can hand to {#resume_input_required} later, or anything else
+      # to wait the pace and retry.
+      # @yieldparam wait [InputRequiredWait] the wait about to be paced
+      # @yieldreturn [Symbol, Object] :retry, :cancel, or anything else to wait
+      # @return [void]
+      def on_input_required_wait(&block)
+        @input_required_wait_callback = block
+      end
+
+      # Resume a multi round-trip request from the continuation an
+      # {MCPClient::Errors::InputRequiredError} carries: the original request
+      # goes out again as a new request with the server's requestState echoed
+      # and no inputResponses, and the round trip continues from there.
+      # @param error [MCPClient::Errors::InputRequiredError] a resumable error
+      # @param timeout [Numeric, nil] per-request timeout for the resumed request
+      # @return [Object] the final (complete) result
+      # @raise [ArgumentError] if the error carries no continuation
+      def resume_input_required(error, timeout: nil)
+        unless error.is_a?(MCPClient::Errors::InputRequiredError) && error.resumable?
+          raise ArgumentError, 'the error carries no continuation to resume'
+        end
+
+        params = error.request_params.is_a?(Hash) ? error.request_params.dup : {}
+        %w[inputResponses requestState].each do |key|
+          params.delete(key)
+          params.delete(key.to_sym)
+        end
+        params['requestState'] = error.request_state unless error.request_state.nil?
+        ensure_initialized if respond_to?(:ensure_initialized, true)
+        rpc_request(error.request_method, params, timeout: timeout)
+      end
+
+      private
+
+      # The params for a multi round-trip retry: the original params plus the
+      # fulfilled inputResponses and the server's requestState. Both fields
+      # affect only this retry; the caller's params are not mutated.
+      # @param params [Hash] the original params
+      # @param result [Hash] the InputRequiredResult
+      # @return [Hash]
+      def retry_params_for(params, result)
+        retry_params = (params.is_a?(Hash) ? params.dup : {})
+        retry_params.delete('inputResponses')
+        retry_params.delete(:inputResponses)
+        retry_params.delete('requestState')
+        retry_params.delete(:requestState)
+
+        if result.key?('inputRequests')
+          retry_params['inputResponses'] = fulfil_input_requests(result['inputRequests'], result)
+        end
+        state = result['requestState']
+        retry_params['requestState'] = state unless state.nil?
+        retry_params
+      end
+
+      # One pause of a continuation that asked for nothing, as the host steers
+      # it. Returns the pace for the next such pause.
+      #
+      # The host's control is host code: it may open a window, ask a person
+      # and come back much later. That time belongs to the request, so the
+      # deadline is read against the clock as it stands when the control
+      # returns, not as it stood when the answer arrived — otherwise a
+      # control that deliberates for most of the timeout still buys itself a
+      # full pause and another request on top of it.
+      # @param wait [InputRequiredWait] what the host is told
+      # @param deadline [Float, nil] the request timeout on the wait clock
+      # @return [Numeric] the next delay
+      # @raise [MCPClient::Errors::InputRequiredError] cancelled, or out of time for the pause
+      def pace_input_round_trip(wait, deadline)
+        decision = @input_required_wait_callback&.call(wait)
+        now = input_wait_clock
+        if decision == :cancel
+          raise MCPClient::Errors::InputRequiredError.new(
+            "#{wait.rpc_method} cancelled by the host while waiting for out-of-band input " \
+            "(round trip #{wait.round_trip})", data: wait.result
+          )
+        end
+        # "Retry now" skips the pause, so only a deadline that has already
+        # passed stops it: the request it would re-send is over either way.
+        pause = decision == :retry ? 0 : wait.delay
+        if deadline && now + pause > deadline
+          raise MCPClient::Errors::InputRequiredError.new(
+            "#{wait.rpc_method} is still waiting for out-of-band input at the request timeout " \
+            "(round trip #{wait.round_trip}); resume it from the continuation", data: wait.result
+          )
+        end
+        return wait.delay if decision == :retry
+
+        sleep(wait.delay)
+        [wait.delay * 2, INPUT_RETRY_MAX_DELAY].min
+      end
+
+      # @param started [Float] the wait clock when the request began
+      # @param timeout [Numeric, nil] the per-request timeout, when the caller gave one
+      # @return [Float, nil] the wait clock reading the waits of this request must not pass
+      def input_wait_deadline(started, timeout)
+        bound = input_wait_timeout(timeout)
+        bound ? started + bound : nil
+      end
+
+      # The bound an out-of-band wait is measured against. A caller that named
+      # no timeout still runs under one — the transport's configured read
+      # timeout — and a wait that outlived it would outlive the request it
+      # belongs to. A transport that bounds nothing (a host adapter that sets
+      # no read timeout) leaves the round-trip ceiling as the only limit.
+      # @param timeout [Numeric, nil] the per-request timeout, when the caller gave one
+      # @return [Numeric, nil] the seconds the waits of this request share
+      def input_wait_timeout(timeout)
+        bound = timeout || (@read_timeout if defined?(@read_timeout))
+        bound if bound.is_a?(Numeric) && bound.positive?
+      end
+
+      # @return [Float] the monotonic clock, in seconds, the out-of-band waits are bounded by
+      def input_wait_clock
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end