ruby-mcp-client 2.1.0 → 3.0.0

data/lib/mcp_client/http_transport_base/stream_recovery.rb

@@ -0,0 +1,318 @@
+# frozen_string_literal: true
+
+module MCPClient
+  module HttpTransportBase
+    # What a response stream that broke leaves behind, and what to make of it.
+    #
+    # MCP 2026-07-28 has no resumption: "a broken response stream loses the
+    # in-flight request; clients MUST re-issue it as a new request with a new
+    # request ID". Faraday discards a partially read body and raises, so
+    # without capturing the bytes as they arrive a break *after* the final
+    # event is indistinguishable from one before it -- and re-issuing then
+    # runs a completed call a second time.
+    module StreamRecovery
+      # Innermost Faraday middleware: streams the response body into a
+      # per-request buffer so that
+      #
+      # 1. a socket failure mid-body still leaves the bytes that did arrive
+      #    (Faraday discards a partially read body and raises), letting a
+      #    response that was fully delivered settle its request instead of being
+      #    re-issued and executed twice; and
+      # 2. a deadline can be enforced while the body is arriving, which a socket
+      #    timeout alone cannot do for a stream that keeps dripping keep-alives.
+      #
+      # It restores the buffer as the response body, and being the innermost
+      # handler its on_complete runs before any user middleware (raise_error and
+      # friends) looks at that body.
+      class ResponseBodyCapture < Faraday::Middleware
+        # @param env [Faraday::Env] the outgoing request environment
+        # @return [void]
+        def on_request(env)
+          state = env.request&.context
+          buffer = state && state[:mcp_body_buffer]
+          return unless buffer
+
+          # The retry middleware sits above this one and replays the whole inner
+          # stack, so each attempt must start from an empty buffer (and from an
+          # empty event scanner: the count of events dispatched while the body
+          # arrived belongs to the attempt whose body is finally parsed).
+          buffer.clear
+          listener = state[:mcp_stream_listener]
+          scanner = listener && SseEventScanner.new(max_inflated_bytes: state[:mcp_inflate_limit])
+          state[:mcp_live_events] = 0
+          # The adapter fills this same env in as it reads: its status is set
+          # from the status line, so a salvaged answer can be rebuilt under the
+          # status it really arrived with. The era rule reads a recognized
+          # modern error only under the status it came with.
+          state[:mcp_env] = env
+          env.request.on_data = lambda do |chunk, _size, _env|
+            # Before the chunk is kept, never after: bytes that arrive past the
+            # deadline are not part of an answer this request may settle on, and
+            # buffering them first would let the salvage hand back an answer the
+            # caller had already stopped waiting for.
+            deadline = state[:mcp_deadline]
+            raise Faraday::TimeoutError, 'Request exceeded its deadline' if deadline && monotonic_now > deadline
+
+            buffer << chunk.to_s
+            # Only a streamed body can be measured against its Content-Length
+            # here; a response the adapter hands over whole never reaches this.
+            state[:mcp_streamed] = true
+
+            next unless scanner
+
+            # Every complete event is handed over as it arrives, so a server
+            # request or a progress notification on the stream is acted on
+            # while the response is still open (a server that waits for its
+            # ping to be answered before sending the result would otherwise
+            # deadlock against a client that answers only at EOF).
+            scanner.feed(chunk.to_s) do |event|
+              note_response_arrival(state, event)
+              deliver_live_event(state, listener, event)
+            end
+            state[:mcp_live_events] = scanner.count
+          end
+        end
+
+        # Hand one event to the stream listener. A failure there is the
+        # exchange's failure, but raising it here would abort the read — and
+        # on MCP 2026-07-28 a client closing the response stream is the
+        # cancellation signal — so the first failure is held for the
+        # transport to raise once the body has been read
+        # (StreamCapture#stream_listener_error).
+        # @param state [Hash] the exchange's capture state
+        # @param listener [Proc] the stream listener
+        # @param event [String] one complete SSE event
+        # @return [void]
+        def deliver_live_event(state, listener, event)
+          listener.call(event)
+        rescue StandardError => e
+          state[:mcp_stream_error] ||= e
+        end
+
+        # Flag the event carrying the answer to this request, so whoever
+        # dates the response (CacheSupport's recorder) can date it from the
+        # chunk that completed the result rather than from whatever opened
+        # the stream: a keep-alive or a progress notification is not the
+        # result, and a TTL that ran from it would expire results that took
+        # a while to compute (MCP 2026-07-28 caching, "Freshness Calculation").
+        # @param state [Hash] the exchange's capture state
+        # @param event [String] one complete SSE event
+        # @return [void]
+        def note_response_arrival(state, event)
+          return if state[:mcp_response_seen] || !state.key?(:mcp_response_id)
+
+          state[:mcp_response_seen] = true if response_event?(event, state[:mcp_response_id])
+        end
+
+        # @param event [String] one complete SSE event
+        # @param id [Integer, String] the id of the request awaiting its answer
+        # @return [Boolean] whether the event is the JSON-RPC response to it
+        def response_event?(event, id)
+          data = event.lines.filter_map { |line| line[5..].to_s.sub(/\A /, '').chomp if line.start_with?('data:') }
+          return false if data.empty?
+
+          message = JSON.parse(data.join("\n"))
+          message.is_a?(Hash) && !message.key?('method') && (message['id'] == id || message['id'].to_s == id.to_s)
+        rescue JSON::ParserError
+          false
+        end
+
+        # @param env [Faraday::Env] the completed request environment
+        # @return [void]
+        def on_complete(env)
+          state = env.request&.context
+          buffer = state && state[:mcp_body_buffer]
+          env.body = buffer.dup if buffer && env.body.to_s.empty?
+          state[:mcp_short_body] = short_body?(env, state, buffer) if state
+        end
+
+        private
+
+        # Whether a streamed body stopped short of the length it promised.
+        #
+        # A Content-Length body that ends early does not raise: Net::HTTP hands
+        # back what arrived as if it were whole, and only the promised length
+        # says the exchange was cut. Read as a malformed body it would look like
+        # a server that speaks bad JSON, and the request the stream took with it
+        # would never be re-issued.
+        # @param env [Faraday::Env] the completed request environment
+        # @param state [Hash] the capture state
+        # @param buffer [String, nil] the bytes this exchange streamed
+        # @return [Boolean]
+        def short_body?(env, state, buffer)
+          return false unless buffer && state[:mcp_streamed]
+
+          declared = env.response_headers && (env.response_headers['content-length'] ||
+                                              env.response_headers['Content-Length'])
+          return false if declared.nil? || !declared.to_s.match?(/\A\d+\z/)
+
+          buffer.bytesize < declared.to_i
+        end
+
+        # @return [Float] a monotonic clock reading in seconds
+        def monotonic_now
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+      end
+
+      # Translate a Faraday socket failure into the MCP error the caller must
+      # act on.
+      #
+      # A response stream that dies mid-body is what a broken stream actually
+      # looks like on the wire: Faraday raises rather than handing back a
+      # truncated body, so it never reaches the SSE parser that recognises a
+      # stream which closed *between* events. MCP 2026-07-28 has no resumption
+      # — "a broken response stream loses the in-flight request; clients MUST
+      # re-issue it as a new request with a new request ID" (changelog, major
+      # change 9) — and the rule does not care where the break landed. Raising
+      # ResponseStreamClosedError puts both breaks on the one re-issue path.
+      #
+      # A failure that never got the request out, and a notification (which has
+      # no response to lose), stay a plain ConnectionError.
+      # @param error [Faraday::ConnectionFailed, Faraday::SSLError] the socket failure
+      # @param request [Hash] the JSON-RPC message that was being sent
+      # @return [MCPClient::Errors::MCPError] the error to raise
+      def connection_failure_error(error, request)
+        if modern? && request.is_a?(Hash) && request.key?('id') && interrupted_exchange?(error)
+          return MCPClient::Errors::ResponseStreamClosedError.new(
+            "Response stream closed before delivering the response: #{error.message}"
+          )
+        end
+
+        MCPClient::Errors::ConnectionError.new("Server connection lost: #{error.message}")
+      end
+
+      # Faraday wraps every socket failure in ConnectionFailed (or, for TLS, in
+      # SSLError), whether the connection was never established or it broke with
+      # a request in flight; only the wrapped exception distinguishes them.
+      # @param error [Faraday::ConnectionFailed, Faraday::SSLError] the socket failure
+      # @return [Boolean] true when the exchange had started when it broke
+      def interrupted_exchange?(error)
+        cause = (error.wrapped_exception if error.respond_to?(:wrapped_exception)) || error.cause
+        return false if tls_handshake_failure?(cause)
+
+        INTERRUPTED_EXCHANGE_ERRORS.any? { |klass| cause.is_a?(klass) }
+      end
+
+      # OpenSSL names the failing operation in its message. A handshake that
+      # never completed ("SSL_connect ... certificate verify failed") means the
+      # request never left this client, so there is nothing in flight to
+      # replace; a body that dies mid-read ("SSL_read: unexpected eof while
+      # reading") is a broken response stream like any other.
+      # @param cause [Exception, nil] the exception Faraday wrapped
+      # @return [Boolean] true when TLS failed before the request was sent
+      def tls_handshake_failure?(cause)
+        cause.is_a?(OpenSSL::SSL::SSLError) && cause.message.to_s.include?('SSL_connect')
+      end
+
+      # The response that did arrive before the socket died, when the stream
+      # carried this request's complete answer.
+      #
+      # Faraday discards a partially read body and raises, so without the
+      # streamed capture a break after the final SSE event is indistinguishable
+      # from a break before it — and re-issuing there would run a tools/call the
+      # server already executed a second time. MCP 2026-07-28's re-issue rule is
+      # about an in-flight request that was *lost*; a delivered response settles
+      # its request, however the socket ends afterwards.
+      # A socket that stalls after the final event until the timeout is the
+      # same case from the other direction: the answer arrived, the framing
+      # after it did not.
+      # @param partial_body [String, nil] the bytes captured before the failure
+      # @param request [Hash] the JSON-RPC message that was being sent
+      # @param error [Faraday::Error] the socket failure or timeout
+      # @param capture [Hash, nil] the capture state of the failed exchange
+      # @return [NormalizedResponse, nil] a response carrying the delivered answer
+      def salvaged_response(partial_body, request, error, capture = nil)
+        return nil unless modern? && request.is_a?(Hash) && request.key?('id')
+        return nil unless error.is_a?(Faraday::TimeoutError) || interrupted_exchange?(error)
+
+        body = partial_body.to_s
+        body = inflate_delivered_gzip(body) if body.b.start_with?(SseEventScanner::GZIP_MAGIC)
+        return nil if body.nil? || body.empty?
+
+        sse = sse_framed_body?(body)
+        # A truncated stream's last event has no terminating blank line, so it
+        # was never dispatched (HTML SSE parsing rules) and must be dropped
+        # before asking whether the answer arrived.
+        body = complete_sse_events(body) if sse
+        return nil if body.empty? || !body_carries_response?(body, sse, request['id'])
+
+        @logger.warn("Response stream ended after the response arrived (#{error.message}); " \
+                     "keeping the delivered #{request['method']} response instead of re-issuing it")
+        NormalizedResponse.new(delivered_status(capture),
+                               { 'content-type' => sse ? 'text/event-stream' : 'application/json' }, body,
+                               capture)
+      end
+
+      # The status a salvaged answer arrived under. A well-formed -32022 in a
+      # 400 body identifies a modern server and is retried with an advertised
+      # version, while the same body under 200 is a permissive legacy echo:
+      # rebuilding every salvaged answer as 200 would turn the first into the
+      # second. The adapter fills the captured env in as it reads, so its status
+      # is the status line this response really carried.
+      # @param capture [Hash, nil] the capture state of the failed exchange
+      # @return [Integer]
+      def delivered_status(capture)
+        (capture.is_a?(Hash) && capture[:mcp_env]&.status) || 200
+      end
+
+      # What a body that stopped short of its Content-Length settles: the
+      # answer if it is all there anyway (the bytes that arrived carry this
+      # request's response, and the rest was framing), otherwise the loss the
+      # re-issue rule is written for.
+      # @param request [Hash] the JSON-RPC message that was being sent
+      # @param capture [Hash] the capture state of the exchange
+      # @return [NormalizedResponse] the delivered answer
+      # @raise [MCPClient::Errors::MCPError] when the response was lost
+      def truncated_body_outcome(request, capture)
+        error = Faraday::ConnectionFailed.new(EOFError.new('response body stopped short of its Content-Length'))
+        salvaged = salvaged_response(capture[:mcp_body_buffer], request, error, capture)
+        return settled_salvage(salvaged) if salvaged
+
+        raise connection_failure_error(error, request)
+      end
+
+      # A salvaged answer read the way the unbroken path reads one: an error
+      # status it arrived under still becomes the typed JSON-RPC error, so a
+      # recognized modern error keeps the status the era rule needs. Returning
+      # it unread would settle a 400 rejection as if it were a 200 result.
+      # @param salvaged [NormalizedResponse] the response the salvage rebuilt
+      # @return [NormalizedResponse] the same response, once it is an answer
+      # @raise [MCPClient::Errors::MCPError] whatever its status and body say
+      def settled_salvage(salvaged)
+        handle_http_error_response(salvaged) unless (200..299).cover?(salvaged.status.to_i)
+        salvaged
+      end
+
+      # Per the SSE specification a line is terminated by CRLF, CR or LF alone;
+      # normalizing to LF lets one set of framing rules serve all three.
+      # @param body [String] a response body
+      # @return [String] the body with LF line terminators
+      def normalize_sse_newlines(body)
+        without_bom(body).gsub(/\r\n|\r/, "\n")
+      end
+
+      # The UTF-8 decode step of the SSE algorithm drops one leading byte-order
+      # mark; the field it precedes must still be recognized.
+      # @param body [String] a response body
+      # @return [String]
+      def without_bom(body)
+        bom = body.encoding == Encoding::BINARY ? SseEventScanner::BOM : "\uFEFF".encode(body.encoding)
+        body.start_with?(bom) ? body[bom.length..] : body
+      rescue EncodingError
+        body
+      end
+
+      # @param body [String] an LF-normalized SSE body
+      # @return [Array<String>] the joined data payload of each event
+      def sse_data_payloads(body)
+        body.split("\n\n").filter_map do |event|
+          lines = event.lines.map(&:chomp).select { |line| line.start_with?('data:') }
+          next if lines.empty?
+
+          lines.map { |line| line.sub(/\Adata:\s*/, '') }.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/mcp_client/http_transport_base/tool_listing.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+module MCPClient
+  module HttpTransportBase
+    # The tool list an HTTP transport keeps, and everything derived from it:
+    # its generation counter (which tells a host that a mid-call refresh
+    # changed the definitions), the fetch that fills it, the invalidation a
+    # list_changed notification triggers, and the Mcp-Param-* headers a
+    # tools/call carries (MCP 2026-07-28 "Custom Headers from Tool
+    # Parameters") -- including the HeaderMismatch refresh-and-retry.
+    module ToolListing
+      private
+
+      # MCP 2026-07-28 "Custom Headers from Tool Parameters": after a
+      # HeaderMismatch the client SHOULD re-fetch tools/list (the tool's
+      # inputSchema may have changed its x-mcp-header annotations) and retry
+      # the original request once with the appropriate headers. The server
+      # rejected the request before executing it, so the retry cannot
+      # duplicate a side effect. A refresh that fails re-raises the rejection:
+      # that is the actionable error.
+      # The list this refresh read is returned, not just cached: the retry
+      # goes out under the definition ITS OWN refresh brought. Two calls to
+      # one tool rejected at the same time each refresh, and the transport's
+      # cache holds whichever landed last — so a retry that re-read the cache
+      # could send another caller's definition.
+      # @param error [MCPClient::Errors::HeaderMismatchError] the rejection
+      # @return [Array<MCPClient::Tool>] the list this refresh fetched
+      def refresh_tools_after_header_mismatch(error)
+        @logger.warn("#{sanitize_log_text(error.message)}; refreshing tools/list and retrying tools/call once")
+        refresh_tools_cache
+      rescue MCPClient::Errors::MCPError => e
+        @logger.warn("tools/list refresh after HeaderMismatch failed: #{sanitize_log_text(e.message)}")
+        raise error
+      end
+
+      # MCP 2026-07-28 basic "Implementation Requirements": a client "MUST
+      # handle unsupported dialects gracefully by returning an appropriate
+      # error indicating the dialect is not supported" — and, having done
+      # so, must not go on to act on the schema. MCPClient::Client refuses
+      # the dialect of the definition a call is prepared from, but the
+      # HeaderMismatch retry goes out under the definition the refresh
+      # brought instead, which this client never resolved. The rejection
+      # means the server did not execute the first attempt, so refusing the
+      # retry keeps the invariant the check is for: the call is never sent
+      # under a schema nothing could read.
+      # @param params [Hash] the tools/call params being re-sent
+      # @param refreshed [Array<MCPClient::Tool>, nil] the list this call's own
+      #   refresh read; the transport's cache is consulted only without one
+      # @return [void]
+      # @raise [MCPClient::Errors::ValidationError] when the refreshed input
+      #   or output schema declares a dialect this client does not implement
+      def reject_unreadable_refreshed_schema!(params, refreshed = nil)
+        return unless params.is_a?(Hash)
+
+        name = (params['name'] || params[:name]).to_s
+        list = refreshed.is_a?(Array) ? refreshed : known_tools_for_headers
+        tool = list.find { |t| t.name.to_s == name }
+        # The definition checked here is the one the retry goes out under
+        # ({#mcp_param_headers} takes it): a second lookup could bring
+        # another, unchecked one.
+        pin_retry_definition(name, tool)
+        reject_unreadable_tool_schema!(name, tool)
+      end
+
+      # Refuse a tool definition whose input or output schema declares a JSON
+      # Schema dialect this client cannot read, before the request it governs
+      # goes out: a tool run under an output dialect nothing here can read
+      # would only be refused after it ran, and the host would have paid for
+      # whatever it did.
+      # @param name [String] the tool name
+      # @param tool [MCPClient::Tool, nil] the definition the request goes out under
+      # @return [void]
+      # @raise [MCPClient::Errors::ValidationError]
+      def reject_unreadable_tool_schema!(name, tool)
+        return unless tool
+
+        { 'input' => tool.schema, 'output' => tool.output_schema }.each do |side, schema|
+          dialect = schema.is_a?(Hash) && MCPClient::SchemaValidator.unsupported_dialect(schema)
+          next unless dialect
+
+          raise MCPClient::Errors::ValidationError,
+                "Tool #{sanitize_log_text(name.inspect)} #{side} schema declares the JSON Schema dialect " \
+                "#{sanitize_log_text(dialect.inspect)[0, 128]}: that dialect is not supported " \
+                "(supported: #{MCPClient::SchemaValidator::SUPPORTED_DIALECTS.join(', ')})"
+        end
+      end
+
+      # The Mcp-Param-* headers for a tools/call request (MCP 2026-07-28
+      # "Custom Headers from Tool Parameters"): the annotated arguments of the
+      # tool, looked up in this transport's tool list (fetched on demand so a
+      # call issued before tools/list still carries them).
+      # @param request [Hash] the JSON-RPC request
+      # @return [Hash{String => String}]
+      # @raise [MCPClient::Errors::ValidationError] when an annotated argument cannot be mirrored
+      def mcp_param_headers(request)
+        return {} unless request['method'] == 'tools/call'
+
+        params = request['params']
+        return {} unless params.is_a?(Hash)
+
+        name = (params['name'] || params[:name]).to_s
+        pinned = take_pinned_retry_definition(name)
+        tool = pinned ? pinned.first : known_tools_for_headers.find { |t| t.name.to_s == name }
+        # The list the headers come from is the list this request goes out
+        # under: a host re-resolving the tool after the call reads that
+        # definition back instead of asking for a possibly newer one. It is
+        # also the definition the dialect guard has to read — this lookup may
+        # bring a newer one than the caller preflighted, and a pinned one has
+        # been checked already by the refresh that pinned it.
+        note_called_tool_definition(name, tool)
+        reject_unreadable_tool_schema!(name, tool) unless pinned
+        return {} unless tool
+
+        MCPClient::HeaderParams.headers_for(tool.schema, params['arguments'] || params[:arguments])
+      end
+
+      # The tool list used for header extraction, fetched on demand. Mirroring
+      # is a MUST, so a list that cannot be fetched fails the call rather than
+      # letting it go out without the headers an intermediary may route on.
+      #
+      # That fetch is an exchange of its own, with a recovery of its own (its
+      # one re-issue, its own with_retry attempts), and it runs inside the
+      # call's recovery block: an error escaping it is marked so the call does
+      # not mistake it for its own rejection or lost stream and spend the one
+      # re-issue or refresh it has on a request that never went out.
+      # @return [Array<MCPClient::Tool>]
+      # @raise [MCPClient::Errors::MCPError] the list's own failure, marked NestedExchange
+      def known_tools_for_headers
+        fresh_list_value(:tools) { @mutex.synchronize { @tools } } || list_tools
+      rescue StandardError => e
+        e.extend(RequestRecovery::NestedExchange) unless e.frozen?
+        raise
+      end
+
+      # Drop the cached tool list and re-fetch it. Hosts layered above the
+      # transport (MCPClient::Client) keep their own tool cache, so the refresh
+      # is announced the way the server itself would: as a tools/list_changed
+      # notification.
+      # @return [void]
+      def refresh_tools_cache
+        invalidate_tools_cache
+        list_tools
+      ensure
+        announce_tools_list_changed
+      end
+
+      # Tell the host its own copy is gone. This runs whether or not the
+      # re-fetch that followed the invalidation succeeded: the transport's
+      # list is already dropped by then, so a host that kept its copy would go
+      # on calling with definitions this client has thrown away, and it would
+      # never learn otherwise -- the server sends no notification for a
+      # refresh the client started. A listener that raises is the host's
+      # problem, not the caller's: the rejection that started the refresh is
+      # what the caller must see.
+      # @return [void]
+      def announce_tools_list_changed
+        # Announced on both hooks, in the order routing uses them, so a host
+        # whose cache invalidation runs ahead of subscription deliveries is
+        # told here too (see {MCPClient::ServerBase#on_cache_invalidation}).
+        notify_cache_invalidation('notifications/tools/list_changed', {})
+        @notification_callback&.call('notifications/tools/list_changed', {})
+      rescue StandardError => e
+        @logger.warn("Tool list invalidation listener failed: #{sanitize_log_text("#{e.class}: #{e.message}")}")
+      end
+
+      # Forget the cached tool list. The generation counter lets a list fetch
+      # that was already in flight recognise that it is stale and not
+      # overwrite a fresher list.
+      # @return [void]
+      def invalidate_tools_cache
+        @mutex.synchronize do
+          @tools = nil
+          @tools_data = nil
+          @tools_generation = tools_generation + 1
+        end
+        # The cached entry (which carries the list too) is stale as well.
+        invalidate_cache(:tools)
+      end
+
+      # @return [Integer] the current tool-list generation (bump on invalidation)
+      def tools_generation
+        @tools_generation ||= 0
+      end
+      public :tools_generation
+
+      # Fetch and cache the tool list, re-fetching when the cache was
+      # invalidated while the fetch was in flight (bounded).
+      # @return [Array<MCPClient::Tool>]
+      def fetch_tools_list
+        3.times do
+          generation = @mutex.synchronize { tools_generation }
+          tools_data = request_tools_list
+          # MCP 2026-07-28: tools with invalid x-mcp-header annotations are
+          # excluded from the list on this transport.
+          tools_data = reject_invalid_header_tools(tools_data) if modern?
+          tools = tools_data.map { |tool_data| MCPClient::Tool.from_json(tool_data, server: self) }
+          stored = store_tools(tools, generation)
+          return stored if stored
+        end
+        raise MCPClient::Errors::TransportError, 'tools/list kept changing while it was being fetched'
+      end
+
+      # Store a freshly fetched tool list unless the cache was invalidated
+      # while it was being fetched, in which case the fresher list wins.
+      # @param tools [Array<MCPClient::Tool>] the fetched list
+      # @param generation [Integer] tools_generation when the fetch started
+      # @return [Array<MCPClient::Tool>] the list to hand to the caller
+      def store_tools(tools, generation)
+        @mutex.synchronize do
+          if tools_generation == generation
+            # A copy is kept only when its hint was attached (or the list
+            # carried none): a fetch whose entry was cleared or replaced in
+            # flight leaves nothing behind, so the next access fetches again.
+            previous = @tools
+            @tools = attach_list_value(:tools, tools) ? tools : nil
+            # A re-fetch that brought different definitions (an expired ttlMs
+            # during a tools/call) is a change the host must see: a client
+            # re-resolves a tool for post-call validation only when the
+            # generation moves, and would otherwise check the result against
+            # the definition the call was not answered under.
+            @tools_generation = tools_generation + 1 if tool_definitions_changed?(previous, tools)
+            return tools
+          end
+
+          # Invalidated while in flight: this list is stale even if nothing
+          # newer was stored yet, and whatever is current may be another
+          # request's list — nil makes the caller fetch again.
+          nil
+        end
+      end
+
+      # Drop the transport's cached list of a kind, so a re-list after a change
+      # (or the HeaderMismatch refresh) really fetches the new definitions.
+      # @param kind [Symbol] :tools, :prompts, :resources or :templates
+      # @return [void]
+      def invalidate_list_cache(kind)
+        case kind
+        when :tools then invalidate_tools_cache
+        when :prompts
+          @mutex.synchronize do
+            @prompts = nil
+            @prompts_data = nil
+          end
+        when :resources
+          @mutex.synchronize do
+            @resources_result = nil
+            @resources_data = nil
+          end
+        when :templates
+          # resources/list_changed covers resources/templates/list too: the
+          # old templates are stale, and holding them keeps a list the next
+          # fetch will replace alive for the life of the connection.
+          @mutex.synchronize { @templates_result = nil }
+        end
+      end
+
+      # Exclude tool definitions whose x-mcp-header annotations violate the
+      # transport constraints (MCP 2026-07-28: "Rejection means the client
+      # MUST exclude the invalid tool from the result of tools/list"), logging
+      # a warning with the tool name and the reason.
+      # @param tools_data [Array<Hash>] raw tool definitions
+      # @return [Array<Hash>] the acceptable definitions
+      def reject_invalid_header_tools(tools_data)
+        tools_data.reject do |data|
+          schema = data['inputSchema'] || data[:inputSchema] || data['schema'] || data[:schema]
+          errors = MCPClient::HeaderParams.validate_schema(schema)
+          next false if errors.empty?
+
+          name = data['name'] || data[:name]
+          @logger.warn("Rejecting tool #{sanitize_log_text(name.to_s.inspect)}: invalid x-mcp-header annotation: " \
+                       "#{sanitize_log_text(errors.join('; '))}")
+          true
+        end
+      end
+    end
+  end
+end