ruby-mcp-client 2.1.0 → 3.0.0

data/lib/mcp_client/called_tool_definition.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module MCPClient
+  # The tool definition a `tools/call` request went out under (MCP 2026-07-28
+  # "Custom Headers from Tool Parameters"): the transport derives that
+  # request's `Mcp-Param-*` headers from its tool list, so the definitions in
+  # that list are the ones the call is made -- and answered -- under.
+  #
+  # A host that re-resolves the tool afterwards, to validate the result
+  # against the definition the call actually carried, reads it from here
+  # instead of listing again: on a list the server bounds with `ttlMs: 0` (or
+  # one whose TTL expired during the call) another access re-fetches, and the
+  # definition that comes back may not be the one the request went out with.
+  #
+  # Every call gets a slot of its own, so a nested exchange cannot overwrite
+  # an outer call's definition: a Streamable HTTP response dispatches the
+  # notifications it carries synchronously, and a listener may call another
+  # tool on this very transport and thread before the outer call returns.
+  #
+  # The slots are kept per thread and per transport, in a stack named after
+  # the transport's `object_id` so that
+  # {MCPClient::ResultCaching#forget_transport_thread_state} drops it with
+  # everything else a discarded transport left behind.
+  module CalledToolDefinition
+    private
+
+    # Run one tools/call with a slot of its own for the definition its
+    # request goes out under. What the call recorded is handed, when it
+    # returns, to the caller still waiting for it -- never to an outer call
+    # that already recorded its own -- and nothing is left on this thread
+    # once the outermost call is over.
+    # @yield the call
+    # @return [Object] the block's value
+    def recording_called_tool_definition
+      stack = (Thread.current[called_tool_definition_key] ||= [])
+      stack.push(nil)
+      begin
+        yield
+      ensure
+        finished = stack.pop
+        stack[-1] = finished if finished && !stack.empty? && stack.last.nil?
+        Thread.current[called_tool_definition_key] = nil if stack.empty?
+      end
+    end
+
+    # The boundary a transport crosses when it hands control to host code: a
+    # notification listener, a handler for a server-initiated request. A
+    # `tools/call` that code issues -- the public `call_tool`, or a raw
+    # `rpc_request('tools/call', ...)` naming the very tool the open call is
+    # waiting on -- records into a slot of its own and nothing of it is handed
+    # back out, so the call whose response is still being parsed keeps the
+    # definition its own request went out under.
+    # @yield the host code
+    # @return [Object] the block's value
+    def outside_called_tool_definition
+      stack = (Thread.current[called_tool_definition_key] ||= [])
+      stack.push(nil)
+      begin
+        yield
+      ensure
+        stack.pop
+        Thread.current[called_tool_definition_key] = nil if stack.empty?
+      end
+    end
+
+    # Remember the definition a tools/call request is going out under.
+    # @param name [String] the tool named in the request
+    # @param tool [MCPClient::Tool, nil] its definition in the list the
+    #   request's headers were derived from (nil when that list no longer
+    #   carries the tool at all)
+    # @return [void]
+    def note_called_tool_definition(name, tool)
+      stack = (Thread.current[called_tool_definition_key] ||= [nil])
+      stack[-1] = [name.to_s, tool]
+    end
+
+    # The definition the tools/call this caller is waiting on went out under.
+    # Taken rather than read: it describes that one request, and leaving it
+    # behind would keep a tool definition on this thread for as long as the
+    # transport lives.
+    # @param name [String] the tool being re-resolved
+    # @return [Array(MCPClient::Tool, nil), nil] a one-element array holding
+    #   the definition -- its element is nil when the list the request went
+    #   out under no longer listed the tool -- or nil when no call of this
+    #   caller's recorded a definition for that tool
+    def take_called_tool_definition(name)
+      stack = Thread.current[called_tool_definition_key]
+      recorded = stack.is_a?(Array) ? stack.last : nil
+      return nil unless recorded.is_a?(Array) && recorded.first == name.to_s
+
+      stack[-1] = nil
+      Thread.current[called_tool_definition_key] = nil if stack.size == 1
+      [recorded.last]
+    end
+
+    # @return [Symbol] this transport's thread-local key for it
+    def called_tool_definition_key
+      :"mcp_client_called_tool_definition_#{object_id}"
+    end
+
+    # Pin the definition the HeaderMismatch retry was checked against, so
+    # the retry's headers are derived from that very definition. Between
+    # the check and the send the list would otherwise be looked up again,
+    # and on a list the server bounds with `ttlMs: 0` another lookup is
+    # another fetch — possibly of a definition the check never read.
+    # @param name [String] the tool named in the retried request
+    # @param tool [MCPClient::Tool, nil] the definition the check read (nil
+    #   when the refreshed list no longer carries the tool)
+    # @return [void]
+    def pin_retry_definition(name, tool)
+      Thread.current[pinned_retry_definition_key] = [name.to_s, tool]
+    end
+
+    # Take the pinned definition for a request, if the retry of that very
+    # tool pinned one. Taken rather than read: it describes one send.
+    # @param name [String] the tool named in the request being sent
+    # @return [Array(MCPClient::Tool, nil), nil] a one-element array holding
+    #   the definition, or nil when nothing is pinned for the tool
+    def take_pinned_retry_definition(name)
+      pinned = Thread.current[pinned_retry_definition_key]
+      return nil unless pinned.is_a?(Array) && pinned.first == name.to_s
+
+      Thread.current[pinned_retry_definition_key] = nil
+      [pinned.last]
+    end
+
+    # Drop a pin the retry never consumed (it raised before sending).
+    # @return [void]
+    def clear_pinned_retry_definition
+      Thread.current[pinned_retry_definition_key] = nil
+    end
+
+    # @return [Symbol] this transport's thread-local key for the pin
+    def pinned_retry_definition_key
+      :"mcp_client_pinned_retry_definition_#{object_id}"
+    end
+  end
+end

data/lib/mcp_client/client/cache_slices.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module MCPClient
+  class Client
+    # The client's own slices of a list cache under the MCP 2026-07-28
+    # caching rules: whether every server's slice is still fresh and current
+    # for the parameters a listing would send, the snapshot a fresh cache
+    # yields, and the replacement of one server's slice by a fresh fetch
+    # without disturbing the others. Mixed into {MCPClient::Client}; every
+    # method is private there.
+    module CacheSlices
+      private
+
+      # Whether every server's cached list of a kind is still fresh (MCP
+      # 2026-07-28 caching: a stale list is re-fetched on access).
+      # The parameters go first: reading them evaluates the host's request_meta
+      # and the transport holds that evaluation, which the freshness check then
+      # reuses instead of reading the callable a second time. Asking the other
+      # way round released the held value in between, so a hit spent two
+      # trace ids (or nonces) on a decision that sends nothing.
+      # @param kind [Symbol] :tools, :prompts or :resources
+      # @return [Boolean]
+      def caches_fresh?(kind)
+        servers.all? do |server|
+          cache_params_current?(kind, server) && (!server.respond_to?(:cache_fresh?) || server.cache_fresh?(kind))
+        end
+      rescue StandardError
+        # One server's check aborted -- an OAuth refresh that failed, a host
+        # `request_meta` callable that raised -- so nothing is fetched from any
+        # of them. Every server the loop had already passed is still holding
+        # the evaluation this decision read for the fetch it would have made:
+        # dropped here, all of them, or an unrelated request on this worker
+        # thread would go out carrying that decision's tenant, baggage or nonce.
+        release_held_request_meta
+        raise
+      end
+
+      # The cache's items as one snapshot taken under the lock, when the cache
+      # holds something and every server's slice is fresh for the parameters
+      # its next request would carry.
+      # @param kind [Symbol]
+      # @param cache [Hash]
+      # @return [Array, nil]
+      def cached_snapshot(kind, cache)
+        # Freshness consults the servers (a request_meta callable, host
+        # middleware), which may clear this cache in turn: it runs outside the
+        # lock, and the copy is served only when nothing changed meanwhile.
+        version = @cache_mutex.synchronize { @cache_version }
+        # An empty snapshot is a hit too: a server may list nothing, and its
+        # entry says so for as long as it is fresh. What makes a hit is that
+        # every server has filled its slice, not that the hash holds items.
+        return nil unless @cache_mutex.synchronize { snapshot_complete?(kind, cache) }
+        return nil unless caches_fresh?(kind)
+
+        @cache_mutex.synchronize do
+          # A cleanup that landed after the verdict replaced the transport
+          # entries the slices came from; that check touches only the
+          # transport's cache lock, so it can run under this one.
+          next unless version == @cache_version && snapshot_complete?(kind, cache) && slices_still_current?(kind)
+
+          cached_copies(cache)
+        end
+      end
+
+      # Whether every server this client talks to has filled its slice of a
+      # list cache (an empty list fills a slice as much as a long one does).
+      # Called under {@cache_mutex}.
+      # @param kind [Symbol]
+      # @param cache [Hash] the kind's cache, to tell an empty snapshot apart
+      # @return [Boolean]
+      def snapshot_complete?(kind, cache)
+        filled = @cache_filled[kind]
+        return false if filled.nil?
+
+        list = servers
+        return false if list.empty? || !list.all? { |server| filled.key?(server) }
+        # A snapshot with nothing in it is only a hit while a server says so
+        # itself: a 2026-07-28 server bounds its empty list with a ttlMs, an
+        # older one records no hint at all and keeps the client's previous
+        # heuristic — ask again until something is listed.
+        return true unless cache.empty?
+
+        list.all? { |server| hinted_slice?(kind, server) }
+      end
+
+      # @param kind [Symbol]
+      # @param server [MCPClient::ServerBase]
+      # @return [Boolean] whether the entry behind this server's slice bounds
+      #   its own freshness (the server sent a hint)
+      def hinted_slice?(kind, server)
+        server.respond_to?(:cache_entry_hinted?, true) && server.send(:cache_entry_hinted?, kind)
+      end
+
+      # Whether every server's slice of a kind still comes from the transport
+      # entry it was recorded against (a cleanup or a replaced entry ends it).
+      # @param kind [Symbol]
+      # @return [Boolean]
+      def slices_still_current?(kind)
+        servers.all? do |server|
+          next true unless server.respond_to?(:cache_entry_token, true)
+
+          _fingerprint, token = @cache_params[kind][server]
+          current = server.send(:cache_entry_token, kind)
+          next current.nil? if token == MCPClient::ResultCaching::LEGACY_ENTRY
+          next false unless !token.nil? && !current.nil? && current.equal?(token)
+
+          # The verdict may be old by the time the copy is made: the entry's
+          # own hint is re-read here (transport cache lock only).
+          !server.respond_to?(:cache_entry_fresh?, true) || server.send(:cache_entry_fresh?, kind)
+        end
+      end
+
+      # Replace one server's slice of a list cache under the lock: its previous
+      # entries go, the fingerprint the fetch was made under is recorded, and
+      # the block inserts the new entries.
+      # @param kind [Symbol]
+      # @param cache [Hash]
+      # @param server [MCPClient::ServerBase]
+      # @param fingerprint [String, nil]
+      # @return [void]
+      def replace_cached_slice(kind, cache, server, fingerprint, generation: nil)
+        @cache_mutex.synchronize do
+          # An invalidation that landed while the fetch ran already replaced
+          # these definitions; writing them back would undo it.
+          next if generation && @tool_cache_generation != generation
+
+          @cache_version += 1
+          drop_cached_entries(cache, server)
+          # This server's slice now stands for its whole list, empty or not.
+          (@cache_filled[kind] ||= {}.compare_by_identity)[server] = true
+          forget_schema_checks(server) if kind == :tools
+          if server.respond_to?(:current_params_fingerprint, true)
+            # The slice is tied to the very transport entry its list came
+            # from — its identity and the parameters that entry is bound to
+            # (the request that produced it, which a first fetch may have made
+            # with more than was known before connecting): a transport list
+            # refreshed on its own (rotated credentials, a concurrent fetch)
+            # replaces that entry, and the slice with it.
+            token, bound = served_entry_for(kind, server)
+            @cache_params[kind][server] = [bound || fingerprint, token]
+          end
+          yield
+        end
+      end
+
+      # @return [Array(Object, String), nil] the identity of the transport
+      #   entry the list this thread just obtained from the server came from,
+      #   and the parameters fingerprint it is bound to
+      def served_entry_for(kind, server)
+        return nil unless server.respond_to?(:take_served_entry, true)
+
+        # Taken rather than read: the note exists for this one tagging, and
+        # leaving it behind would keep a slot on this thread for every
+        # transport a long-lived worker has ever listed through.
+        server.send(:take_served_entry, kind)
+      end
+
+      # @return [Boolean] whether the server's next request would carry the
+      #   parameters its slice of the cache was filled under, and the transport
+      #   still holds the entry that slice came from
+      def cache_params_current?(kind, server)
+        return true unless server.respond_to?(:current_params_fingerprint, true)
+
+        fingerprint, token = @cache_params[kind][server]
+        return false unless fingerprint == server.send(:current_params_fingerprint)
+        return true unless server.respond_to?(:cache_entry_token, true)
+
+        # A slice is identified by the very entry it came from; a legacy list
+        # (no hint recorded) stays a hit only while the transport still holds
+        # no entry, and a fetch that recorded no entry identifies nothing.
+        current = server.send(:cache_entry_token, kind)
+        return current.nil? if token == MCPClient::ResultCaching::LEGACY_ENTRY
+
+        !token.nil? && !current.nil? && current.equal?(token)
+      end
+
+      # The cache's items as copies: a caller can neither change the cache nor
+      # what later callers (and the x-mcp-header derivation) see.
+      # @param cache [Hash]
+      # @return [Array]
+      def cached_copies(cache)
+        cache.values.map { |item| MCPClient::DeepCopy.copy(item) }
+      end
+
+      # Remove one server's entries from a client-level cache.
+      # @param cache [Hash] the cache keyed by #cache_key_for
+      # @param server [MCPClient::ServerBase]
+      # @return [void]
+      def drop_cached_entries(cache, server)
+        prefix = "#{server.object_id}:"
+        cache.delete_if { |key, _| key.start_with?(prefix) }
+      end
+    end
+  end
+end

data/lib/mcp_client/client/list_aggregation.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+module MCPClient
+  class Client
+    # Listing across the client's servers: the per-server fetch loops that
+    # fill the client's slices of a list cache, and the bookkeeping the
+    # MCP 2026-07-28 caching rules put around them.
+    #
+    # A listing weighs its cache decision on the effective parameters the
+    # fetch would carry, which evaluates the host's `request_meta` callable;
+    # the transports hold that evaluation for the fetch the decision leads
+    # to, so the request goes out with exactly what was weighed. That
+    # reservation is opened here, for every server, and closed here from an
+    # `ensure`: a fetch that raises during a reconnect, an authorization
+    # error a caller catches, a server the loop never reaches -- none of them
+    # can leave an evaluation on this worker thread for some later, unrelated
+    # request to send.
+    module ListAggregation
+      private
+
+      # Reserve, on every server, the evaluation of the host `request_meta`
+      # for the request this listing leads to -- for the listing and no
+      # longer. Each reservation is kept by name: it is handed to that
+      # server's own fetch when the loop reaches it ({#fetching_from}) and to
+      # nothing else, so a list a notification listener runs meanwhile on a
+      # server the loop has not reached cannot spend an evaluation this
+      # decision weighed for that server's fetch.
+      # @param method [String] the JSON-RPC method the listing's fetch sends
+      # @yield the listing
+      # @return [Object] the block's value
+      def holding_request_meta(method)
+        holders = servers.select { |server| server.respond_to?(:open_request_meta_hold, true) }
+        reservations = holders.to_h { |server| [server, server.send(:open_request_meta_hold, method)] }
+        request_meta_reservations.push(reservations)
+        begin
+          yield
+        ensure
+          pop_request_meta_reservations
+          holders.each { |server| server.send(:close_request_meta_hold) }
+        end
+      end
+
+      # Run this server's fetch under the reservation this listing opened for
+      # it: the transport's own listing operation adopts it, and only it --
+      # an operation that begins meanwhile finds nothing to adopt and
+      # reserves its own.
+      # @param server [MCPClient::ServerBase]
+      # @yield the fetch
+      # @return [Object] the block's value
+      def fetching_from(server)
+        reservation = request_meta_reservations.last&.[](server)
+        return yield unless reservation && server.respond_to?(:offer_request_meta_hold, true)
+
+        server.send(:offer_request_meta_hold, reservation)
+        begin
+          yield
+        ensure
+          server.send(:withdraw_request_meta_hold)
+        end
+      end
+
+      # The reservations of the listings open on this thread, innermost last:
+      # a listing a notification listener nests inside this one has its own,
+      # and neither reaches the other's.
+      # @return [Array<Hash>]
+      def request_meta_reservations
+        Thread.current[request_meta_reservations_key] ||= []
+      end
+
+      # @return [void]
+      def pop_request_meta_reservations
+        stack = Thread.current[request_meta_reservations_key]
+        return nil unless stack.is_a?(Array)
+
+        stack.pop
+        Thread.current[request_meta_reservations_key] = nil if stack.empty?
+        nil
+      end
+
+      # @return [Symbol] this client's thread-local key for the reservations
+      #   its open listings hold
+      def request_meta_reservations_key
+        :"mcp_client_list_reservations_#{object_id}"
+      end
+
+      # A freshness check reads the parameters each server's next request
+      # would carry, which evaluates a host `request_meta` callable; the
+      # transports hold that evaluation for the fetch the check decides on.
+      # Nothing is fetched after a snapshot is served, so the held metadata is
+      # dropped instead of being sent by some later request.
+      # @return [void]
+      def release_held_request_meta
+        servers.each do |server|
+          server.send(:release_held_request_meta) if server.respond_to?(:release_held_request_meta, true)
+        end
+      end
+
+      # The effective-parameter fingerprint a server's next request would
+      # carry, read before a fetch so its slice of the cache is tagged with
+      # the parameters of the list it holds (never with a leftover of whatever
+      # request ran last on this thread).
+      # @param server [MCPClient::ServerBase]
+      # @return [String, nil]
+      def params_fingerprint_for(server)
+        return nil unless server.respond_to?(:current_params_fingerprint, true)
+
+        server.send(:current_params_fingerprint)
+      end
+
+      # A forced refresh (`cache: false`) must really re-list. A transport
+      # keeps a list the server bounded with a positive `ttlMs` and answers
+      # from it without sending anything at all (MCP 2026-07-28
+      # server/utilities/caching), so the entry that bounds it is dropped
+      # first and the fetch reaches the server.
+      # @param server [MCPClient::ServerBase]
+      # @param kind [Symbol] :tools, :prompts or :resources
+      # @return [void]
+      def refresh_server_cache(server, kind)
+        server.send(:invalidate_cache, kind) if server.respond_to?(:invalidate_cache, true)
+        server.send(:invalidate_list_cache, kind) if server.respond_to?(:invalidate_list_cache, true)
+      end
+
+      # A call and the re-resolve that follows it share one slot for the
+      # definition the request went out under, so a nested call (a listener
+      # the response's notification dispatch runs) records into its own and
+      # leaves this one alone.
+      # @param server [MCPClient::ServerBase]
+      # @yield the call and its validation
+      # @return [Object] the block's value
+      def with_called_tool_definition(server, &block)
+        return block.call unless server.respond_to?(:recording_called_tool_definition, true)
+
+        server.send(:recording_called_tool_definition, &block)
+      end
+
+      # @param cache [Boolean] whether a cached list may answer
+      # @return [Array<MCPClient::Tool>]
+      def collect_tools_from_servers(cache)
+        tools = []
+        connection_errors = []
+        # Read before the fetch so an invalidation that lands while it runs is
+        # noticed. The mutex is never held across a request: a response may
+        # dispatch a notification, on this very thread, that empties the cache.
+        generation = @cache_mutex.synchronize { @tool_cache_generation }
+
+        servers.each do |server|
+          refresh_server_cache(server, :tools) unless cache
+          # The parameters this fetch will carry are read before it goes out:
+          # whatever request ran last on this thread says nothing about it.
+          fingerprint = params_fingerprint_for(server)
+          server_tools = fetching_from(server) { server.list_tools }
+          # What was fetched answers this caller either way.
+          tools.concat(server_tools)
+          # Replace this server's slice: an item the refreshed list no longer
+          # carries must not linger from the previous fetch. A
+          # tools/list_changed that landed while the fetch ran -- the one a
+          # HeaderMismatch refresh announces included -- already replaced these
+          # definitions, so caching them would hand the superseded ones on.
+          replace_cached_slice(:tools, @tool_cache, server, fingerprint,
+                               generation: generation) do
+            server_tools.each do |tool|
+              @tool_cache[cache_key_for(server, tool.name)] = MCPClient::DeepCopy.copy(tool)
+            end
+          end
+        rescue MCPClient::Errors::ConnectionError => e
+          # Fast-fail on authorization errors for better user experience
+          # If this is the first server or we haven't collected any tools yet,
+          # raise the auth error directly to avoid cascading error messages
+          raise e if e.message.include?('Authorization failed') && tools.empty?
+
+          # Store the error and try other servers
+          connection_errors << e
+          @logger.error("Server error: #{e.message}")
+        end
+
+        # If we didn't get any tools from any server but have servers configured, report failure
+        if tools.empty? && !servers.empty?
+          raise connection_errors.first if connection_errors.any?
+
+          @logger.warn('No tools found from any server.')
+        end
+
+        tools
+      end
+
+      # @param cache [Boolean] whether a cached list may answer
+      # @return [Array<MCPClient::Prompt>]
+      def collect_prompts_from_servers(cache)
+        prompts = []
+        connection_errors = []
+
+        servers.each do |server|
+          refresh_server_cache(server, :prompts) unless cache
+          fingerprint = params_fingerprint_for(server)
+          server_prompts = fetching_from(server) { server.list_prompts }
+          replace_cached_slice(:prompts, @prompt_cache, server, fingerprint) do
+            server_prompts.each do |prompt|
+              @prompt_cache[cache_key_for(server, prompt.name)] = MCPClient::DeepCopy.copy(prompt)
+              prompts << prompt
+            end
+          end
+        rescue MCPClient::Errors::ConnectionError => e
+          # Fast-fail on authorization errors for better user experience
+          raise e if e.message.include?('Authorization failed') && prompts.empty?
+
+          connection_errors << e
+          @logger.error("Server error: #{e.message}")
+        end
+
+        prompts
+      end
+
+      # @param cache [Boolean] whether a cached list may answer
+      # @return [Hash] the aggregated resources result
+      def collect_resources_from_servers(cache)
+        resources = []
+        connection_errors = []
+
+        servers.each do |server|
+          refresh_server_cache(server, :resources) unless cache
+          fingerprint = params_fingerprint_for(server)
+          result = fetching_from(server) { server.list_resources }
+          resource_list = result['resources'] || []
+          replace_cached_slice(:resources, @resource_cache, server, fingerprint) do
+            resource_list.each do |resource|
+              @resource_cache[cache_key_for(server, resource.uri)] = MCPClient::DeepCopy.copy(resource)
+              resources << resource
+            end
+          end
+        rescue MCPClient::Errors::ConnectionError => e
+          # Fast-fail on authorization errors for better user experience
+          raise e if e.message.include?('Authorization failed') && resources.empty?
+
+          connection_errors << e
+          @logger.error("Server error: #{e.message}")
+        end
+
+        # Return hash format consistent with server methods
+        { 'resources' => resources, 'nextCursor' => nil }
+      end
+    end
+  end
+end