robot_lab 0.3.0 → 0.3.1

data/docs/api/mcp/client.md

@@ -1,387 +0,0 @@
-# MCP Client
-
-Connects to MCP servers, discovers tools, and invokes them via the Model Context Protocol.
-
-## Class: `RobotLab::MCP::Client`
-
-```ruby
-client = RobotLab::MCP::Client.new(
-  {
-    name: "filesystem",
-    transport: { type: "stdio", command: "mcp-server-filesystem", args: ["--root", "/data"] }
-  }
-)
-
-client.connect
-tools = client.list_tools
-result = client.call_tool("readFile", { path: "/data/readme.txt" })
-client.disconnect
-```
-
-## Constructor
-
-```ruby
-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 | 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:**
-
-| Key | Type | Required | Description |
-|-----|------|----------|-------------|
-| `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`.
-
-## Attributes
-
-### server
-
-```ruby
-client.server  # => RobotLab::MCP::Server
-```
-
-The MCP server configuration object.
-
-### 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. `connected` is a plain
-reader over the same ivar that `connected?` returns; both are public.
-
-## Methods
-
-### connect
-
-```ruby
-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. 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). Always check `connected?` afterwards.
-
-### disconnect
-
-```ruby
-client.disconnect  # => self
-```
-
-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
-
-```ruby
-client.list_tools  # => Array<Hash>
-```
-
-Discover available tools from the server. Returns an array of tool definition hashes.
-
-**Raises:** `MCPError` if not connected.
-
-### call_tool
-
-```ruby
-result = client.call_tool(name, arguments = {})
-```
-
-Execute a tool on the server.
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `name` | `String` | Tool name |
-| `arguments` | `Hash` | Tool arguments (default: `{}`) |
-
-**Returns:** Tool result content (from the `content` field of the response).
-
-**Raises:** `MCPError` if not connected.
-
-### list_resources
-
-```ruby
-client.list_resources  # => Array<Hash>
-```
-
-List available resources from the server.
-
-**Raises:** `MCPError` if not connected.
-
-### read_resource
-
-```ruby
-client.read_resource(uri)  # => Object
-```
-
-Read a resource by URI.
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `uri` | `String` | Resource URI |
-
-**Raises:** `MCPError` if not connected.
-
-### list_prompts
-
-```ruby
-client.list_prompts  # => Array<Hash>
-```
-
-List available prompts from the server.
-
-**Raises:** `MCPError` if not connected.
-
-### get_prompt
-
-```ruby
-client.get_prompt(name, arguments = {})  # => Hash
-```
-
-Get a prompt by name with optional arguments.
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `name` | `String` | Prompt name |
-| `arguments` | `Hash` | Prompt arguments (default: `{}`) |
-
-**Raises:** `MCPError` if not connected.
-
-### to_h
-
-```ruby
-client.to_h  # => Hash
-```
-
-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
-
-The transport type is determined by the `type` key in the transport hash of the `Server` configuration.
-
-### Stdio
-
-```ruby
-client = RobotLab::MCP::Client.new(
-  {
-    name: "local",
-    transport: {
-      type: "stdio",
-      command: "npx",
-      args: ["@modelcontextprotocol/server-filesystem", "/path"]
-    }
-  }
-)
-```
-
-### WebSocket
-
-```ruby
-client = RobotLab::MCP::Client.new(
-  {
-    name: "remote",
-    transport: {
-      type: "ws",
-      url: "wss://mcp.example.com/ws"
-    }
-  }
-)
-```
-
-### SSE
-
-```ruby
-client = RobotLab::MCP::Client.new(
-  {
-    name: "streaming",
-    transport: {
-      type: "sse",
-      url: "https://mcp.example.com/sse"
-    }
-  }
-)
-```
-
-### Streamable HTTP
-
-```ruby
-client = RobotLab::MCP::Client.new(
-  {
-    name: "http",
-    transport: {
-      type: "streamable-http",
-      url: "https://mcp.example.com/mcp",
-      session_id: "optional-session-id"
-    }
-  }
-)
-```
-
-## Examples
-
-### Basic Usage
-
-```ruby
-client = RobotLab::MCP::Client.new(
-  { 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
-tools.each { |t| puts "#{t[:name]}: #{t[:description]}" }
-
-# Call a tool
-result = client.call_tool("search_repositories", { query: "ruby mcp" })
-puts result
-
-client.disconnect
-```
-
-### From a Server Object
-
-```ruby
-server = RobotLab::MCP::Server.new(
-  name: "neon",
-  transport: { type: "ws", url: "ws://localhost:8080" }
-)
-
-client = RobotLab::MCP::Client.new(server)
-client.connect
-```
-
-### In a Robot
-
-```ruby
-robot = Robot.new(
-  name: "assistant",
-  system_prompt: "You help with file operations.",
-  mcp: [
-    { name: "fs", transport: { type: "stdio", command: "mcp-fs" } }
-  ]
-)
-
-# `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
-  raise RobotLab::MCPError, "not connected" unless client.connected?
-
-  result = client.call_tool("unknown_tool", {})
-rescue RobotLab::MCPError => e
-  puts "MCP error: #{e.message}"
-ensure
-  client.disconnect
-end
-```
-
-## See Also
-
-- [MCP Overview](index.md)
-- [Server Configuration](server.md)
-- [Transports](transports.md)

data/docs/api/mcp/index.md

@@ -1,267 +0,0 @@
-# MCP (Model Context Protocol)
-
-Integration with MCP servers for extended tool capabilities.
-
-## Overview
-
-MCP allows robots to connect to external tool servers, extending their capabilities without modifying robot code. RobotLab provides an MCP client that communicates with MCP-compliant servers over multiple transport types.
-
-```ruby
-robot = Robot.new(
-  name: "developer",
-  system_prompt: "You help with coding tasks.",
-  mcp: [
-    {
-      name: "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
-
-| Component | Description |
-|-----------|-------------|
-| [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
-
-### Using MCP with a Robot
-
-Pass MCP server configurations via the `mcp:` parameter when creating a robot:
-
-```ruby
-robot = Robot.new(
-  name: "assistant",
-  template: :assistant,
-  mcp: [
-    { name: "github", transport: { type: "stdio", command: "mcp-server-github" } }
-  ]
-)
-
-result = robot.run("List my open pull requests", mcp: :inherit, tools: :inherit)
-result.last_text_content
-```
-
-### Connecting at Run Time
-
-`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
-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
-```
-
-`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
-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 |
-|------|------------|----------|
-| `stdio` | `"stdio"` | Local command/subprocess execution |
-| `websocket` | `"ws"` or `"websocket"` | Real-time bidirectional communication |
-| `sse` | `"sse"` | Server-sent events streaming |
-| `streamable-http` | `"streamable-http"` or `"http"` | HTTP request/response with session support |
-
-## MCP Parameter Values
-
-The `mcp:` parameter on a Robot accepts three types of values:
-
-| Value | Meaning |
-|-------|---------|
-| `:none` | No MCP servers (explicitly disabled) |
-| `:inherit` | Resolve against the parent level (network config, then global config) |
-| `Array<Hash>` | Explicit list of server configurations |
-
-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.
-
-`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
-
-`RobotLab::MCPError` is raised when a request is made without an active
-connection, and by the transports for protocol/I-O failures.
-
-**`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.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)
-- [MCP Server](server.md)
-- [Transports](transports.md)