robot_lab 0.0.1 → 0.0.4

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)

data/docs/api/mcp/server.md

@@ -1,221 +1,205 @@
-# MCP Server
+# MCP Server Configuration
 
-Expose tools via Model Context Protocol.
+Data structure for MCP server connection configuration.
 
 ## Class: `RobotLab::MCP::Server`
 
-```ruby
-server = RobotLab::MCP::Server.new(name: "my_tools")
+`Server` is a configuration object that defines how to connect to an MCP server. It holds the server name and transport settings, and validates the configuration on construction.
 
-server.add_tool(
-  name: "get_time",
-  description: "Get current time",
-  handler: ->(**_) { Time.now.iso8601 }
-)
+This is **not** an MCP server implementation -- it is the configuration used by `MCP::Client` to establish a connection to an external MCP server.
 
-server.start(transport: :stdio)
+```ruby
+server = RobotLab::MCP::Server.new(
+  name: "filesystem",
+  transport: { type: "stdio", command: "mcp-server-filesystem", args: ["--root", "/data"] }
+)
 ```
 
 ## Constructor
 
 ```ruby
-Server.new(name:, version: "1.0.0")
+Server.new(name:, transport:)
 ```
 
 **Parameters:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `name` | `String` | Server name |
-| `version` | `String` | Server version |
+| `name` | `String` | Unique server identifier |
+| `transport` | `Hash` | Transport configuration (must include `type`) |
 
-## Attributes
+**Raises:** `ArgumentError` if:
+- The transport type is not one of the valid types
+- A stdio transport is missing the `:command` key
+- A network transport (ws, websocket, sse, streamable-http, http) is missing the `:url` key
 
-### name
+## Valid Transport Types
 
 ```ruby
-server.name  # => String
+RobotLab::MCP::Server::VALID_TRANSPORT_TYPES
+# => ["stdio", "sse", "ws", "websocket", "streamable-http", "http"]
 ```
 
-Server identifier.
+## Attributes
 
-### version
+### name
 
 ```ruby
-server.version  # => String
+server.name  # => String
 ```
 
-Server version.
+The server identifier string.
 
-### tools
+### transport
 
 ```ruby
-server.tools  # => Array<Tool>
+server.transport  # => Hash
 ```
 
-Registered tools.
+The normalized transport configuration hash (keys are symbols, type is downcased).
 
 ## Methods
 
-### add_tool
+### transport_type
 
 ```ruby
-server.add_tool(
-  name:,
-  description:,
-  parameters: {},
-  handler:
-)
+server.transport_type  # => String
 ```
 
-Register a tool with the server.
+Returns the transport type string (e.g., `"stdio"`, `"ws"`, `"sse"`).
 
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `name` | `String` | Tool name |
-| `description` | `String` | Tool description |
-| `parameters` | `Hash` | Parameter schema |
-| `handler` | `Proc` | Execution function |
-
-### remove_tool
+### to_h
 
 ```ruby
-server.remove_tool(name)
+server.to_h  # => { name: "...", transport: { ... } }
 ```
 
-Unregister a tool.
+Converts the server configuration to a hash representation.
+
+## Transport Configuration Options
 
-### start
+### Stdio Transport
+
+For local MCP servers running as subprocesses:
 
 ```ruby
-server.start(transport: :stdio, **options)
+Server.new(
+  name: "filesystem",
+  transport: {
+    type: "stdio",
+    command: "mcp-server-filesystem",  # Required
+    args: ["--root", "/data"],          # Optional
+    env: { "DEBUG" => "true" }          # Optional
+  }
+)
 ```
 
-Start the server.
+| Key | Type | Required | Description |
+|-----|------|----------|-------------|
+| `type` | `String` | Yes | Must be `"stdio"` |
+| `command` | `String` | Yes | Executable command |
+| `args` | `Array<String>` | No | Command arguments |
+| `env` | `Hash` | No | Environment variables |
 
-**Transport Options:**
+### WebSocket Transport
 
-| Transport | Options |
-|-----------|---------|
-| `:stdio` | None |
-| `:websocket` | `port:`, `host:` |
-| `:sse` | `port:`, `host:`, `path:` |
-| `:http` | `port:`, `host:`, `path:` |
-
-### stop
+For bidirectional real-time communication:
 
 ```ruby
-server.stop
+Server.new(
+  name: "neon",
+  transport: {
+    type: "ws",
+    url: "ws://localhost:8080"  # Required
+  }
+)
 ```
 
-Stop the server.
+| Key | Type | Required | Description |
+|-----|------|----------|-------------|
+| `type` | `String` | Yes | `"ws"` or `"websocket"` |
+| `url` | `String` | Yes | WebSocket endpoint URL |
 
-## Examples
+### SSE Transport
 
-### Basic Server
+For server-sent events streaming:
 
 ```ruby
-server = RobotLab::MCP::Server.new(name: "utilities")
-
-server.add_tool(
-  name: "echo",
-  description: "Echo back the input",
-  parameters: {
-    message: { type: "string", required: true }
-  },
-  handler: ->(message:) { message }
+Server.new(
+  name: "streaming",
+  transport: {
+    type: "sse",
+    url: "http://localhost:8080/sse"  # Required
+  }
 )
-
-server.start(transport: :stdio)
 ```
 
-### Database Tools Server
+| Key | Type | Required | Description |
+|-----|------|----------|-------------|
+| `type` | `String` | Yes | Must be `"sse"` |
+| `url` | `String` | Yes | SSE endpoint URL |
 
-```ruby
-server = RobotLab::MCP::Server.new(name: "database")
-
-server.add_tool(
-  name: "query_users",
-  description: "Query users by criteria",
-  parameters: {
-    status: { type: "string", enum: ["active", "inactive"] },
-    limit: { type: "integer", default: 10 }
-  },
-  handler: ->(status: nil, limit: 10) {
-    scope = User.all
-    scope = scope.where(status: status) if status
-    scope.limit(limit).map(&:to_h)
-  }
-)
+### Streamable HTTP Transport
 
-server.add_tool(
-  name: "get_user",
-  description: "Get user by ID",
-  parameters: {
-    id: { type: "string", required: true }
-  },
-  handler: ->(id:) {
-    user = User.find_by(id: id)
-    user ? user.to_h : { error: "Not found" }
+For HTTP-based communication with session management:
+
+```ruby
+Server.new(
+  name: "api",
+  transport: {
+    type: "streamable-http",
+    url: "https://server.smithery.ai/neon/mcp",  # Required
+    session_id: "abc123",                         # Optional
+    auth_provider: -> { "Bearer #{token}" }       # Optional
   }
 )
-
-server.start(transport: :websocket, port: 8080)
 ```
 
-### From Robot Tools
+| Key | Type | Required | Description |
+|-----|------|----------|-------------|
+| `type` | `String` | Yes | `"streamable-http"` or `"http"` |
+| `url` | `String` | Yes | HTTP endpoint URL |
+| `session_id` | `String` | No | Session identifier |
+| `auth_provider` | `Proc` | No | Authentication callback returning auth header value |
 
-```ruby
-# Convert existing robot tools to MCP server
-robot = RobotLab.build do
-  name "assistant"
-
-  tool :calculate do
-    description "Perform calculation"
-    parameter :expression, type: :string, required: true
-    handler { |expression:, **_| eval(expression) }
-  end
-end
-
-server = RobotLab::MCP::Server.from_robot(robot)
-server.start(transport: :stdio)
-```
+## Examples
 
-### HTTP Server
+### Multiple Server Configurations
 
 ```ruby
-server = RobotLab::MCP::Server.new(name: "api_tools")
-
-server.add_tool(
-  name: "fetch_data",
-  description: "Fetch data from API",
-  parameters: {
-    endpoint: { type: "string", required: true }
+servers = [
+  {
+    name: "filesystem",
+    transport: { type: "stdio", command: "mcp-server-filesystem", args: ["/data"] }
+  },
+  {
+    name: "github",
+    transport: { type: "stdio", command: "mcp-server-github" }
   },
-  handler: ->(endpoint:) {
-    response = HTTP.get("https://api.example.com/#{endpoint}")
-    JSON.parse(response.body)
+  {
+    name: "database",
+    transport: { type: "ws", url: "ws://localhost:9090" }
   }
-)
+]
 
-server.start(transport: :http, port: 3001, path: "/mcp")
+# Pass directly to a robot
+robot = Robot.new(
+  name: "dev_assistant",
+  system_prompt: "You help with development tasks.",
+  mcp: servers
+)
 ```
 
-### With Resources
+### Creating a Client from a Server
 
 ```ruby
-server = RobotLab::MCP::Server.new(name: "files")
-
-server.add_resource(
-  uri: "file://config",
-  name: "Configuration",
-  description: "Application configuration",
-  handler: -> { File.read("config.yml") }
+server = RobotLab::MCP::Server.new(
+  name: "tools",
+  transport: { type: "ws", url: "ws://localhost:8080" }
 )
 
-server.start(transport: :stdio)
+client = RobotLab::MCP::Client.new(server)
+client.connect
 ```
 
 ## See Also