robot_lab 0.2.1 → 0.2.7

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)

data/docs/api/mcp/server.md

@@ -11,6 +11,7 @@ This is **not** an MCP server implementation -- it is the configuration used by
 ```ruby
 server = RobotLab::MCP::Server.new(
   name: "filesystem",
+  description: "Read, write, and search local files and directories",
   transport: { type: "stdio", command: "mcp-server-filesystem", args: ["--root", "/data"] }
 )
 
@@ -25,7 +26,7 @@ server = RobotLab::MCP::Server.new(
 ## Constructor
 
 ```ruby
-Server.new(name:, transport:, timeout: nil, **_extra)
+Server.new(name:, transport:, timeout: nil, description: nil, **_extra)
 ```
 
 **Parameters:**
@@ -35,6 +36,10 @@ Server.new(name:, transport:, timeout: nil, **_extra)
 | `name` | `String` | **required** | Unique server identifier |
 | `transport` | `Hash` | **required** | Transport configuration (must include `type`) |
 | `timeout` | `Numeric`, `nil` | `15` | Request timeout in seconds. Values >= 1000 are auto-converted from milliseconds. Minimum 1 second |
+| `description` | `String`, `nil` | `""` | Human-readable summary of what the server does; scored by `MCP::ServerDiscovery` |
+
+Any other keyword is absorbed by `**_extra` and silently discarded, so a
+misspelled key raises nothing.
 
 **Raises:** `ArgumentError` if:
 - The transport type is not one of the valid types
@@ -61,6 +66,18 @@ server.name  # => String
 
 The server identifier string.
 
+### description
+
+```ruby
+server.description  # => String
+```
+
+Human-readable summary of the server's capabilities. Always a String — a `nil`
+or omitted `description:` becomes `""`. Used by `MCP::ServerDiscovery`, which
+scores `"#{name} #{description}"` against the user's message when a robot is
+built with `mcp_discovery: true`. Discovery falls back to the full server list
+when no server in the list has a non-empty description.
+
 ### transport
 
 ```ruby
@@ -90,10 +107,14 @@ Returns the transport type string (e.g., `"stdio"`, `"ws"`, `"sse"`).
 ### to_h
 
 ```ruby
-server.to_h  # => { name: "...", transport: { ... }, timeout: 15 }
+server.to_h
+# => { name: "y", description: "", transport: { type: "sse", url: "http://x" }, timeout: 30.0 }
 ```
 
-Converts the server configuration to a hash representation (includes `timeout`).
+Converts the server configuration to a hash representation. The hash is **not**
+compacted — all four keys are always present, and `description` is `""` when it
+was never set. Note that `timeout` is normalized to a Float unless it defaulted
+(`DEFAULT_TIMEOUT` is the Integer `15`).
 
 ## Transport Configuration Options
 
@@ -207,6 +228,9 @@ robot = Robot.new(
   system_prompt: "You help with development tasks.",
   mcp: servers
 )
+
+# `run` defaults to `mcp: :none, tools: :none` — opt in per run
+robot.run("What changed in the repo?", mcp: :inherit, tools: :inherit)
 ```
 
 ### Creating a Client from a Server