robot_lab 0.3.1 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ae306b218ea8c7c5d68b9de5c0bce088e40a9f1c482278fd54557624bc0ad72
-  data.tar.gz: 92206741b254631a7e09da7247db35702eb12a70409622aa3634c594e83207a0
+  metadata.gz: 7830657dbfe2508c38884f5a117e3b1eb6db6223c0c5336ba8fdbdd3c8718732
+  data.tar.gz: 3df367453aef2881e24e7e718c7778416e932e4f265deca27961bbe1952db483
 SHA512:
-  metadata.gz: 36c52283dfd0edc88cfc71e358a82e463ddfad501a69097ef2aaa28b37f7c5f5d08938d39b1c6312c2b1a3aaf19494895d3bcfd6f74870b4b770942f3ae60d3e
-  data.tar.gz: 1477bf01cb700d41bab40950cd650960676f1589a5f2f4dc8747b1f940e9f21a5b3ff53a15ca4aa2ef01c493b38c1f957406ddc1b365f1592a21b1e6bda1d992
+  metadata.gz: 5f12198c217fa3465274de33a0dfac869eecc51e679f5f65d6d0ee3f0ad18ce9cb14e346b12f35fff6f0fc948ec8dc19e2dfc4eae66afd94a6e4f469a9d2458b
+  data.tar.gz: 7e91d8448bc45512216c1e53ba4dee007c0f40f225a6a34b1b8a51238962b99fd6b26757a6dc842d332ed34ccc73f7a381e404d622ad1e847bfeff5da29c1df0

data/CHANGELOG.md

@@ -8,6 +8,60 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- **OAuth `grant:` from YAML.** An MCP server config such as `oauth: { grant: client_credentials }` raised `ArgumentError: Unknown OAuth grant`, because ruby_llm accepts the grant only as a Symbol. `RobotLab::MCP.define` now converts a String grant to a Symbol.
+
+## [0.5.0] - 2026-11-01
+
+robot_lab 0.4.0: MCP (Model Context Protocol) now runs on ruby_llm 2.1's
+built-in client. robot_lab's own JSON-RPC client, four transports and
+connection poller are gone; a robot's MCP servers are `RubyLLM::MCP`
+objects with the whole protocol surface (tools, resources, prompts, OAuth,
+input requests, long-running tasks, deferred tools), not just tools. This
+is a deliberate breaking release with no legacy API; see "Migrating from
+0.3" in `docs/guides/mcp-integration.md`.
+
+### Changed (BREAKING)
+
+- **ruby_llm 2.1.1 or newer is required** (`ruby_llm ">= 2.1.1", "< 3"`). The `async-http` and `async-websocket` dependencies are dropped.
+- **MCP servers are `RubyLLM::MCP` objects.** `mcp:` (constructor, `RunConfig`, template front matter, `Network#task`) takes an Array mixing config Hashes, `RubyLLM::MCP` instances and `RubyLLM::MCP` subclasses. Hashes become anonymous `RobotLab::MCP::Server` subclasses via `RobotLab::MCP.define`. The `mcp_servers:` constructor keyword is removed; use `mcp:`.
+- **`Robot#mcp` is the robot's `RobotLab::MCP::Registry`** (keyed by server name) and `Robot#with_mcp(*servers)` registers servers on the robot; neither delegates to the chat any more. `robot.mcp[:github]` is the `RubyLLM::MCP` instance: `.tools .call .resources .resource(uri) .prompts .prompt(name, **args) .instructions .close` and the OAuth flow.
+- **MCP tools are `RubyLLM::MCP::Tool` instances**, attached to the chat per run with `with_tools` beside local tools. The per-run `tools:` allowlist, `max_tools` cap and `:none` apply to them exactly as to local tools, and `mcp: :none` on a later run detaches the MCP tools that an earlier run attached while the servers stay registered and connected. Two tools with one name now raise `MCPError` (the message suggests `prefix:`) instead of silently shadowing each other.
+- **Tool calls that require approval fail closed.** A tool a server (or `RubyLLM::Tool.requires_approval`) marks as needing approval is denied with a warning unless the robot has `tool_approval: :approve` or an `on_tool_approval:` Proc.
+- **Only stdio and Streamable HTTP transports exist.** `type: "sse"`, `"ws"` and `"websocket"` raise `MCPError` at build time with guidance; Streamable HTTP must be `https` except on loopback. A `transport:` object that responds to `request`/`notify`/`cancel`/`close` is installed directly.
+- **Timeouts.** `timeout:` is seconds and defaults to ruby_llm's `request_timeout` (was a 15 s default). Values of 1000 or more are still read as milliseconds.
+- **`connect_mcp!` registers and connects the build-time servers**; failures land in `Robot#mcp_failures` / `#failed_mcp_server_names` instead of raising, and a failed server is retried on the next run that selects it.
+- `Robot#to_h` no longer has `mcp_tools` (it would force connections); `mcp_servers` lists registered names and `mcp_failed` appears when any server failed.
+- `RobotLab::Tool.create` no longer takes `mcp:`; `Tool#mcp`, `Tool#mcp?` and the `:mcp` key of `Tool#to_h` are removed.
+- `MCP::ServerDiscovery` runs on every message (not only the first run) and accepts Hashes with symbol or string keys, `RubyLLM::MCP` instances and subclasses.
+
+### Added
+
+- `RobotLab::MCP.build(spec)`, `.define(config)`, `.name_of(spec)`, `.seconds(timeout)` and the `HTTP_TYPES`, `UNSUPPORTED_TYPES`, `IGNORED_KEYS`, `TRANSPORT_KEYS`, `SETTING_KEYS`, `CONNECT_ERRORS` constants. Config keys map onto ruby_llm's DSL: `command`/`args`/`env`/`directory` (or `cwd`), `url`/`headers`/`bearer_token`/`oauth`, `timeout`, `prefix`, `only`, `except`, `requires_approval`, `defer`, `log_level`, `input_requests`, `extensions`, `description`. The flat shape (`transport: stdio` with sibling `command:`/`args:`), which 0.3 front matter used and which failed silently, now works.
+- `RobotLab::MCP::Server < RubyLLM::MCP` with a `description` class macro (used by `ServerDiscovery`) and `#connected?`.
+- `RobotLab::MCP::Registry` — one connection (and one stdio process) per server per robot across runs; re-adding the same Hash, instance or class returns the existing server.
+- `tool_approval`, `on_tool_approval` and `on_input_request` as constructor keywords and `RunConfig` fields. Runs settle approvals, answer or decline MCP input requests (elicitation) and wait on MCP tasks (up to `MCP_TASK_TIMEOUT`, then `MCPError(retryable: true)`) before returning.
+- `Robot#run` accepts a `RubyLLM::MCP::Prompt` (`robot.run(robot.mcp[:github].prompt("code_review", code: diff))`).
+- `:tool_call` hooks now run for MCP tools and plain `RubyLLM::Tool` instances (the chat's `execute_tool` is bridged), with `ToolCallHookContext#mcp_server` and `#mcp?`. A `RubyLLM::MCP::Error` raised mid-call becomes an `{ error: }` tool result instead of aborting the run.
+- `Robot#mcp_failures`, `#mcp_tools(servers)`, `#mcp_server_for(tool)`; servers' deferred tools (`defer:`) are attached with `defer: true`.
+- `RobotLab::Errors.retryable?` treats a `RubyLLM::MCP::Error` without a JSON-RPC code (transport failure) as retryable and one with a code as not.
+- `test/support/fake_mcp_transport.rb`: an in-process MCP transport (not shipped in the gem) that drives the whole stack without a server process.
+
+### Removed
+
+- `RobotLab::MCP::Client`, `RobotLab::MCP::ConnectionPoller`, `RobotLab::MCP::Transports::{Base,Stdio,SSE,WebSocket,StreamableHTTP}` and their tests.
+- `Robot#mcp_clients`, `Robot#mcp_client(name)`, `Robot#inject_mcp!`, the `mcp_servers:` keyword, `MCP::Server::VALID_TRANSPORT_TYPES`, `MCP::Server::DEFAULT_TIMEOUT`.
+
+### Fixed
+
+- JSON-RPC error responses from a server are no longer silently ignored.
+- Servers added after a robot's first run are now connected (the old client only initialized once).
+- Remote servers no longer report `connected?` before the handshake completes.
+- Template front matter in the flat `transport: stdio` form no longer fails silently.
+
+## [0.3.1] - 2026-11-01
+
 ### Changed
 
 - **Minimum Ruby raised to 4.0.9.** `required_ruby_version` is now `>= 4.0.9` (was `>= 3.2.0`), and a `.ruby-version` file pins development to 4.0.9.

data/README.md

@@ -20,7 +20,7 @@
 - <strong>Extensible Tools</strong> - Custom capabilities with graceful error handling<br>
 - <strong>Human-in-the-Loop</strong> - AskUser tool for interactive prompting<br>
 - <strong>Content Streaming</strong> - Stored callbacks, per-call blocks, or both<br>
-- <strong>MCP Integration</strong> - Connect to external tool servers with timeouts and retry<br>
+- <strong>MCP Integration</strong> - Tools, resources and prompts from MCP servers through ruby_llm's built-in client<br>
 - <strong>Local LLM Providers</strong> - LM Studio (via ruby_llm-providers-lms), Ollama, and GPUStack via provider passthrough<br>
 - <strong>Shared Memory</strong> - Reactive key-value store with subscriptions<br>
 - <strong>Message Bus</strong> - Bidirectional robot communication via TypedBus<br>
@@ -347,7 +347,7 @@ result = tool.call({})
 # => "Error (fetch_data): connection refused"
 ```
 
-This applies to all tools — subclasses, factory tools, and MCP tools. For critical tools where you want exceptions to propagate, opt out per class:
+This applies to every `RobotLab::Tool` — subclasses and factory tools. (MCP tools are `RubyLLM::MCP::Tool` instances; a `RubyLLM::MCP::Error` raised during one of their calls becomes an `{ error: }` tool result through the robot's tool-call bridge instead.) For critical tools where you want exceptions to propagate, opt out per class:
 
 ```ruby
 class CriticalTool < RobotLab::Tool
@@ -394,13 +394,13 @@ result = robot.run("Should I start learning Rust?", tools: :inherit)
 ```
 
 > [!WARNING]
-> `run()` defaults to `tools: :none` and `mcp: :none`, and `:none` means **send zero tools this turn**. Attaching tools with `local_tools:` (or servers with `mcp:`) is therefore not enough on its own — a plain `robot.run("...")` sends the LLM no tools at all and connects no MCP servers.
+> `run()` defaults to `tools: :none` and `mcp: :none`, and `:none` means **send zero tools this turn**. Attaching tools with `local_tools:` (or servers with `mcp:`) is therefore not enough on its own — a plain `robot.run("...")` sends the LLM no tools at all and contacts no MCP servers.
 >
 > Pass `tools: :inherit` / `mcp: :inherit` on each run to use what the robot has attached:
 >
 > ```ruby
 > robot.run("...", tools: :inherit)              # send attached tools
-> robot.run("...", mcp: :inherit, tools: :inherit)  # connect MCP + send its tools
+> robot.run("...", mcp: :inherit, tools: :inherit)  # select MCP servers + send their tools
 > ```
 >
 > `:inherit` means "no filter, use everything attached"; an explicit array acts as a name allowlist. Note that `tools: :inherit` at *build* time behaves differently — it resolves against the parent level, so keep `:inherit` on the `run()` call.
@@ -510,39 +510,49 @@ Results are keyed in `result.context` by the **robot's** `name`, not by the task
 
 ## MCP Integration
 
-Connect to external tool servers via Model Context Protocol:
+RobotLab uses ruby_llm's built-in MCP client (`RubyLLM::MCP`, stdio and Streamable HTTP). A server is a config Hash, a `RubyLLM::MCP` subclass, or an instance:
 
 ```ruby
-# Configure MCP server (with optional timeout)
-filesystem_server = {
+# A config Hash — the same shape works in template front matter and Network#task(mcp:)
+filesystem = {
   name: "filesystem",
   transport: {
     type: "stdio",
-    command: "mcp-server-filesystem",
-    args: ["/path/to/allowed/directory"]
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
   },
-  timeout: 30  # seconds (default: 15)
+  timeout: 30  # seconds; absent means ruby_llm's request_timeout
 }
 
-# Create robot with MCP server - tools are auto-discovered
+# Or anything RubyLLM::MCP's class DSL offers
+class GitHub < RubyLLM::MCP
+  command "github-mcp-server", "stdio"
+  env GITHUB_PERSONAL_ACCESS_TOKEN: ENV["GITHUB_PERSONAL_ACCESS_TOKEN"]
+  requires_approval if: :destructive?
+end
+
 robot = RobotLab.build(
   name: "developer",
   template: :developer,
-  mcp: [filesystem_server]
+  mcp: [filesystem, GitHub],
+  tool_approval: :approve   # approval-gated tools are denied unless allowed here or via on_tool_approval:
 )
 
-# Connect. Do this explicitly — run() defaults to mcp: :none, so a plain
-# run() never connects the servers configured above.
+# Servers connect on the first run that selects them; connect_mcp! connects now
 robot.connect_mcp!
-
-# Check connection status
 puts "Failed: #{robot.failed_mcp_server_names}" if robot.failed_mcp_server_names.any?
 
-# Robot can now use filesystem tools — :inherit is required on the run
+# run() defaults to mcp: :none / tools: :none — ask for the servers and their tools per run
 result = robot.run("List the files in the current directory", mcp: :inherit, tools: :inherit)
+
+# The full ruby_llm surface is one lookup away
+robot.mcp[:filesystem].resources
+robot.run(robot.mcp[:git_hub].prompt("code_review", code: diff), mcp: :inherit)
+
+robot.disconnect   # closes every server (stopping stdio processes); they reconnect on next use
 ```
 
-MCP connections are resilient: failed servers are automatically retried on subsequent `run(mcp: :inherit)` calls, and one failing server does not prevent others from connecting. Connection failures are logged and recorded in `failed_mcp_server_names` rather than raised, so a robot whose servers all failed still builds and runs — just without those tools.
+Connection failures are logged, recorded in `robot.mcp_failures` and retried on the next run that selects the server; they are not raised, and one failing server does not stop the others. A `RubyLLM::MCP::Error` during a tool call becomes an `{ error: }` tool result rather than aborting the run. See the [MCP Integration guide](docs/guides/mcp-integration.md), including its "Migrating from 0.3" section.
 
 ## Message Bus
 

data/lib/robot_lab/errors.rb

@@ -28,6 +28,10 @@ module RobotLab
         error.respond_to?(:retryable) && error.retryable == true
       when RobotLab::InferenceError
         true
+      when RubyLLM::MCP::Error
+        # A JSON-RPC error code means the server answered and rejected the
+        # request; no code means the transport failed (timeout, closed pipe).
+        error.code.nil?
       else
         false
       end

data/lib/robot_lab/hook_context.rb

@@ -74,10 +74,11 @@ module RobotLab
   end
 
   class ToolCallHookContext < HookContext
-    attr_reader :tool, :tool_name, :tool_args, :robot
+    attr_reader :tool, :tool_name, :tool_args, :robot, :mcp_server
     attr_accessor :tool_result, :tool_error
 
-    def initialize(tool:, tool_args:, robot: nil, tool_result: nil, tool_error: nil, **)
+    # @param mcp_server [RubyLLM::MCP, nil] the server that owns +tool+ when it is an MCP tool
+    def initialize(tool:, tool_args:, robot: nil, tool_result: nil, tool_error: nil, mcp_server: nil, **)
       super(event: :tool_call, **)
       @tool = tool
       @tool_name = tool.respond_to?(:name) ? tool.name : tool.class.name
@@ -85,6 +86,12 @@ module RobotLab
       @robot = robot
       @tool_result = tool_result
       @tool_error = tool_error
+      @mcp_server = mcp_server
+    end
+
+    # @return [Boolean] whether the tool being called comes from an MCP server
+    def mcp?
+      !@mcp_server.nil?
     end
   end
 

data/lib/robot_lab/mcp/registry.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module MCP
+    # The MCP servers a robot knows, keyed by server name.
+    #
+    # A robot resolves its +mcp+ config on every run. The registry makes that
+    # cheap and side-effect free: adding the same config Hash (by value), the
+    # same +RubyLLM::MCP+ instance, or the same class again returns the server
+    # already built, so a stdio server's process is started once and reused
+    # across runs. Adding a different spec under an existing name closes the
+    # old server and replaces it.
+    #
+    # Servers are closed only by {#delete}, {#clear}, or the robot's
+    # +disconnect+; selecting a subset of servers for one run never closes
+    # the others.
+    class Registry
+      include Enumerable
+
+      def initialize
+        @servers = {}
+        @specs   = {}
+      end
+
+      # Register a server (or return the one already registered for +spec+).
+      #
+      # @param spec [Hash, RubyLLM::MCP, Class<RubyLLM::MCP>]
+      # @return [RubyLLM::MCP]
+      def add(spec)
+        key      = MCP.name_of(spec).to_sym
+        existing = @servers[key]
+        return existing if existing && same_spec?(key, spec, existing)
+
+        existing&.close
+        @specs[key]   = spec
+        @servers[key] = MCP.build(spec)
+      end
+
+      # @param name [String, Symbol]
+      # @return [RubyLLM::MCP, nil]
+      def [](name)
+        @servers[name.to_sym]
+      end
+
+      def key?(name)
+        @servers.key?(name.to_sym)
+      end
+
+      def each(&)
+        @servers.each_value(&)
+      end
+
+      # @return [Array<String>] registered server names, in registration order
+      def names
+        @servers.keys.map(&:to_s)
+      end
+
+      def empty?
+        @servers.empty?
+      end
+
+      def size
+        @servers.size
+      end
+
+      # Close and forget one server.
+      #
+      # @param name [String, Symbol]
+      # @return [RubyLLM::MCP, nil] the removed server
+      def delete(name)
+        key = name.to_sym
+        @specs.delete(key)
+        server = @servers.delete(key)
+        server&.close
+        server
+      end
+
+      # Close and forget every server.
+      #
+      # @return [self]
+      def clear
+        each(&:close)
+        @servers.clear
+        @specs.clear
+        self
+      end
+
+      private
+
+      def same_spec?(key, spec, existing)
+        case spec
+        when RubyLLM::MCP then existing.equal?(spec)
+        when Hash         then @specs[key] == spec
+        else                   @specs[key].equal?(spec)
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/mcp/server.rb

@@ -2,105 +2,69 @@
 
 module RobotLab
   module MCP
-    # Configuration for an MCP server connection
+    # The +RubyLLM::MCP+ subclass that {MCP.build} creates from a config Hash.
     #
-    # @example WebSocket transport
-    #   Server.new(
-    #     name: "neon",
-    #     transport: { type: "ws", url: "ws://localhost:8080" }
-    #   )
+    # Everything a server can do comes from ruby_llm: +tools+, +call+,
+    # +resources+, +resource+, +prompts+, +prompt+, +instructions+, +version+,
+    # +listen+, +close+, the OAuth flow, and so on. This subclass adds only:
     #
-    # @example StdIO transport
-    #   Server.new(
-    #     name: "filesystem",
-    #     transport: {
-    #       type: "stdio",
-    #       command: "mcp-server-filesystem",
-    #       args: ["--root", "/data"]
-    #     }
-    #   )
+    # - a class-level +description+, used by {ServerDiscovery} to pick servers
+    #   relevant to a message;
+    # - +connected?+, true once the server has answered a +tools+ request and
+    #   false again after +close+.
     #
-    class Server
-      # Valid transport types for MCP connections
-      VALID_TRANSPORT_TYPES = %w[stdio sse ws websocket streamable-http http].freeze
+    # Subclass it directly when you want the description macro:
+    #
+    #   class Brew < RobotLab::MCP::Server
+    #     description "Install, update, and manage macOS packages via Homebrew"
+    #     command "mcp-server-brew"
+    #   end
+    # :reek:InstanceVariableAssumption -- @description is a class-level DSL ivar set by the description macro
+    #   and copied by inherited; it has no instance-side initializer by design.
+    class Server < RubyLLM::MCP
+      @description = nil
 
-      # Default timeout for MCP requests (in seconds)
-      DEFAULT_TIMEOUT = 15
+      class << self
+        # Sets or reads a short description of what the server offers.
+        #
+        # @param value [String, nil]
+        # @return [String, nil]
+        def description(value = nil)
+          return @description if value.nil?
 
-      # @!attribute [r] name
-      #   @return [String] the server name
-      # @!attribute [r] transport
-      #   @return [Hash] the transport configuration
-      # @!attribute [r] timeout
-      #   @return [Numeric] request timeout in seconds
-      # @!attribute [r] description
-      #   @return [String] human-readable description used by ServerDiscovery
-      attr_reader :name, :transport, :timeout, :description
+          @description = value.to_s
+        end
 
-      # Creates a new Server configuration.
-      #
-      # @param name [String] the server name
-      # @param transport [Hash] the transport configuration
-      # @param timeout [Numeric, nil] request timeout in seconds (default: 15)
-      # @param description [String, nil] human-readable description for server discovery
-      # @param _extra [Hash] additional keys are silently ignored for forward compatibility
-      # @raise [ArgumentError] if transport type is invalid or required fields are missing
-      def initialize(name:, transport:, timeout: nil, description: nil, **_extra)
-        @name = name.to_s
-        @description = description.to_s
-        @transport = normalize_transport(transport)
-        @timeout = normalize_timeout(timeout)
-        validate!
+        def inherited(subclass) # :nodoc:
+          super
+          subclass.description(@description) if @description
+        end
       end
 
-      # Returns the transport type.
-      #
-      # @return [String] the transport type (stdio, sse, ws, etc.)
-      def transport_type
-        @transport[:type]
+      def initialize(context: nil, **inputs)
+        super
+        @connected = false
       end
 
-      # Converts the server configuration to a hash.
-      #
-      # @return [Hash]
-      def to_h
-        {
-          name: name,
-          description: description,
-          transport: transport,
-          timeout: timeout
-        }
+      # @return [String] the class-level description, or an empty string
+      def description
+        self.class.description.to_s
       end
 
-      private
-
-      def normalize_transport(transport)
-        transport = transport.transform_keys(&:to_sym)
-        transport[:type] = transport[:type].to_s.downcase
-        transport
+      # @return [Boolean] whether the server has answered a tools request since the last close
+      def connected?
+        @connected == true
       end
 
-      def validate!
-        unless VALID_TRANSPORT_TYPES.include?(transport_type)
-          raise ArgumentError, "Invalid transport type: #{transport_type}. " \
-                               "Must be one of: #{VALID_TRANSPORT_TYPES.join(', ')}"
-        end
-
-        case transport_type
-        when "stdio"
-          raise ArgumentError, "StdIO transport requires :command" unless transport[:command]
-        when "ws", "websocket", "sse", "streamable-http", "http"
-          raise ArgumentError, "Transport requires :url" unless transport[:url]
-        end
+      # Lists the server's tools, connecting on the first call (see RubyLLM::MCP#tools).
+      def tools
+        super.tap { @connected = true }
       end
 
-      def normalize_timeout(value)
-        return DEFAULT_TIMEOUT if value.nil?
-
-        seconds = value.to_f
-        # If the caller passed milliseconds (>= 1000), convert to seconds
-        seconds /= 1000.0 if seconds >= 1000
-        [seconds, 1].max
+      # Closes the connection (see RubyLLM::MCP#close). The next request reconnects.
+      def close
+        @connected = false
+        super
       end
     end
   end

data/lib/robot_lab/mcp/server_discovery.rb

@@ -56,9 +56,9 @@ module RobotLab
       # Select MCP servers relevant to the given query.
       #
       # @param query     [String]          user message or intent
-      # @param from      [Array<Hash, MCP::Server>] candidate server configs
+      # @param from      [Array<Hash, RubyLLM::MCP, Class>] candidate server specs
       # @param threshold [Float]           minimum cosine score (default 0.05)
-      # @return [Array<Hash, MCP::Server>] matching servers, or +from+ as
+      # @return [Array<Hash, RubyLLM::MCP, Class>] matching servers, or +from+ as
       #   fallback when no match is found
       # :reek:TooManyStatements -- linear guard/score/filter pipeline; each early return is a documented fallback.
       def self.select(query, from:, threshold: DEFAULT_THRESHOLD)
@@ -77,29 +77,42 @@ module RobotLab
         from
       end
 
-      # @param servers [Array<Hash, MCP::Server>]
+      # @param servers [Array<Hash, RubyLLM::MCP, Class>]
       def self.any_descriptions?(servers)
         servers.any? { |s| !description_for(s).empty? }
       end
 
       # Build the topic string used for similarity scoring: name + description.
       #
-      # @param server [Hash, MCP::Server]
+      # @param server [Hash, RubyLLM::MCP, Class<RubyLLM::MCP>]
       # @return [String]
       def self.topic_text(server)
-        name = server.is_a?(Hash) ? server[:name].to_s : server.name.to_s
-        "#{name} #{description_for(server)}".strip
+        "#{name_for(server)} #{description_for(server)}".strip
       end
 
-      # @param server [Hash, MCP::Server]
+      # @param server [Hash, RubyLLM::MCP, Class<RubyLLM::MCP>]
+      # @return [String] server name or empty string
+      def self.name_for(server)
+        name = case server
+               when Hash  then server[:name] || server['name']
+               when Class then server.default_name
+               else            server.name
+               end
+        name.to_s.strip
+      end
+
+      # @param server [Hash, RubyLLM::MCP, Class<RubyLLM::MCP>]
       # @return [String] description or empty string
       def self.description_for(server)
-        desc = server.is_a?(Hash) ? server[:description] : server.respond_to?(:description) && server.description
+        desc = case server
+               when Hash then server[:description] || server['description']
+               else           (server.description if server.respond_to?(:description))
+               end
         desc.to_s.strip
       end
 
       # @param query  [String]
-      # @param server [Hash, MCP::Server]
+      # @param server [Hash, RubyLLM::MCP, Class]
       # @return [Float] cosine similarity in [0.0, 1.0]
       def self.score(query, server)
         TextAnalysis.tf_cosine_similarity(query, topic_text(server))