robot_lab 0.0.1 → 0.0.6

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