robot_lab 0.2.6 → 0.2.7

data/docs/api/index.md

@@ -8,10 +8,50 @@ The fundamental building blocks of RobotLab:
 
 | Class | Description |
 |-------|-------------|
-| [Robot](core/robot.md) | LLM-powered agent with personality and tools |
-| [Network](core/network.md) | Orchestrates multiple robots |
+| [Robot](core/robot.md) | LLM-powered agent with templates, tools, memory, and MCP |
+| [RobotResult](core/result.md) | Value object returned by every `robot.run()` |
+| [Network](core/network.md) | Orchestrates multiple robots as a SimpleFlow pipeline |
 | [Memory](core/memory.md) | Reactive key-value store for sharing data |
+| [StateProxy](core/state.md) | Hash/method-access wrapper returned by `memory.data` |
 | [Tool](core/tool.md) | Custom function robots can call |
+| `RunConfig` | Shared LLM / tool / infrastructure configuration — see [Robot: RunConfig](core/robot.md#runconfig) |
+
+There is **no** `RobotLab::State` class and no `RobotLab::NetworkRun` class. Runtime
+state lives in `Memory`; `memory.data` returns a `StateProxy`.
+
+## Hooks
+
+The framework's extension seam — `Hooks.run` brackets every robot run, network
+run, task, LLM generation, tool call, compaction, and `learn` call:
+
+| Class | Description |
+|-------|-------------|
+| [Hook](hooks.md#robotlabhook) | Handler base class; subclasses implement hooks as class methods |
+| [HookRegistry](hooks.md#robotlabhookregistry) | The store behind `RobotLab.hooks`, `network.hooks`, `robot.hooks` |
+| [Hooks](hooks.md#robotlabhooks) | The dispatcher |
+| [HookContext](hooks.md#robotlabhookcontext) | Base context, plus one subclass per family |
+
+## Skills
+
+`SKILL.md` bundles, the scripts they expose as tools, and the sandbox that
+confines them:
+
+| Class | Description |
+|-------|-------------|
+| [AgentSkill](skills.md#robotlabagentskill) | One skill bundle: instructions + `scripts/` |
+| [AgentSkillCatalog](skills.md#robotlabagentskillcatalog) | Lazy registry over `~/.prompts/skills/` |
+| [Capabilities](skills.md#robotlabcapabilities) | Declared vs. ceiling filesystem / network / timeout grant |
+| [ScriptTool](skills.md#robotlabscripttool) | Wraps an executable script as a `Tool` |
+| [Sandbox](skills.md#robotlabsandbox) | macOS Seatbelt confinement, or a passthrough |
+
+## Support Classes
+
+Everything else with a public surface — `Task`, `Runnable`, `ToolConfig`,
+`ToolManifest`, `Budget::Ledger`, `DoomLoopDetector`, `HistoryCompressor`,
+`Convergence`, `TextAnalysis`, `DelegationFuture`, `RobotMessage`, `BusPoller`,
+`Waiter`, `Narrator`, `Config`, `MCP::ServerDiscovery`,
+`MCP::ConnectionPoller`, and `Streaming::SequenceCounter` — is documented on the
+[Support Classes](support.md) page.
 
 ## Messages
 
@@ -49,16 +89,49 @@ Real-time response streaming:
 
 ```ruby
 # Configuration
-RobotLab.config              # => Config instance
-RobotLab.reload_config!      # => reload from all sources
+RobotLab.config                      # => Config instance
+RobotLab.configure { |c| ... }       # => yields the Config for mutation
+RobotLab.reload_config!              # => reload from all sources
 
 # Building
-RobotLab.build(name:, template:, system_prompt:, context:, **options)
-RobotLab.create_network(name:, concurrency:) { ... }
-RobotLab.create_memory(data:, enable_cache:, **options)
+RobotLab.build(name: "robot", template: nil, system_prompt: nil, context: {},
+               enable_cache: true, bus: nil, skills: nil, config: nil, **options)
+RobotLab.create_network(name:, concurrency: :auto, config: nil) { ... }
+RobotLab.create_memory(data: {}, enable_cache: true, **options)
 
 # Rendering a template to a String (not a robot) -- see Building Robots guide
 RobotLab.render_template(name, **context)  # => String
+
+# Hooks -- see the Hooks API page
+RobotLab.hooks                       # => HookRegistry
+RobotLab.on(HandlerClass, context: nil)
+RobotLab.clear_hooks!                # => replaces the global registry with a fresh one
+
+# Hook scope (internal plumbing; read by Tool#call)
+RobotLab.with_hook_scope(registries, per_run_hooks) { ... }
+RobotLab.current_hook_scope          # => { registries:, per_run_hooks: } or nil
+
+# Extensions
+RobotLab.register_extension(name, mod)
+RobotLab.extension_loaded?(:ractor)  # => Boolean
+RobotLab.extension(:ractor)
+RobotLab.loaded_extensions           # => Array<Symbol>
 ```
 
+`with_hook_scope` publishes the active run's registries in a `Thread.current`
+slot so a tool executing deep inside RubyLLM's tool loop resolves the same
+registries — including the network's and any per-run `hooks:` — instead of
+falling back to `[RobotLab.hooks, robot.hooks]`. It is thread-local, so it does
+not reach a tool that runs on another thread. See
+[Hooks: with_hook_scope](hooks.md#with_hook_scope-current_hook_scope).
+
+!!! warning "Tools and MCP are opt-in per call"
+    `Robot#run` defaults to `tools: :none, mcp: :none`. A bare `robot.run("...")`
+    sends the LLM **zero** tools and connects **no** MCP servers, even when
+    `local_tools:`/`mcp:` were supplied at build time. Pass `tools: :inherit`
+    (and `mcp: :inherit`) at *run* time to use what is attached. For a standalone
+    robot, do not pass `tools: :inherit` at *build* time — it resolves to an
+    allowlist matching nothing. (Inside a network it is the required opt-in to a
+    network `config:` list.) See [Robot: Configuration Hierarchy](core/robot.md#configuration-hierarchy).
+
 See individual class documentation for detailed method references.

data/docs/api/mcp/client.md

@@ -6,8 +6,10 @@ Connects to MCP servers, discovers tools, and invokes them via the Model Context
 
 ```ruby
 client = RobotLab::MCP::Client.new(
-  name: "filesystem",
-  transport: { type: "stdio", command: "mcp-server-filesystem", args: ["--root", "/data"] }
+  {
+    name: "filesystem",
+    transport: { type: "stdio", command: "mcp-server-filesystem", args: ["--root", "/data"] }
+  }
 )
 
 client.connect
@@ -19,16 +21,22 @@ client.disconnect
 ## Constructor
 
 ```ruby
-Client.new(server_or_config)
+Client.new(server_or_config, poller: nil)
 ```
 
+`server_or_config` is **positional**. Passing the server keys directly —
+`Client.new(name: "fs", transport: {...})` — raises
+`ArgumentError: wrong number of arguments (given 0, expected 1)`. Wrap the
+configuration in braces.
+
 Accepts either a `Server` instance or a Hash configuration. When a Hash is provided, it is used to construct a `Server` internally.
 
 **Parameters:**
 
-| Name | Type | Description |
-|------|------|-------------|
-| `server_or_config` | `Server`, `Hash` | Server instance or configuration hash |
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `server_or_config` | `Server`, `Hash` | **required, positional** | Server instance or configuration hash |
+| `poller` | `MCP::ConnectionPoller`, `nil` | `nil` | Shared `IO.select` poller for multiplexing stdio transports (see [ConnectionPoller](#connectionpoller)) |
 
 **Hash Configuration Keys:**
 
@@ -37,6 +45,7 @@ Accepts either a `Server` instance or a Hash configuration. When a Hash is provi
 | `name` | `String` | Yes | Server identifier |
 | `transport` | `Hash` | Yes | Transport configuration (must include `type`) |
 | `timeout` | `Numeric` | No | Request timeout in seconds (default: 15). Propagated to the transport layer |
+| `description` | `String` | No | Human-readable summary used by `MCP::ServerDiscovery` |
 
 **Raises:** `ArgumentError` if the config is neither a `Server` nor a `Hash`.
 
@@ -50,13 +59,24 @@ client.server  # => RobotLab::MCP::Server
 
 The MCP server configuration object.
 
-### connected?
+### transport
+
+```ruby
+client.transport  # => RobotLab::MCP::Transports::Base subclass | nil
+```
+
+The transport instance created by `connect`. `nil` before the first successful
+`connect` and again after `disconnect`.
+
+### connected
 
 ```ruby
+client.connected   # => Boolean
 client.connected?  # => Boolean
 ```
 
-Whether the client is currently connected to the server.
+Whether the client is currently connected to the server. `connected` is a plain
+reader over the same ivar that `connected?` returns; both are public.
 
 ## Methods
 
@@ -66,9 +86,9 @@ Whether the client is currently connected to the server.
 client.connect  # => self
 ```
 
-Establish a connection to the MCP server. Creates the appropriate transport based on the server's transport type, then connects. If already connected, returns immediately.
+Establish a connection to the MCP server. Creates the appropriate transport based on the server's transport type, then connects. If already connected, returns immediately. When a `poller:` was supplied, the client registers itself with the poller after the transport connects.
 
-Connection failures are logged as warnings and the client remains in a disconnected state (does not raise).
+Connection failures are logged as warnings and the client remains in a disconnected state (does not raise). Always check `connected?` afterwards.
 
 ### disconnect
 
@@ -76,7 +96,7 @@ Connection failures are logged as warnings and the client remains in a disconnec
 client.disconnect  # => self
 ```
 
-Close the connection to the MCP server. Closes the underlying transport and resets connection state. If not connected, returns immediately.
+Close the connection to the MCP server. Unregisters from the poller (if any), closes the underlying transport, and resets `transport` to `nil`. If not connected, returns immediately.
 
 ### list_tools
 
@@ -166,7 +186,62 @@ Get a prompt by name with optional arguments.
 client.to_h  # => Hash
 ```
 
-Converts the client to a hash representation containing server config and connection status.
+Converts the client to a hash representation containing server config and connection status:
+
+```ruby
+{ server: { name: "...", description: "...", transport: { ... }, timeout: 15 },
+  connected: false }
+```
+
+## ConnectionPoller
+
+**Class:** `RobotLab::MCP::ConnectionPoller`
+
+By default each stdio client blocks on its own `@stdout.gets` inside a
+`Timeout.timeout`. `ConnectionPoller` replaces that with a single background
+thread running one `IO.select` across every registered stdio transport,
+dispatching each JSON-RPC response to the client that is waiting for it. This is
+useful when one robot talks to several local MCP servers.
+
+It is **opt-in**: nothing in `Robot` or `Network` creates one. `Robot`'s internal
+MCP setup calls `MCP::Client.new(server_config)` with no poller. You get a poller
+only by wiring it yourself.
+
+Async-based transports (SSE, WebSocket, StreamableHTTP) are unaffected — the
+poller silently ignores any client whose transport is not a live `Stdio`.
+
+```ruby
+poller = RobotLab::MCP::ConnectionPoller.new.start
+
+client = RobotLab::MCP::Client.new(
+  { name: "fs", transport: { type: "stdio", command: "mcp-server-fs" } },
+  poller: poller
+)
+
+client.connect          # registers the transport's stdout with the poller
+client.call_tool("readFile", { path: "/data/readme.txt" })
+client.disconnect       # unregisters
+
+poller.stop
+```
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `start` | Start the polling thread (named `RobotLab::MCP::ConnectionPoller`). Idempotent; returns `self` |
+| `stop(timeout: 5)` | Stop the thread, cancelling every pending request with an `MCPError`. Waits up to `timeout` seconds for the thread to join. Returns `self` |
+| `register(client)` | Register a client. Non-stdio (or not-yet-connected) clients are silently ignored |
+| `unregister(client)` | Remove a client's IO from the select set |
+| `send_request(client, message, timeout:)` | Write the JSON-RPC message to the client's stdin and block until the poll loop dispatches the response. Raises `MCPError` on timeout or a broken pipe |
+| `running?` | Whether the polling thread is running |
+
+`POLL_INTERVAL` is `0.1` seconds — the `IO.select` timeout, and the sleep used
+when no clients are registered.
+
+`Client#request` routes through `poller.send_request` only when a poller is
+present **and** the transport is a `Transports::Stdio`; otherwise it calls
+`transport.send_request` directly.
 
 ## Transport Configuration
 
@@ -176,11 +251,13 @@ The transport type is determined by the `type` key in the transport hash of the
 
 ```ruby
 client = RobotLab::MCP::Client.new(
-  name: "local",
-  transport: {
-    type: "stdio",
-    command: "npx",
-    args: ["@modelcontextprotocol/server-filesystem", "/path"]
+  {
+    name: "local",
+    transport: {
+      type: "stdio",
+      command: "npx",
+      args: ["@modelcontextprotocol/server-filesystem", "/path"]
+    }
   }
 )
 ```
@@ -189,10 +266,12 @@ client = RobotLab::MCP::Client.new(
 
 ```ruby
 client = RobotLab::MCP::Client.new(
-  name: "remote",
-  transport: {
-    type: "ws",
-    url: "wss://mcp.example.com/ws"
+  {
+    name: "remote",
+    transport: {
+      type: "ws",
+      url: "wss://mcp.example.com/ws"
+    }
   }
 )
 ```
@@ -201,10 +280,12 @@ client = RobotLab::MCP::Client.new(
 
 ```ruby
 client = RobotLab::MCP::Client.new(
-  name: "streaming",
-  transport: {
-    type: "sse",
-    url: "https://mcp.example.com/sse"
+  {
+    name: "streaming",
+    transport: {
+      type: "sse",
+      url: "https://mcp.example.com/sse"
+    }
   }
 )
 ```
@@ -213,11 +294,13 @@ client = RobotLab::MCP::Client.new(
 
 ```ruby
 client = RobotLab::MCP::Client.new(
-  name: "http",
-  transport: {
-    type: "streamable-http",
-    url: "https://mcp.example.com/mcp",
-    session_id: "optional-session-id"
+  {
+    name: "http",
+    transport: {
+      type: "streamable-http",
+      url: "https://mcp.example.com/mcp",
+      session_id: "optional-session-id"
+    }
   }
 )
 ```
@@ -228,11 +311,11 @@ client = RobotLab::MCP::Client.new(
 
 ```ruby
 client = RobotLab::MCP::Client.new(
-  name: "github",
-  transport: { type: "stdio", command: "mcp-server-github" }
+  { name: "github", transport: { type: "stdio", command: "mcp-server-github" } }
 )
 
 client.connect
+raise "could not connect" unless client.connected?
 
 # List available tools
 tools = client.list_tools
@@ -268,16 +351,27 @@ robot = Robot.new(
   ]
 )
 
-# MCP tools are automatically discovered and available to the LLM
-result = robot.run("Read the contents of /data/config.yml")
+# `Robot#run` defaults to `mcp: :none, tools: :none`. Opt in on every run that
+# should reach the MCP servers: `mcp: :inherit` connects them, `tools: :inherit`
+# forwards the discovered tools to the model.
+result = robot.run("Read the contents of /data/config.yml", mcp: :inherit, tools: :inherit)
 puts result.last_text_content
 ```
 
+MCP connection failures inside a robot are logged and recorded in
+`robot.failed_mcp_server_names`; they never raise out of `run`.
+
 ### Error Handling
 
+`connect` swallows its own failures, so test `connected?` rather than rescuing
+around it:
+
 ```ruby
+client.connect
+
 begin
-  client.connect
+  raise RobotLab::MCPError, "not connected" unless client.connected?
+
   result = client.call_tool("unknown_tool", {})
 rescue RobotLab::MCPError => e
   puts "MCP error: #{e.message}"

data/docs/api/mcp/index.md

@@ -13,10 +13,17 @@ robot = Robot.new(
   mcp: [
     {
       name: "filesystem",
-      transport: { type: "stdio", command: "npx @modelcontextprotocol/server-filesystem" }
+      transport: {
+        type: "stdio",
+        command: "npx",
+        args: ["@modelcontextprotocol/server-filesystem", "/data"]
+      }
     }
   ]
 )
+
+# MCP is opt-in per run — see "Connecting at Run Time" below.
+result = robot.run("What files are in /data?", mcp: :inherit, tools: :inherit)
 ```
 
 ## Components
@@ -26,6 +33,8 @@ robot = Robot.new(
 | [Client](client.md) | Connects to MCP servers, lists tools, calls tools |
 | [Server](server.md) | Server configuration data structure |
 | [Transports](transports.md) | Communication methods (stdio, WebSocket, SSE, HTTP) |
+| [ConnectionPoller](client.md#connectionpoller) | Optional shared `IO.select` loop multiplexing several stdio transports |
+| `MCP::ServerDiscovery` | Picks the relevant subset of configured servers for a message (see [Server Discovery](#server-discovery)) |
 
 ## Quick Start
 
@@ -42,33 +51,91 @@ robot = Robot.new(
   ]
 )
 
-result = robot.run("List my open pull requests")
+result = robot.run("List my open pull requests", mcp: :inherit, tools: :inherit)
 result.last_text_content
 ```
 
-### MCP in Networks
+### Connecting at Run Time
 
-Robots in a network can inherit MCP servers from the network or define their own:
+`Robot#run` defaults to `mcp: :none, tools: :none`. Those defaults mean "connect
+nothing and send zero tools for this turn", so a bare `robot.run("...")` reaches
+the LLM with **no** MCP servers connected and **no** tools attached, even when
+`mcp:` was supplied at build time.
 
 ```ruby
-network_mcp = [
-  { name: "github", transport: { type: "stdio", command: "mcp-server-github" } }
-]
+robot.run("...")                                  # no MCP, no tools
+robot.run("...", tools: :inherit)                 # attached local tools only
+robot.run("...", mcp: :inherit, tools: :inherit)  # connect MCP servers AND send their tools
+```
 
-robot = Robot.new(
-  name: "assistant",
-  template: :assistant,
-  mcp: :inherit  # Use network's MCP servers
-)
+`mcp: :inherit` triggers the connection attempt; `tools: :inherit` is what
+actually forwards the discovered MCP tools to the model. Both are needed.
+
+!!! warning "Build-time `:inherit` depends on whether there is a parent"
+    `resolve_mcp_hierarchy` does not freeze the parent at construction — it
+    recomputes it on **every run** as
+    `network_config&.mcp || network_parent_config(network)&.mcp || RobotLab.config.mcp`,
+    then resolves the build-time value against it, then the runtime value against
+    *that*.
+
+    - For a **standalone** robot the parent is the global default `:none`, so a
+      build-time `mcp: :inherit` / `tools: :inherit` collapses to an allowlist
+      that matches nothing. Give the standalone robot an explicit array at build
+      time and pass `:inherit` at run time.
+    - **Inside a network** whose `config:` sets `mcp:`/`tools:`, build-time
+      `:inherit` is exactly how a robot opts in to the network's list — see
+      [MCP in Networks](#mcp-in-networks) below.
+
+`robot.connect_mcp!` connects eagerly, but a later plain `run()` still sends no
+tools. Connection failures are logged and recorded in
+`robot.failed_mcp_server_names` — they are not raised.
+
+### MCP in Networks
+
+A robot can inherit its MCP server list from the network's `config:`. This is one
+of only two fields (`mcp` and `tools`) that a network-level `RunConfig`
+propagates to member robots, and only when the robot opts in with `:inherit`:
+
+```ruby
+network = RobotLab.create_network(
+  name: "dev",
+  config: RobotLab::RunConfig.new(
+    mcp: [{ name: "github", transport: { type: "stdio", command: "mcp-server-github" } }]
+  )
+) do |n|
+  n.task :assistant,
+         Robot.new(name: "assistant", template: :assistant, mcp: :inherit),
+         mcp: :inherit, tools: :inherit
+end
 ```
 
+Here the build-time `mcp: :inherit` on the robot is correct and necessary: the
+parent is resolved at run time from the network's `config:`, so `:inherit` picks
+up the network's server list rather than the global `:none`.
+
+`Network#task` has the same `mcp: :none, tools: :none` defaults as `Robot#run`,
+so the task must opt in as well — otherwise the inherited list collapses to `[]`.
+
+LLM fields (`model`, `temperature`, ...) and callbacks are **not** inherited from
+a network config; each robot reads those from its own configuration.
+
 ### Direct Client Usage
 
+`Client.new` takes the server (or config hash) as a **positional** argument:
+
 ```ruby
 client = RobotLab::MCP::Client.new(
   name: "filesystem",
   transport: { type: "stdio", command: "mcp-server-filesystem", args: ["--root", "/data"] }
 )
+# ArgumentError: wrong number of arguments (given 0, expected 1)
+
+client = RobotLab::MCP::Client.new(
+  {
+    name: "filesystem",
+    transport: { type: "stdio", command: "mcp-server-filesystem", args: ["--root", "/data"] }
+  }
+)
 
 client.connect
 tools = client.list_tools
@@ -76,6 +143,34 @@ result = client.call_tool("readFile", { path: "/data/config.yml" })
 client.disconnect
 ```
 
+### Server Discovery
+
+When a robot is built with `mcp_discovery: true`, the configured server list is
+filtered before connecting: `MCP::ServerDiscovery` scores each server's
+`name + description` against the user's message using term-frequency cosine
+similarity and connects only the servers scoring at or above the threshold
+(`DEFAULT_THRESHOLD` = 0.05).
+
+```ruby
+robot = RobotLab.build(
+  name: "assistant",
+  mcp_discovery: true,
+  mcp: [
+    { name: "filesystem", description: "Read, write, and search local files",
+      transport: { type: "stdio", command: "mcp-server-fs" } },
+    { name: "brew", description: "Install and manage macOS packages via Homebrew",
+      transport: { type: "stdio", command: "mcp-server-brew" } }
+  ]
+)
+
+# Connects only the "brew" server for this message
+robot.run("install imagemagick", mcp: :inherit, tools: :inherit)
+```
+
+Discovery falls back to the **full** server list when no server has a
+`description`, when the query is blank, when no server clears the threshold, or
+when the optional `classifier` gem is unavailable.
+
 ## Transport Types
 
 | Type | Config Key | Use Case |
@@ -92,33 +187,79 @@ The `mcp:` parameter on a Robot accepts three types of values:
 | Value | Meaning |
 |-------|---------|
 | `:none` | No MCP servers (explicitly disabled) |
-| `:inherit` | Use the network's MCP servers |
+| `:inherit` | Resolve against the parent level (network config, then global config) |
 | `Array<Hash>` | Explicit list of server configurations |
 
-Each server configuration hash requires:
+Each server configuration hash is passed straight to `MCP::Server.new`:
+
+| Key | Type | Required | Description |
+|-----|------|----------|-------------|
+| `name` | `String` | Yes | Unique server identifier |
+| `transport` | `Hash` | Yes | Transport configuration (must include `type`) |
+| `timeout` | `Numeric` | No | Request timeout in seconds (default: 15) |
+| `description` | `String` | No | Human-readable summary; the text `ServerDiscovery` scores against |
+
+`transport:` must be a **nested hash**. A flat `transport: "stdio"` with sibling
+`command:`/`args:` keys raises internally (`NoMethodError: undefined method
+'transform_keys' for an instance of String`). `init_mcp_client` rescues it rather
+than re-raising, so the robot still builds — but with zero tools from that
+server. It is not silent: the failure is logged at `warn` through
+`RobotLab.config.logger` (`"Robot '<name>' error connecting to MCP server
+'<server>': ..."`) and the server is recorded in
+`robot.failed_mcp_server_names`. The same holds for an invalid transport type
+reached through the robot path.
 
-| Key | Type | Description |
-|-----|------|-------------|
-| `name` | `String` | Unique server identifier |
-| `transport` | `Hash` | Transport configuration (must include `type`) |
+`MCP::Server#initialize` ends in `**_extra`, so any other key you add is
+accepted and silently discarded — a typo in `timeout` or `description` will not
+raise.
 
 ## Error Handling
 
-MCP operations raise `RobotLab::MCPError` when:
+`RobotLab::MCPError` is raised when a request is made without an active
+connection, and by the transports for protocol/I-O failures.
 
-- Connection to a server fails
-- A request is made without an active connection
-- An unsupported transport type is specified
+**`Client#connect` does not raise.** It rescues every `StandardError` — including
+a failed transport handshake and an unsupported transport type — logs a warning,
+and leaves the client disconnected. Check `client.connected?` after connecting:
 
 ```ruby
+client.connect
+
+unless client.connected?
+  warn "MCP server unavailable"
+  return
+end
+
 begin
-  client.connect
   client.call_tool("unknown_tool", {})
 rescue RobotLab::MCPError => e
   puts "MCP error: #{e.message}"
 end
 ```
 
+An invalid transport type or a missing `command`/`url` raises `ArgumentError`
+from `MCP::Server.new` — and because `MCP::Client.new` builds the server, from
+`Client.new` too:
+
+```ruby
+RobotLab::MCP::Server.new(name: "x", transport: { type: "bogus", command: "z" })
+# ArgumentError: Invalid transport type: bogus. Must be one of:
+#   stdio, sse, ws, websocket, streamable-http, http
+```
+
+That `ArgumentError` only reaches you when you construct the server or client
+**directly**. Through the robot path it is rescued like any other connect
+failure — `init_mcp_client` logs it at `warn` and adds the server to
+`failed_mcp_server_names`:
+
+```ruby
+robot = RobotLab.build(name: "t", system_prompt: "hi",
+                       mcp: [{ name: "x", transport: { type: "bogus", command: "z" } }])
+robot.connect_mcp!
+# WARN -- : Robot 't' error connecting to MCP server 'x': Invalid transport type: bogus...
+robot.failed_mcp_server_names  # => ["x"]
+```
+
 ## See Also
 
 - [MCP Client](client.md)