robot_lab 0.0.1 → 0.0.6

data/docs/api/mcp/client.md

@@ -1,49 +1,53 @@
 # MCP Client
 
-Connects to MCP servers and discovers tools.
+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" }
+  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(name:, transport:)
+Client.new(server_or_config)
 ```
 
+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 |
 |------|------|-------------|
-| `name` | `String` | Server identifier |
-| `transport` | `Hash` | Transport configuration |
+| `server_or_config` | `Server`, `Hash` | Server instance or configuration hash |
 
-## Attributes
+**Hash Configuration Keys:**
 
-### name
+| Key | Type | Required | Description |
+|-----|------|----------|-------------|
+| `name` | `String` | Yes | Server identifier |
+| `transport` | `Hash` | Yes | Transport configuration (must include `type`) |
 
-```ruby
-client.name  # => String
-```
+**Raises:** `ArgumentError` if the config is neither a `Server` nor a `Hash`.
 
-Server identifier.
+## Attributes
 
-### transport
+### server
 
 ```ruby
-client.transport  # => Transport
+client.server  # => RobotLab::MCP::Server
 ```
 
-The underlying transport connection.
+The MCP server configuration object.
 
 ### connected?
 
@@ -51,38 +55,42 @@ The underlying transport connection.
 client.connected?  # => Boolean
 ```
 
-Whether the client is connected.
+Whether the client is currently connected to the server.
 
 ## Methods
 
 ### connect
 
 ```ruby
-client.connect
+client.connect  # => self
 ```
 
-Establish connection to the MCP server.
+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.
+
+Connection failures are logged as warnings and the client remains in a disconnected state (does not raise).
 
 ### disconnect
 
 ```ruby
-client.disconnect
+client.disconnect  # => self
 ```
 
-Close the connection.
+Close the connection to the MCP server. Closes the underlying transport and resets connection state. If not connected, returns immediately.
 
 ### list_tools
 
 ```ruby
-client.list_tools  # => Array<Tool>
+client.list_tools  # => Array<Hash>
 ```
 
-Discover available tools from the server.
+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, params)
+result = client.call_tool(name, arguments = {})
 ```
 
 Execute a tool on the server.
@@ -92,30 +100,81 @@ Execute a tool on the server.
 | Name | Type | Description |
 |------|------|-------------|
 | `name` | `String` | Tool name |
-| `params` | `Hash` | Tool parameters |
+| `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<Resource>
+client.list_resources  # => Array<Hash>
 ```
 
-List available resources (if supported).
+List available resources from the server.
+
+**Raises:** `MCPError` if not connected.
 
 ### read_resource
 
 ```ruby
-client.read_resource(uri)  # => Resource
+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.
+
 ## Transport Configuration
 
+The transport type is determined by the `type` key in the transport hash of the `Server` configuration.
+
 ### Stdio
 
 ```ruby
-client = Client.new(
+client = RobotLab::MCP::Client.new(
   name: "local",
   transport: {
     type: "stdio",
@@ -128,10 +187,10 @@ client = Client.new(
 ### WebSocket
 
 ```ruby
-client = Client.new(
+client = RobotLab::MCP::Client.new(
   name: "remote",
   transport: {
-    type: "websocket",
+    type: "ws",
     url: "wss://mcp.example.com/ws"
   }
 )
@@ -140,7 +199,7 @@ client = Client.new(
 ### SSE
 
 ```ruby
-client = Client.new(
+client = RobotLab::MCP::Client.new(
   name: "streaming",
   transport: {
     type: "sse",
@@ -149,14 +208,15 @@ client = Client.new(
 )
 ```
 
-### HTTP
+### Streamable HTTP
 
 ```ruby
-client = Client.new(
+client = RobotLab::MCP::Client.new(
   name: "http",
   transport: {
-    type: "http",
-    url: "https://mcp.example.com/mcp"
+    type: "streamable-http",
+    url: "https://mcp.example.com/mcp",
+    session_id: "optional-session-id"
   }
 )
 ```
@@ -166,7 +226,7 @@ client = Client.new(
 ### Basic Usage
 
 ```ruby
-client = Client.new(
+client = RobotLab::MCP::Client.new(
   name: "github",
   transport: { type: "stdio", command: "mcp-server-github" }
 )
@@ -175,7 +235,7 @@ client.connect
 
 # List available tools
 tools = client.list_tools
-tools.each { |t| puts "#{t.name}: #{t.description}" }
+tools.each { |t| puts "#{t[:name]}: #{t[:description]}" }
 
 # Call a tool
 result = client.call_tool("search_repositories", { query: "ruby mcp" })
@@ -184,19 +244,32 @@ puts result
 client.disconnect
 ```
 
-### In Robot
+### From a Server Object
 
 ```ruby
-robot = RobotLab.build do
-  name "assistant"
+server = RobotLab::MCP::Server.new(
+  name: "neon",
+  transport: { type: "ws", url: "ws://localhost:8080" }
+)
 
-  mcp [
+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" } }
   ]
-end
+)
 
-# MCP tools are automatically available
-robot.tools.each { |t| puts t.name }
+# MCP tools are automatically discovered and available to the LLM
+result = robot.run("Read the contents of /data/config.yml")
+puts result.last_text_content
 ```
 
 ### Error Handling
@@ -205,10 +278,8 @@ robot.tools.each { |t| puts t.name }
 begin
   client.connect
   result = client.call_tool("unknown_tool", {})
-rescue RobotLab::MCP::ConnectionError => e
-  puts "Failed to connect: #{e.message}"
-rescue RobotLab::MCP::ToolError => e
-  puts "Tool error: #{e.message}"
+rescue RobotLab::MCPError => e
+  puts "MCP error: #{e.message}"
 ensure
   client.disconnect
 end
@@ -217,5 +288,5 @@ end
 ## See Also
 
 - [MCP Overview](index.md)
+- [Server Configuration](server.md)
 - [Transports](transports.md)
-- [MCP Server](server.md)

data/docs/api/mcp/index.md

@@ -4,108 +4,123 @@ 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.
+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 = RobotLab.build do
-  name "developer"
-  template "You help with coding tasks."
-
-  mcp [
+robot = Robot.new(
+  name: "developer",
+  system_prompt: "You help with coding tasks.",
+  mcp: [
     {
       name: "filesystem",
       transport: { type: "stdio", command: "npx @modelcontextprotocol/server-filesystem" }
     }
   ]
-end
+)
 ```
 
 ## Components
 
 | Component | Description |
 |-----------|-------------|
-| [Client](client.md) | Connects to MCP servers |
-| [Server](server.md) | Exposes tools via MCP |
-| [Transports](transports.md) | Communication methods |
+| [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) |
 
 ## Quick Start
 
-### Using MCP Tools
+### Using MCP with a Robot
 
-```ruby
-network = RobotLab.create_network do
-  name "with_mcp"
+Pass MCP server configurations via the `mcp:` parameter when creating a robot:
 
-  mcp [
+```ruby
+robot = Robot.new(
+  name: "assistant",
+  template: :assistant,
+  mcp: [
     { name: "github", transport: { type: "stdio", command: "mcp-server-github" } }
   ]
+)
 
-  add_robot RobotLab.build {
-    name "assistant"
-    template "You help with GitHub tasks."
-    mcp :inherit  # Use network's MCP servers
-  }
-end
+result = robot.run("List my open pull requests")
+result.last_text_content
 ```
 
-### Creating an MCP Server
+### MCP in Networks
+
+Robots in a network can inherit MCP servers from the network or define their own:
 
 ```ruby
-server = RobotLab::MCP::Server.new(name: "my_tools")
+network_mcp = [
+  { name: "github", transport: { type: "stdio", command: "mcp-server-github" } }
+]
+
+robot = Robot.new(
+  name: "assistant",
+  template: :assistant,
+  mcp: :inherit  # Use network's MCP servers
+)
+```
+
+### Direct Client Usage
 
-server.add_tool(
-  name: "get_user",
-  description: "Get user by ID",
-  parameters: { id: { type: "string", required: true } },
-  handler: ->(id:) { User.find(id).to_h }
+```ruby
+client = RobotLab::MCP::Client.new(
+  name: "filesystem",
+  transport: { type: "stdio", command: "mcp-server-filesystem", args: ["--root", "/data"] }
 )
 
-server.start(transport: :stdio)
+client.connect
+tools = client.list_tools
+result = client.call_tool("readFile", { path: "/data/config.yml" })
+client.disconnect
 ```
 
 ## Transport Types
 
-| Type | Use Case |
-|------|----------|
-| `stdio` | Local command execution |
-| `websocket` | Real-time bidirectional |
-| `sse` | Server-sent events |
-| `http` | HTTP request/response |
+| 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 |
 
-## Configuration Levels
+## MCP Parameter Values
 
-### Network Level
+The `mcp:` parameter on a Robot accepts three types of values:
 
-```ruby
-network = RobotLab.create_network do
-  mcp [
-    { name: "server1", transport: { type: "stdio", command: "..." } }
-  ]
-end
-```
+| Value | Meaning |
+|-------|---------|
+| `:none` | No MCP servers (explicitly disabled) |
+| `:inherit` | Use the network's MCP servers |
+| `Array<Hash>` | Explicit list of server configurations |
 
-### Robot Level
+Each server configuration hash requires:
 
-```ruby
-robot = RobotLab.build do
-  mcp :inherit  # Use network's servers
-  # or
-  mcp :none     # No MCP servers
-  # or
-  mcp [...]     # Specific servers
-end
-```
+| Key | Type | Description |
+|-----|------|-------------|
+| `name` | `String` | Unique server identifier |
+| `transport` | `Hash` | Transport configuration (must include `type`) |
+
+## Error Handling
+
+MCP operations raise `RobotLab::MCPError` when:
 
-### Tool Filtering
+- Connection to a server fails
+- A request is made without an active connection
+- An unsupported transport type is specified
 
 ```ruby
-robot = RobotLab.build do
-  mcp :inherit
-  tools %w[read_file write_file]  # Only allow these tools
+begin
+  client.connect
+  client.call_tool("unknown_tool", {})
+rescue RobotLab::MCPError => e
+  puts "MCP error: #{e.message}"
 end
 ```
 
 ## See Also
 
-- [MCP Integration Guide](../../guides/mcp-integration.md)
-- [Tool](../core/tool.md)
+- [MCP Client](client.md)
+- [MCP Server](server.md)
+- [Transports](transports.md)