Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.
docs(mcp): document the MCP server, sign-in, tools and setup
spacesdrive06ebcfa339a7
diff --git a/docs/platform-v2/MCP_DOCUMENTATION.md b/docs/platform-v2/MCP_DOCUMENTATION.mdnew file mode 100644index 0000000..f2d15a4--- /dev/null+++ b/docs/platform-v2/MCP_DOCUMENTATION.md@@ -0,0 +1,226 @@+# MCP server++Twiligent's Model Context Protocol server lets a person connect Claude (Claude Code, Claude Desktop, claude.ai) to their own Twiligent account and work with their dashboard by asking: read analytics, see and schedule posts, change settings. It is part of the Worker, not a separate service, and every tool calls the same services the app uses, under the same per-user rules. Issue #146; design in `ARCHITECTURE.md` section 2; research in `research/mcp.md`.++---++## Architecture++```+Claude client+ | POST /mcp (JSON-RPC 2.0, one message per request)+ v+Worker pipeline: CORS -> request id and deadline -> security headers -> clients -> IP rate limit+ -> requireMcpAuth (access token, or OAuth token of an approved client) -> MCP rate limit (per user)+ -> handleMcpMessage (controllers/mcpController.ts)+ -> McpService (services/mcpService.ts): envelope checks, method dispatch, permission, confirmation, timeout+ -> tool (backend/mcp/tools/*.ts): validates input with backend/validators/, calls one service method+ -> services -> repositories -> Postgres, Redis, platforms+```++| Part | File | Job |+|---|---|---|+| Envelope | `backend/lib/mcp/protocol.ts` | Parse one JSON-RPC message, tell a legacy (handshake) client from a 2026-07-28 client, check headers against the body, build initialize, discover and error replies |+| Tokens | `backend/lib/mcp/accessToken.ts` | Generate `twl_` tokens and hash them (SHA-256) |+| Confirmations | `backend/lib/mcp/confirmation.ts` | Sign and verify the token that approves an irreversible action |+| Sign-in | `backend/middleware/mcpAuth.ts` | Origin check, credential check, sets `userId` and `mcpPrincipal` |+| Access | `backend/services/mcpAccessService.ts` | Create, list and revoke tokens; approve, list and revoke OAuth clients; sign a caller in |+| Dispatch | `backend/services/mcpService.ts` | initialize, ping, server/discover, tools/list, tools/call |+| Tools | `backend/mcp/registry.ts`, `backend/mcp/tools/` | The tool list and each tool's schema, permission and handler |+| Storage | `mcp_access_tokens`, `mcp_client_grants`, `audit_events` | Token hashes, approved clients, the record of every write |++### Protocol++- **Transport:** Streamable HTTP on one endpoint. `POST /mcp` takes one JSON-RPC request or notification and answers with JSON; a notification gets `202` with no body. `GET` and `DELETE /mcp` answer `405`: there is no server stream and no session.+- **Versions:** `2026-07-28` (stateless, version in `_meta` and the `MCP-Protocol-Version` header) and the handshake-based `2025-11-25`, `2025-06-18` and `2025-03-26`, which Claude's hosted apps speak today. `initialize` is answered with the client's version when supported, otherwise `2025-11-25`, and never creates a session id.+- **Modern requests** must send `MCP-Protocol-Version`, `Mcp-Method` and, for `tools/call`, `Mcp-Name` matching the body (base64 `=?base64?...?=` values are decoded first); a mismatch is `400` with code `-32020`, an unknown version `400` with `-32022` and the supported list, an unknown method `404` with `-32601`.+- **Methods:** `initialize`, `notifications/initialized`, `ping`, `server/discover`, `tools/list`, `tools/call`. Resources, prompts, sampling and elicitation are not offered.++---++## Signing in++Two kinds of credential reach `/mcp`. Both end in the same thing: the verified user id the rest of the Worker trusts, plus a permission, `read` or `write`.++### Personal access tokens (available now)++For Claude Code, Claude Desktop config files and scripts.++1. In Twiligent, Settings, Claude, create a token: a name, what it may do (read only, or read and make changes) and when it expires (or never).+2. Copy it. It is shown once; only its SHA-256 hash and last four characters are stored.+3. Send it as `Authorization: Bearer twl_...` on every request.++A token stops working when it is revoked or expires; the answer is the same `401` for an unknown, revoked or expired token. A person can hold 20 active tokens. Last used is recorded at most once an hour.++### OAuth through Supabase Auth (claude.ai, Desktop and mobile connectors)++Claude's apps only accept OAuth for remote servers. Twiligent stays a resource server: Supabase Auth's OAuth 2.1 server issues the tokens.++1. Claude calls `/mcp` without a token and gets `401` with `WWW-Authenticate: Bearer realm="twiligent", resource_metadata=".../.well-known/oauth-protected-resource/mcp"`.+2. The metadata names `https://<project>.supabase.co/auth/v1` as the authorization server. Claude registers itself and sends the person to Supabase, which sends them to Twiligent's consent page.+3. The consent page shows the client's name and asks what it may do. The choice is saved in `mcp_client_grants`, then the page approves the request with Supabase.+4. Claude receives an access token and calls `/mcp` with it. The Worker checks it with Supabase Auth, requires a `client_id` claim (so an app session token copied from a browser is refused) and requires a grant for that client.++Removing a client in Settings deletes its grant, which stops it at the next call even while its token is still valid. Steps 2 and 3 need the owner to turn on the OAuth server (see Deployment); until then the challenge omits `resource_metadata` and the metadata endpoint answers `404`.++---++## Connecting Claude++The server URL is `https://<your Worker host>/mcp`; Settings, Claude shows it with a copy button.++### Claude Code++```bash+claude mcp add --transport http twiligent https://api.example.com/mcp --header "Authorization: Bearer twl_your_token"+```++Or in a project's `.mcp.json`, keeping the token out of the file:++```json+{+ "mcpServers": {+ "twiligent": {+ "type": "http",+ "url": "https://api.example.com/mcp",+ "headers": { "Authorization": "Bearer ${TWILIGENT_TOKEN}" }+ }+ }+}+```++### Claude Desktop with a token++Claude Desktop's own config takes local servers; reach a remote server with a token through `mcp-remote`:++```json+{+ "mcpServers": {+ "twiligent": {+ "command": "npx",+ "args": ["mcp-remote", "https://api.example.com/mcp", "--header", "Authorization:${AUTH_HEADER}"],+ "env": { "AUTH_HEADER": "Bearer twl_your_token" }+ }+ }+}+```++### claude.ai, Desktop and mobile with OAuth++Settings, Connectors, Add custom connector, paste the server URL, then sign in and approve on Twiligent's consent page. Needs the OAuth server turned on.++---++## Tools++Every tool works only on the caller's own data. Read tools need no confirmation. Write tools need a `write` token or grant and are hidden from read-only callers (calling one anyway returns a tool error that explains how to allow changes). Tools marked "confirm" run only on a second call carrying a confirmation token.++| Tool | Kind | Input | Result |+|---|---|---|---|+| `get_settings` | read | none | Which server keys are set (never their values); the GitHub repository setting |+| `get_instagram_publishing_limit` | read | `accountId` | Posts published in the last 24 hours and the limit |+| `update_github_settings` | write | `repoOwner`, `repoName`, `branch` | The saved setting |+| `list_scheduled_posts` | read | `status`, `limit` (1 to 50, default 20), `cursor` | `posts`, `nextCursor`, `total` |+| `get_scheduled_post` | read | `postId` | `post` |+| `schedule_instagram_post` | write, confirm | `accountId`, `mediaUrl` (public https), `scheduledAt` (future ISO 8601), `mediaType` (IMAGE, VIDEO, REELS, STORIES), `caption`, `shareToFeed`, `collaborators`, `altText`, `locationId` | `post`, `alreadyScheduled` (true when the same media was already scheduled for that account and time) |+| `update_scheduled_post` | write | `postId` and the fields to change | `post` |+| `cancel_scheduled_post` | write, confirm | `postId` | `cancelled` |++Each tool publishes its full JSON Schema in `tools/list`, with annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`). The validators in `backend/validators/` enforce the same rules the REST API does. Analytics, accounts, tracked videos, media and YouTube tools follow in later phases (`IMPLEMENTATION_PLAN.md`).++### Confirmation++```json+// first call+{ "name": "cancel_scheduled_post", "arguments": { "postId": "p1" } }+// result+{ "status": "confirmation_required", "action": "Delete scheduled post p1 so it is never published.",+ "confirmationToken": "1762310000000.Xw3...", "expiresInSeconds": 300,+ "instructions": "Show the action to the person. Only if they agree, call this tool again with the same arguments plus confirmationToken." }+// second call, after the person agreed+{ "name": "cancel_scheduled_post", "arguments": { "postId": "p1", "confirmationToken": "1762310000000.Xw3..." } }+```++The token is an HMAC over the user id, the tool name, the arguments (in any key order) and an expiry five minutes ahead, with a key derived from `TOKEN_ENCRYPTION_KEY`. A token for other arguments, another tool or another person does not work. It does not rely on the client supporting elicitation, and text a model reads in a caption or comment cannot produce one.++---++## Errors++| Situation | Answer |+|---|---|+| No credential | HTTP `401`, `WWW-Authenticate` challenge, JSON-RPC error `-32001` |+| Unknown, revoked or expired token; expired OAuth sign-in; app session token | HTTP `401`, `-32001`, a message saying what to do |+| OAuth client not approved | HTTP `403` |+| `Origin` header from a site other than claude.ai, claude.com or the app | HTTP `403` |+| Too many requests | HTTP `429` with `Retry-After` (60 burst, then 1 a second per user, after the per-IP limit) |+| Body is not JSON | HTTP `400`, `-32700` |+| Not one JSON-RPC message (a batch, a response, no method) | HTTP `400`, `-32600` |+| Unknown tool or arguments that are not an object | `-32602` |+| Invalid tool input, not found, platform error | A tool result with `isError: true` and a message the model can act on |+| Tool took more than 25 seconds | Tool error that says to check whether the change happened before retrying |+| Result over about 10,000 tokens | Tool error asking for fewer items |+| Unexpected failure | Tool error with the request id; the details go only to the Worker log |++---++## Security++- **Identity comes only from the credential.** No tool takes a user id; every service call is scoped by the verified user id, so another person's ids answer "not found".+- **Least privilege.** `read` credentials never see write tools. Connecting or removing accounts, passwords and tokens are not available through MCP at all.+- **Irreversible and public actions need a confirmation** bound to the exact arguments.+- **No token passthrough.** The client's credential is never forwarded; platform calls use the stored per-user platform credentials, as the app does.+- **Untrusted content.** Captions, titles and comments are returned as data fields; the server instructions tell the model to treat them as data. Tools that return them set `openWorldHint`.+- **Secrets at rest.** Access tokens are stored as SHA-256 hashes; raw tokens are sent once with `Cache-Control: no-store`.+- **Abuse limits.** Per-IP and per-user rate limits, a 25 second tool timeout, a result size cap, 20 tokens a person.+- **Audit.** Token and client changes and every write tool call are recorded in `audit_events` (`mcp_access_token.called_tool` or `mcp_client.called_tool` with the tool and outcome, never the arguments).+- **Origin check.** A request with an `Origin` header from any site other than Claude's or the app's is refused, so a web page cannot use a person's browser to call the endpoint.++---++## Environment variables++| Variable | Required | Purpose |+|---|---|---|+| `BACKEND_URL` | yes (existing) | Builds the server URL (`<BACKEND_URL>/mcp`) and the metadata URL |+| `SUPABASE_URL` | yes (existing) | Names the authorization server (`<SUPABASE_URL>/auth/v1`) |+| `TOKEN_ENCRYPTION_KEY` | for write tools that confirm | At least 32 random characters; keys derived from it sign confirmations (and, with YouTube publishing, encrypt stored tokens). Generate with `openssl rand -base64 48` |+| `MCP_OAUTH_ENABLED` | for Claude's apps | `true` after the OAuth server is turned on in Supabase |++---++## Local development++1. `npm run dev` starts the Worker on `http://localhost:8787`; the endpoint is `http://localhost:8787/mcp`.+2. Sign in to the local app, create a token in Settings, Claude.+3. Try it with the MCP Inspector (`npx @modelcontextprotocol/inspector`, transport Streamable HTTP, header `Authorization: Bearer twl_...`) or with curl:++```bash+curl -s http://localhost:8787/mcp -H "Authorization: Bearer twl_your_token" -H "Content-Type: application/json" \+ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'+```++Tests: `backend/tests/lib/mcp/`, `backend/tests/services/mcpService.test.ts`, `mcpAccessService.test.ts`, `backend/tests/mcp/`, `backend/tests/routes/mcpRoutes.test.ts`.++---++## Deployment++1. Apply the migrations (`npm run db:push`, then `npm run db:schema`): `mcp_access_tokens`, `mcp_client_grants` and the wider `audit_events` subject check.+2. Set `TOKEN_ENCRYPTION_KEY` with `wrangler secret put TOKEN_ENCRYPTION_KEY`, then deploy the Worker.+3. For Claude's apps: in the Supabase dashboard, Authentication, OAuth Server, turn the server on, allow dynamic client registration, set the authorization path to `/oauth/consent`; then `wrangler secret put MCP_OAUTH_ENABLED` with `true` and deploy.++---++## Troubleshooting++| Symptom | Cause and fix |+|---|---|+| `401` "This access token is not valid" | Revoked, expired or mistyped. Create a new token in Settings, Claude |+| `401` "App session tokens are not accepted" | A browser session token was used. Use an access token or connect with OAuth |+| `403` "not approved for your account" | The OAuth client's grant was removed. Connect again and approve it |+| `403` "Requests from this web page are not allowed" | The request came from a web page on another site. Connect from a Claude client |+| A write tool says the connection may only read | The token or grant is read only. Create a token that may make changes, or approve the client again with changes allowed |+| "cannot sign until its owner sets the TOKEN_ENCRYPTION_KEY" | Set the Worker secret (at least 32 characters) and deploy |+| claude.ai says it cannot find an authorization server | OAuth is not turned on: `MCP_OAUTH_ENABLED` is not `true`, or the Supabase OAuth server is off |+| `429` | The per-user limit; wait the `Retry-After` seconds |