activeagent 1.8.1 → 1.9.1

data/lib/active_agent/providers/mcp_bridge.rb

@@ -0,0 +1,691 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "timeout"
+require "uri"
+require "active_support/core_ext/hash/keys"
+require "active_support/core_ext/object/deep_dup"
+require_relative "mcp_tool_cache"
+
+module ActiveAgent
+  module Providers
+    # Runs MCP servers from the client side.
+    #
+    # Declaring `mcps:` is normally passthrough: the declaration is translated
+    # into the provider's own `mcp_servers` parameter and the provider runs the
+    # tool loop. That works only where the provider implements MCP. DeepSeek does
+    # not — it ignores `mcp_servers`, returns 200, and answers without the
+    # server's data, so the failure reads as a poor answer rather than as a
+    # configuration error.
+    #
+    # This bridge closes that gap without the provider's help. It connects to
+    # each declared server, lists the tools it offers, merges them with whatever
+    # tools the caller declared, and answers tool calls on the server that owns
+    # them. The provider's tool loop is untouched: it is handed tools it can call
+    # and receives results, which is all it ever needed.
+    #
+    # The `mcp` gem is loaded only when a bridge is built, so it stays an
+    # optional dependency for anyone who does not declare `mcps:` against a
+    # client-side provider.
+    #
+    # @see ActiveAgent::Providers::MCPServing#mcp_resolved_context
+    class MCPBridge
+      # Raised when a bridge is built without the `mcp` gem installed.
+      class MissingGemError < LoadError; end
+
+      # Raised when two tools would share a name. The model has no way to say
+      # which it meant, so this is refused rather than resolved by guessing.
+      class DuplicateToolError < StandardError; end
+
+      # Raised when a `command:` server does not answer within its
+      # `read_timeout:`. The server has been stopped by the time this reaches
+      # the caller.
+      #
+      # A `Timeout::Error`, as `Net::ReadTimeout` is, so a policy written for
+      # timeouts in general covers this one too.
+      class TimeoutError < ::Timeout::Error; end
+
+      # Schema handed to a tool that declares none. Providers expect an object
+      # schema, and MCP permits omitting it.
+      #
+      # Frozen, and handed out as a copy, because one constant would otherwise
+      # be a single mutable object serving every tool of every server in the
+      # process — a transform that wrote to it would corrupt it for everyone.
+      EMPTY_SCHEMA = { type: "object", properties: {}.freeze }.freeze
+
+      # Seconds to wait for a server to answer before abandoning the connection.
+      #
+      # A stdio read blocks forever without one, so a server that accepts a
+      # request and never replies holds the generation open until the worker is
+      # restarted. Generous, since a tool call can legitimately be slow; set
+      # `read_timeout:` on a declaration to override it. What it bounds depends
+      # on the transport; see {#transport_for}.
+      DEFAULT_READ_TIMEOUT = 30
+
+      # A declared server, paired with the client connected to it.
+      Server = Struct.new(:name, :declaration, :client, keyword_init: true)
+
+      # The result of a tool call that failed on the server: a result the tool
+      # marked `isError`, or a JSON-RPC error the server answered with.
+      #
+      # A provider sends a tool's result to the model as JSON, and this one
+      # serializes as `{"error": message}`, which reads as a failure on an API
+      # that has no error flag. A provider whose API has one also sets it, as
+      # Anthropic does with `is_error`.
+      #
+      # @!attribute [r] message
+      #   @return [String] the error, as the model reads it
+      ErrorResult = Data.define(:message) do
+        # @return [Hash{String => String}]
+        def as_json(*) = { "error" => message }
+
+        # The `json` gem on its own encodes an object as its `to_s`, so this
+        # routes through {#as_json} whether or not ActiveSupport's encoder is
+        # loaded.
+        #
+        # @return [String]
+        def to_json(*args) = as_json.to_json(*args)
+      end
+
+      # @param servers [Array<Hash>, Hash, nil] common-format `mcps:`
+      #   declarations. A single Hash is accepted as a one-server list, because
+      #   `Array(some_hash)` would split it into pairs.
+      def initialize(servers, cache: nil)
+        @declarations = normalize_all(servers)
+        @tools        = nil
+        @ownership    = {}
+        # Every connection attempted, so a failed handshake is still reaped.
+        @servers      = []
+        # Only the connections that succeeded, so a failure is not reused.
+        @connections  = {}
+        @cache        = cache
+      end
+
+      # @return [Boolean] whether no servers were declared
+      def empty? = @declarations.empty?
+
+      # Closes every connection this bridge opened.
+      #
+      # A stdio server is a process this process spawned, and it is reaped only
+      # by its transport's `close` — so a bridge that is simply dropped leaks a
+      # child process per generation, which accumulates in a long-lived worker.
+      # The wrapper exposes no `close` of its own; the transport is where it
+      # lives.
+      #
+      # Idempotent, and deliberately never raises: it runs while a generation is
+      # finishing, often from an `ensure`, and a teardown failure must not
+      # replace the error that generation was already carrying. Closing resets
+      # the discovered tools, so a bridge that is closed and used again
+      # reconnects rather than handing back stale clients.
+      #
+      # @return [void]
+      def close
+        servers      = @servers || []
+        @servers     = []
+        @connections = {}
+        @tools       = nil
+        @ownership   = {}
+
+        servers.each { |server| close_transport(server) }
+
+        nil
+      end
+
+      # Every tool the declared servers offer, in the common format.
+      #
+      # Served from {MCPToolCache} when it has an entry, in which case no
+      # connection is opened at all.
+      #
+      # @return [Array<Hash>]
+      def tools
+        discover if @tools.nil?
+        @tools
+      end
+
+      # Drops the cached tool lists and closes anything open, so the next use
+      # asks the servers again. For a caller that has learned — from a tool the
+      # server no longer provides, say — that its view is stale.
+      #
+      # @return [void]
+      def refresh!
+        @declarations.each { |declaration| MCPToolCache.invalidate(fingerprint_for(declaration)) }
+        close
+      end
+
+      # @param name [String, Symbol] tool name
+      # @return [Boolean] whether a declared server provides this tool
+      def owns?(name)
+        tools
+
+        @ownership.key?(name.to_s)
+      end
+
+      # Whether a call to the tool needs the user's approval, by the
+      # `require_approval` of the declaration that serves it (see
+      # {.approval_required?}).
+      #
+      # @param name [String, Symbol] tool name
+      # @return [Boolean] false for a tool no declared server provides
+      def requires_approval?(name)
+        return false unless owns?(name)
+
+        self.class.approval_required?(@ownership[name.to_s][:require_approval], name)
+      end
+
+      # Whether a declaration's `require_approval` asks for approval of any of
+      # its tools: anything but blank, `"never"`, or a map whose only list,
+      # under `always`, is empty.
+      #
+      # @param policy [String, Symbol, Hash, nil]
+      # @return [Boolean]
+      def self.approval_policy?(policy)
+        return false if policy.blank? || policy.to_s == "never"
+        return true unless policy.is_a?(Hash)
+
+        policy = policy.to_h.transform_keys(&:to_s)
+        policy.key?("never") || !policy.key?("always") || approval_tool_names(policy["always"]).any?
+      end
+
+      # Whether `require_approval` covers a tool. The policy takes the shapes
+      # OpenAI's hosted MCP tool does:
+      #   - `"always"` covers every tool, and `"never"` none
+      #   - a map covers the tools listed under `always`, and, when it lists
+      #     tools under `never`, every tool not listed there. A list is an
+      #     array of names or `{ tool_names: [...] }`.
+      #
+      # Any other policy covers every tool.
+      #
+      # @example
+      #   approval_required?({ never: { tool_names: ["search"] } }, "delete_file") # => true
+      #   approval_required?({ always: ["delete_file"] }, "search")                # => false
+      #
+      # @param policy [String, Symbol, Hash, nil]
+      # @param name [String, Symbol] tool name
+      # @return [Boolean]
+      def self.approval_required?(policy, name)
+        return false unless approval_policy?(policy)
+        return true unless policy.is_a?(Hash)
+
+        policy = policy.to_h.transform_keys(&:to_s)
+        return true if approval_tool_names(policy["always"]).include?(name.to_s)
+        return !approval_tool_names(policy["never"]).include?(name.to_s) if policy.key?("never")
+
+        !policy.key?("always")
+      end
+
+      # @param entry [Array, Hash, nil] a list under `always` or `never`
+      # @return [Array<String>]
+      def self.approval_tool_names(entry)
+        names = entry.is_a?(Hash) ? (entry[:tool_names] || entry["tool_names"]) : entry
+
+        Array(names).map(&:to_s)
+      end
+      private_class_method :approval_tool_names
+
+      # The caller's tools followed by the servers' tools.
+      #
+      # @param declared [Array<Hash>, nil] tools the caller declared
+      # @return [Array<Hash>]
+      # @raise [DuplicateToolError] when a declared tool and a server tool share
+      #   a name
+      def merge_tools(declared)
+        declared = Array(declared)
+        taken    = declared.map { |tool| tool_name(tool) }
+
+        tools.each do |tool|
+          next unless taken.include?(tool[:name])
+
+          fail DuplicateToolError,
+               "A tool named #{tool[:name].inspect} is declared by the agent and also offered by an MCP " \
+               "server, so the model cannot choose between them. Rename one, or restrict the server with " \
+               "`allowed_tools:`."
+        end
+
+        declared + tools
+      end
+
+      # Invokes a tool on the server that owns it.
+      #
+      # @param name [String, Symbol] tool name
+      # @param kwargs [Hash] tool arguments
+      # @return [String, Hash, ErrorResult] the tool's result, or an
+      #   {ErrorResult} when the call failed
+      # @raise [ArgumentError] when no server provides the tool
+      def call(name, **kwargs)
+        self.class.load_mcp!
+
+        tools # populates ownership
+
+        declaration = @ownership.fetch(name.to_s) do
+          fail ArgumentError, "No declared MCP server provides a tool named #{name.to_s.inspect}."
+        end
+
+        server = ensure_connected(declaration)
+
+        begin
+          flatten_result(call_tool_on(server, name.to_s, kwargs))
+        rescue MCP::Client::ServerError => e
+          # The client raises on a JSON-RPC error envelope. The message goes back to the model as the tool's
+          # answer, since it can often recover from a bad argument, where a raise would end the generation.
+          error_message(e.message)
+        end
+      end
+
+      # Loads the `mcp` gem, explaining the dependency if it is absent.
+      #
+      # @return [void]
+      # @raise [MissingGemError]
+      def self.load_mcp!
+        require "mcp"
+      rescue LoadError => e
+        raise MissingGemError,
+              "Using `mcps:` with a provider that has no server-side MCP requires the 'mcp' gem. " \
+              "Add `gem \"mcp\"` to your Gemfile and run `bundle install`. (#{e.message})"
+      end
+
+      private
+
+      # Works out which tools each declared server offers.
+      #
+      # Connections are deliberately left alone: a cache hit means this needs
+      # none, and one that is opened here only to be closed again would defeat
+      # the point.
+      #
+      # @return [void]
+      def discover
+        @tools     = []
+        @ownership = {}
+
+        @declarations.each do |declaration|
+          tools_for(declaration).each do |tool|
+            existing = @ownership[tool[:name]]
+
+            if existing
+              fail DuplicateToolError,
+                   "Two declared MCP servers offer a tool named #{tool[:name].inspect}: " \
+                   "#{existing[:name].to_s.inspect} and #{declaration[:name].to_s.inspect}. The model cannot choose " \
+                   "between them, so rename one or restrict it with `allowed_tools:`."
+            end
+
+            @ownership[tool[:name]] = declaration
+            @tools << tool
+          end
+        end
+      end
+
+      # The tools one declaration offers, from the cache where it can be.
+      #
+      # @param declaration [Hash]
+      # @return [Array<Hash>]
+      def tools_for(declaration)
+        MCPToolCache.fetch(fingerprint_for(declaration), enabled: @cache) do
+          server_tools(ensure_connected(declaration))
+        end
+      end
+
+      # The live connection to a declaration's server, opening it on first use.
+      #
+      # This is what the cache buys: a generation whose tools all come from the
+      # cache and never calls one opens no connection and spawns no process.
+      #
+      # @param declaration [Hash]
+      # @return [Server]
+      def ensure_connected(declaration)
+        @connections[declaration] ||= connect(declaration)
+      end
+
+      # Identifies a declaration for caching purposes.
+      #
+      # Covers what can change the advertised tools: endpoint, credentials,
+      # command environment and tool filter. Credentials are hashed along with
+      # the rest of the declaration; the raw secret is never used as a cache
+      # key. The display name is excluded, so renaming a server does not throw
+      # away its cached tools.
+      #
+      # @param declaration [Hash]
+      # @return [String]
+      def fingerprint_for(declaration)
+        canonical = {
+          url:           declaration[:url],
+          command:       declaration[:command],
+          args:          declaration[:args],
+          env:           declaration[:env]&.sort&.to_h,
+          authorization: declaration[:authorization],
+          authorization_token: declaration[:authorization_token],
+          allowed_tools: declaration[:allowed_tools]&.map { |tool| tool_name(tool) }&.sort
+        }
+
+        Digest::SHA256.hexdigest(JSON.generate(canonical))
+      end
+
+      # Connects a client to one declared server.
+      #
+      # The server is recorded before it is connected, because `connect` starts a
+      # stdio process and only then handshakes: a handshake that fails — a
+      # mistyped command, a server that never answers — has already spawned a
+      # process, and recording it afterwards would leave that process with
+      # nothing to reap it. It is only remembered for reuse once it succeeds.
+      #
+      # @param declaration [Hash]
+      # @return [Server]
+      def connect(declaration)
+        self.class.load_mcp!
+
+        client = MCP::Client.new(transport: transport_for(declaration))
+        server = Server.new(name: declaration[:name], declaration:, client:)
+        @servers << server
+
+        # A `command:` server's handshake opens with a `server/discover` probe that the gem bounds on its own, and
+        # a server that ignores the probe spends that bound before the client falls back to `initialize`. The
+        # deadline allows for it, so the server still has its whole read timeout to answer `initialize`.
+        probe = MCP::Client::Stdio.const_defined?(:DEFAULT_DISCOVER_PROBE_TIMEOUT) ? MCP::Client::Stdio::DEFAULT_DISCOVER_PROBE_TIMEOUT : 0
+        answer_within_read_timeout(server, "the handshake", allowance: probe) { client.connect }
+
+        server
+      end
+
+      # Builds the transport for one declared server.
+      #
+      # `read_timeout:` is validated for either transport, then applied in the
+      # way each one allows:
+      #
+      # - `url:` — set as the read timeout of the server's Faraday connection.
+      #   Faraday's default adapter, Net::HTTP, applies it to each wait for
+      #   data rather than to the whole response, so a streamed answer stays
+      #   open while it keeps sending events. The gem sets a read timeout of its
+      #   own on the standalone listening stream and on a resumed stream, which
+      #   takes precedence there.
+      # - `command:` — not handed to the transport, whose own read timeout
+      #   restarts with every frame it reads, so a server that keeps sending
+      #   notifications never reaches it. Without one, the gem keeps its own
+      #   short bound on the `server/discover` probe. The bridge bounds the whole
+      #   answer itself; see {#answer_within_read_timeout}.
+      #
+      # @param declaration [Hash]
+      # @return [Object] an MCP transport
+      # @raise [ArgumentError] when the declaration names neither a `url:` nor
+      #   a `command:`, or declares a `read_timeout:` that is not a positive,
+      #   finite number
+      def transport_for(declaration)
+        read_timeout = read_timeout_for(declaration)
+
+        if declaration[:url]
+          MCP::Client::HTTP.new(
+            url:     declaration[:url],
+            headers: headers_for(declaration),
+            **{ max_reconnection_wait: declaration[:max_reconnection_wait] }.compact
+          ) { |faraday| faraday.options.read_timeout = read_timeout }
+        elsif declaration[:command]
+          MCP::Client::Stdio.new(
+            command: declaration[:command],
+            args:    Array(declaration[:args]),
+            env:     spawn_env_for(declaration)
+          )
+        else
+          # The keys only: a declaration's values carry credentials, and this message reaches logs.
+          fail ArgumentError,
+               "An entry in `mcps:` needs either a `url:` or a `command:` to connect to; " \
+               "#{declaration[:name].inspect} declares only #{declaration.keys.inspect}."
+        end
+      end
+
+      # The environment a stdio server's process is spawned with. Spawning requires String keys and values,
+      # while a declaration's keys are symbolized on the way in and its values may be numbers or symbols.
+      # A nil value is kept, which unsets the variable.
+      #
+      # @param declaration [Hash]
+      # @return [Hash{String => String, nil}, nil]
+      def spawn_env_for(declaration)
+        declaration[:env]&.to_h { |key, value| [ key.to_s, value&.to_s ] }
+      end
+
+      # The bounded wait for a server to answer.
+      #
+      # @param declaration [Hash]
+      # @return [Numeric]
+      # @raise [ArgumentError] when a declared timeout is not a positive, finite
+      #   number
+      def read_timeout_for(declaration)
+        timeout = declaration[:read_timeout]
+        return DEFAULT_READ_TIMEOUT if timeout.nil?
+
+        unless timeout.is_a?(Numeric) && timeout.positive? && timeout.finite?
+          fail ArgumentError,
+               "`read_timeout:` on an MCP server must be a positive number of seconds, got #{timeout.inspect}."
+        end
+
+        timeout
+      end
+
+      # Calls a tool on its server, within the server's `read_timeout:`.
+      #
+      # @param server [Server]
+      # @param name [String] tool name
+      # @param arguments [Hash] tool arguments
+      # @return [Object] the client's response
+      def call_tool_on(server, name, arguments)
+        answer_within_read_timeout(server, "tools/call for #{name.inspect}") do
+          server.client.call_tool(name:, arguments:)
+        end
+      end
+
+      # Runs one exchange with a server — the handshake, the tool listing or a
+      # tool call — within the server's `read_timeout:`, and returns the
+      # block's result.
+      #
+      # A `url:` server's exchange runs as it is, bounded by its transport; see
+      # {#transport_for}. A `command:` server's runs on a thread of its own,
+      # which this one waits on for at most the timeout, so the bound covers the
+      # whole answer: notifications and pings the server sends meanwhile do not
+      # extend it. A server that misses it is released, which ends the exchange
+      # too, since closing the transport fails the read the thread is blocked in.
+      #
+      # The deadline is kept by waiting rather than with `Timeout.timeout`,
+      # which raises into the running thread at whatever point it has reached,
+      # part-way through writing a request to the server included.
+      #
+      # @param server [Server]
+      # @param request [String] the exchange, as the error names it
+      # @param allowance [Numeric] seconds granted on top of the read timeout
+      # @return [Object] the block's result
+      # @raise [TimeoutError] when a `command:` server does not answer in time
+      def answer_within_read_timeout(server, request, allowance: 0, &exchange)
+        return exchange.call if server.declaration[:url]
+
+        seconds = read_timeout_for(server.declaration) + allowance
+        outcome = Thread::Queue.new
+        worker  = Thread.new do
+          outcome << [ :answered, exchange.call ]
+        rescue Exception => e
+          # Every exception is handed to the waiting thread, which re-raises it, so one that is not a
+          # StandardError still reaches the caller at once rather than surfacing as a timeout.
+          outcome << [ :failed, e ]
+        end
+
+        status, result = outcome.pop(timeout: seconds)
+        raise result if status == :failed
+        return result if status == :answered
+
+        fail TimeoutError,
+             "The MCP server #{server.name.to_s.inspect} did not answer #{request} within #{seconds} seconds, so it " \
+             "was stopped. Increase `read_timeout:` on its `mcps:` entry if it needs longer."
+      ensure
+        # With no outcome, the exchange was abandoned part-way — the deadline passed, or this thread was
+        # interrupted while it waited — and the connection cannot be trusted with another request.
+        release(server) if worker && status.nil?
+      end
+
+      # Gives up on a server whose exchange was abandoned. Its connection is
+      # forgotten, so the next use opens a new one, and its transport is closed,
+      # which stops a `command:` server's process.
+      #
+      # @param server [Server]
+      # @return [void]
+      def release(server)
+        @connections.delete(server.declaration)
+        close_transport(server)
+      end
+
+      # Closes a server's transport, which for a `command:` server stops its
+      # process. Never raises, for the reasons {#close} gives.
+      #
+      # @param server [Server]
+      # @return [void]
+      def close_transport(server)
+        transport = server.client.transport if server.client.respond_to?(:transport)
+        transport.close if transport.respond_to?(:close)
+
+        nil
+      rescue StandardError
+        # Best effort. A server that will not shut down cleanly is not worth an
+        # error that would replace the one its caller is already handling.
+        nil
+      end
+
+      # @return [Hash] a fresh copy of {EMPTY_SCHEMA}, safe for a caller to mutate
+      def empty_schema = EMPTY_SCHEMA.deep_dup
+
+      # @param declaration [Hash]
+      # @return [Hash] request headers for the server
+      def headers_for(declaration)
+        token = declaration[:authorization] || declaration[:authorization_token]
+
+        token.present? ? { "Authorization" => "Bearer #{token}" } : {}
+      end
+
+      # One server's tools, in the common format.
+      #
+      # @param server [Server]
+      # @return [Array<Hash>]
+      def server_tools(server)
+        allowed = Array(server.declaration[:allowed_tools]).map { |tool| tool_name(tool) }
+        allowed = nil if allowed.empty?
+        listed  = answer_within_read_timeout(server, "tools/list") { server.client.tools }
+
+        listed.filter_map do |tool|
+          name = tool.name.to_s
+          next if allowed && !allowed.include?(name)
+
+          {
+            name:        name,
+            description: tool.description,
+            parameters:  tool.input_schema || empty_schema
+          }.compact
+        end
+      end
+
+      # Reduces an MCP tool result to something a provider can hand back to the
+      # model. Structured content is preferred when the server sends it, since
+      # it is the machine-readable form; otherwise the text blocks are joined.
+      # A result the tool marked `isError` becomes an {ErrorResult} carrying
+      # its text, which is where MCP describes a tool's failure.
+      #
+      # `MCP::Client#call_tool` returns the whole JSON-RPC envelope, so the tool
+      # result sits one level down. That is unwrapped first — keyed off the
+      # envelope's own marker rather than the presence of `result`, which a tool
+      # is free to use as a field name.
+      #
+      # @param result [Object]
+      # @return [String, Hash, ErrorResult]
+      def flatten_result(result)
+        result = result.to_h if result.respond_to?(:to_h) && !result.is_a?(Hash)
+        return result unless result.is_a?(Hash)
+
+        if result.key?(:jsonrpc) || result.key?("jsonrpc")
+          error = result[:error] || result["error"]
+          return error_message(error) if error
+
+          result = result[:result] || result["result"] || {}
+        end
+
+        return error_message(text_content(result)) if result[:isError] || result["isError"]
+
+        structured = result[:structuredContent] || result["structuredContent"]
+        return structured if structured
+
+        text_content(result)
+      end
+
+      # Joins the text blocks of a tool result. Blocks without text, such as
+      # images, are left out.
+      #
+      # @param result [Hash]
+      # @return [String]
+      def text_content(result)
+        Array(result[:content] || result["content"]).filter_map do |block|
+          block = block.to_h if block.respond_to?(:to_h) && !block.is_a?(Hash)
+
+          block[:text] || block["text"] if block.is_a?(Hash)
+        end.join("\n")
+      end
+
+      # Wraps the error a failed call reports in an {ErrorResult} for the
+      # model, with a placeholder when the server gave no message. It is
+      # returned as the tool's result rather than raised: the model can often
+      # recover from a bad argument, and a raise here would surface as a failed
+      # generation instead.
+      #
+      # @param error [Hash, String, nil] a JSON-RPC error object, or the text
+      #   describing the failure
+      # @return [ErrorResult]
+      def error_message(error)
+        message = error.is_a?(Hash) ? (error[:message] || error["message"] || error.inspect) : error
+
+        ErrorResult.new(message: message.to_s.presence || "The MCP server returned an empty error.")
+      end
+
+      # @param servers [Array<Hash>, Hash, nil]
+      # @return [Array<Hash>]
+      def normalize_all(servers)
+        return [] if servers.nil?
+        return [ normalize(servers) ] if servers.is_a?(Hash)
+
+        Array(servers).map { |server| normalize(server) }
+      end
+
+      # @param server [Hash]
+      # @return [Hash] declaration with symbolized keys and a display name
+      def normalize(server)
+        unless server.is_a?(Hash)
+          fail ArgumentError, "Each entry in `mcps:` must be a Hash, got #{server.class}."
+        end
+
+        declaration = server.deep_symbolize_keys
+        declaration[:name] ||= default_name(declaration)
+
+        declaration
+      end
+
+      # A display name for a declaration that gave none.
+      #
+      # Deliberately the host rather than the whole URL. An MCP endpoint usually
+      # carries its key in the path (`https://mcp.example.com/<key>/v2/mcp`),
+      # and this name reaches error messages, which reach log aggregators and
+      # error trackers — so the URL is the one part of the declaration that must
+      # not be copied into them.
+      #
+      # @param declaration [Hash]
+      # @return [String]
+      def default_name(declaration)
+        return "command: #{File.basename(declaration[:command].to_s)}" if declaration[:command].present?
+
+        url = declaration[:url]
+        return "unnamed server" if url.blank?
+
+        URI.parse(url).host || "unnamed server"
+      rescue URI::InvalidURIError
+        "unnamed server"
+      end
+
+      # @param tool [Hash, Object, String, Symbol]
+      # @return [String]
+      def tool_name(tool)
+        return (tool[:name] || tool["name"]).to_s if tool.is_a?(Hash)
+        return tool.name.to_s if tool.respond_to?(:name)
+
+        tool.to_s
+      end
+    end
+  end
+end