@hotmeshio/long-tail 0.4.18 → 0.4.19

package/docs/api/http/mcp-endpoint.md

@@ -0,0 +1,133 @@
+# MCP Endpoint
+
+Long Tail exposes its full tool surface via the MCP (Model Context Protocol) streamable-http transport at `/mcp`. External MCP clients — Claude Desktop, Cursor, other agents, or custom applications — connect to this endpoint to discover and invoke tools.
+
+All requests require authentication via `Authorization: Bearer <token>`.
+
+## Connection
+
+```
+POST /mcp
+Authorization: Bearer <api-key>
+Content-Type: application/json
+Accept: application/json, text/event-stream
+```
+
+The endpoint uses stateless mode — each request is self-contained. No session management required.
+
+### Connecting with the MCP SDK
+
+```typescript
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+
+const transport = new StreamableHTTPClientTransport(
+  new URL('http://localhost:3000/mcp'),
+  {
+    requestInit: {
+      headers: { 'Authorization': `Bearer ${apiKey}` },
+    },
+  },
+);
+
+const client = new Client({ name: 'my-app', version: '1.0.0' });
+await client.connect(transport);
+
+// Discover tools
+const { tools } = await client.listTools();
+console.log(`${tools.length} tools available`);
+
+// Invoke a tool
+const result = await client.callTool({
+  name: 'list_roles',
+  arguments: {},
+});
+```
+
+### Connecting with curl
+
+```bash
+# Initialize
+curl -X POST http://localhost:3000/mcp \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}},"id":1}'
+
+# List tools
+curl -X POST http://localhost:3000/mcp \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}'
+
+# Call a tool
+curl -X POST http://localhost:3000/mcp \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_settings","arguments":{}},"id":3}'
+```
+
+## Authentication
+
+Two token types are supported:
+
+| Type | Format | Use case |
+|------|--------|----------|
+| JWT | Standard Bearer token from `POST /api/auth/login` | Interactive sessions, testing |
+| API key | `lt_bot_*` prefix | Service accounts, automation |
+
+### Service Account Setup
+
+1. Create a service account: `POST /api/bot-accounts`
+2. Generate an API key with scopes: `POST /api/bot-accounts/:id/api-keys`
+3. Use the key as a Bearer token for `/mcp` requests
+
+## Scopes
+
+API key scopes control which tools are visible:
+
+| Scope | Tools | Description |
+|-------|-------|-------------|
+| `mcp:read` | 57 | Read-safe tools only — queries, listings, discovery |
+| `mcp:read` + `mcp:full` | 110 | All tools — can modify state |
+
+A read key cannot invoke write operations (create, update, delete, invoke workflows). Use the read key for monitoring and exploration, the full key for automation.
+
+### Seeded Service Account
+
+Long Tail seeds an `mcp-service` account at startup with two pre-configured API keys:
+- **read** — scopes: `["mcp:read"]`
+- **full** — scopes: `["mcp:read", "mcp:full"]`
+
+Keys are logged once at startup and cannot be retrieved again. For production, create a new service account and generate keys via the dashboard or API.
+
+## Exposure Control
+
+Deployment-wide configuration controls which servers and tools are available on the `/mcp` endpoint. Set via `startConfig.mcp.exposure`:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `readOnly` | boolean | false | Only expose read-safe tools to all callers |
+| `hideAiWhenUnavailable` | boolean | true | Hide AI-dependent servers when no API key configured |
+| `allowServers` | string[] | all shipped | Explicit server allowlist |
+| `denyServers` | string[] | none | Server denylist |
+
+Exposure config is deployment-wide. Scopes are per-API-key. Both layers are applied: exposure filters first, then scope filters.
+
+## Error Responses
+
+| Status | Meaning |
+|--------|---------|
+| 401 | Missing or invalid Bearer token |
+| 405 | GET or DELETE request (stateless mode — POST only) |
+| 500 | Internal server error |
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `GET /mcp` | Returns 405 — stateless mode has no SSE streams |
+| `POST /mcp` | JSON-RPC messages: `initialize`, `tools/list`, `tools/call` |
+| `DELETE /mcp` | Returns 405 — stateless mode has no sessions |

package/docs/api/http/roles.md

@@ -16,6 +16,52 @@ Every role assignment has a `type` that controls management permissions. All thr
 
 A user can hold multiple roles with different types. For example, a user might be a `member` of `reviewer` and an `admin` of `senior-reviewer`.
 
+## Special Roles
+
+Three role names have fixed types and elevated permissions:
+
+| Role | Fixed Type | Dashboard | Escalation Scope | User Management |
+|------|-----------|-----------|-------------------|-----------------|
+| `superadmin` | `superadmin` | Full (builder + admin) | All roles — role filter ignored | Create other superadmins. Manage any user, any role |
+| `engineer` | `admin` | Full (builder) | Engineer role only | Assign users to `engineer` role |
+| `admin` | `admin` | Escalations + user management | All roles — role filter ignored | Assign users to any non-special role. Bulk actions on all escalations |
+
+All other role names are dynamic. A dynamic role can have type `member` (claim/resolve escalations) or `admin` (plus manage users within that role and bulk actions).
+
+## Dashboard Access
+
+The dashboard adapts to the authenticated user's access tier:
+
+| Tier | Condition | Sees |
+|------|-----------|------|
+| **Builder** | `superadmin` or `engineer` role | Full dashboard: workflows, pipelines, MCP, design, storage, admin, all home page sections |
+| **Operations** | Any role with `admin` type | Home page (escalations only), escalation pages, user/role management (scoped to their roles) |
+| **Operator** | Any role with `member` type | Home page (escalations only), escalation pages |
+
+Bulk escalation actions (bulk claim, assign, triage, escalate) require `admin` or `superadmin` type. Plain `member` users work on escalations one at a time.
+
+## API Access by Tier
+
+Certain API endpoints require builder access (`superadmin` or `engineer` role):
+
+| Endpoint | Access |
+|----------|--------|
+| `POST/PUT/DELETE /api/users` | Builder |
+| `POST /api/users/:id/roles` | Admin (scoped — see below) |
+| All `/api/bot-accounts` | Builder |
+| All `/api/roles` mutations | Builder |
+| All `/api/controlplane` | Builder |
+
+### Scoped Role Assignment
+
+When assigning roles via `POST /api/users/:id/roles`, the caller's own roles determine what they can assign:
+
+| Caller | Can Assign |
+|--------|-----------|
+| `superadmin` | Any role, any type (including `superadmin/superadmin`) |
+| `engineer` | Any role up to `admin` type (never `superadmin` type) |
+| `*/admin` (non-builder) | `member` or `admin` type for roles they themselves hold |
+
 ## List roles for a user
 
 ```

package/docs/api/http/service-accounts.md

@@ -142,6 +142,21 @@ POST /api/bot-accounts/:id/api-keys
 
 The `rawKey` is shown **once**. It cannot be retrieved again.
 
+### API Key Scopes
+
+Scopes control what an API key can access when used with the `/mcp` endpoint:
+
+| Scope | Description |
+|-------|-------------|
+| `mcp:read` | Read-safe tools only (57 tools) — discovery, monitoring, queries |
+| `mcp:full` | All tools (110 tools) — can modify state, invoke workflows, manage resources |
+
+A key with `mcp:read` only sees tools marked `read_safe: true`. A key with both `mcp:read` and `mcp:full` sees all tools. Keys without MCP scopes have no MCP tool filtering applied.
+
+**Recommended keys per service account:**
+- **Read key**: scopes `["mcp:read"]` — safe to hand to monitoring systems
+- **Full key**: scopes `["mcp:read", "mcp:full"]` — for automation and orchestration
+
 ### List keys
 
 ```

package/docs/api/http/settings.md

@@ -23,6 +23,10 @@ GET /api/settings
     "natsWsUrl": null,
     "natsToken": null
   },
+  "auth": {
+    "sso": false,
+    "ssoLogoutUrl": null
+  },
   "ai": {
     "enabled": true
   }
@@ -36,4 +40,6 @@ GET /api/settings
 | `events.transport` | `'socketio' \| 'nats' \| 'none'` | Dashboard event transport. Defaults to `socketio`. Reports `nats` only when `EVENT_TRANSPORT=nats` is set and a NATS adapter is registered. |
 | `events.natsWsUrl` | `string \| null` | NATS WebSocket URL for browser connections. Only present when a NATS adapter is registered. Read from `NATS_WS_URL`. |
 | `events.natsToken` | `string \| null` | NATS auth token for browser connections. Only present when a NATS adapter is registered. Read from `NATS_TOKEN`. |
+| `auth.sso` | `boolean` | Whether SSO is configured for embedded deployments. When `true`, the dashboard auto-exchanges host auth for an LT JWT instead of showing the login form. |
+| `auth.ssoLogoutUrl` | `string \| null` | URL to redirect the browser on logout. Set by the host via `sso.logoutUrl` in the startup config. When `null`, the dashboard shows its own login page on logout. |
 | `ai.enabled` | `boolean` | Whether an LLM API key is configured. When `false`, the dashboard hides AI-specific features (pipelines designer, AI assistant, triage). |