Tsumu MCP
by abshrimp
README.md
# Tsumu MCP
A standalone remote Model Context Protocol (MCP) server for [Tsumu](https://github.com/abshrimp/tsumu). The Tsumu editor remains independent: no account, local server, or MCP packages are required to edit browser-stored sites.
## Architecture
- **Public MCP URL:** https://mcp.tsumu.ebii.net/mcp (after deployment and custom-domain setup)
- **Runtime:** Cloudflare Workers, Durable Objects for browser sessions and one-time pairing, Workers KV for OAuth tokens and grants.
- **Transport:** Streamable HTTP with OAuth 2.1 authorization-code / PKCE.
- **Data:** The MCP server does **not** persist or mirror Tsumu site documents. It relays operations to the browser tab where the site is open. The browser's existing Tsumu editor applies and saves those edits.
- **Permission:** One active browser/site per pairing; read-only or read/edit, selected in Tsumu. No publishing or asset deletion.
## Connect
1. Open the desired site in https://tsumu.ebii.net.
2. Open **Settings → Connect an AI app**. Choose read-only or read/edit, then start the connection.
3. Add https://mcp.tsumu.ebii.net/mcp to your ChatGPT/Claude/Cursor MCP app, if that client supports remote OAuth MCP.
4. On the MCP OAuth authorization page, inspect the client identity and redirect host. Enter the **one-time pairing code** shown by Tsumu.
5. Keep the Tsumu editor tab open. The connection expires after one hour, and the pairing code after ten minutes.
6. Revoke immediately using **Disconnect and revoke** in Tsumu.
The pairing code is not a bearer token; it is a random, single-use authorization proof. Do not share it.
## Deploy
Requires Node.js 24+, a Cloudflare account, a KV namespace and permission to configure the subdomain.
~~~sh
npm install
npx wrangler kv namespace create OAUTH_KV
~~~
Replace the placeholder ID of all zeroes in wrangler.jsonc with the KV namespace ID from Cloudflare. Keep the durable-object migration configuration. The TSUMU_ORIGINS setting is a comma-separated exact origin allowlist. Default: https://tsumu.ebii.net. Never configure a wildcard for this setting.
~~~sh
npm run check
npm test
npm run build
npm run deploy
~~~
Configure the custom domain **mcp.tsumu.ebii.net** for this Worker in Cloudflare. The OAuth resource and issuer in src/index.js must match the deployed HTTPS origin. Do not advertise the workers.dev URL while they are configured for the custom domain.
To use this with a self-hosted Tsumu instance, compile that editor with NEXT_PUBLIC_TSUMU_MCP_URL pointing to the MCP Worker, and add the Tsumu instance's actual origin to TSUMU_ORIGINS on its dedicated MCP deployment.
## MCP tools
| Tool | Permission | Action |
| --- | --- | --- |
| list_sites | Read | Return the paired site |
| list_pages | Read | Return page IDs and slugs |
| get_page | Read | Return a page's edit context and SHA-256 revision |
| get_element | Read | Read a node's text, styles and children |
| apply_operations | Edit | Apply up to 100 Tsumu AI operations atomically |
Read the page with get_page before calling apply_operations. Pass the revision returned by get_page as expectedRevision. Every write must have a unique requestId (8–80 letters/numbers/underscore/hyphen) to prevent duplicate execution. Never blindly repeat a timed-out write; retrieve the page again to determine whether it applied.
## Security model and limitations
- A signed-in Tsumu account is not required: the **live browser** authorizes access to the particular site.
- The remote MCP OAuth server issues scoped access tokens using the official Cloudflare OAuth Provider. A separate random WebSocket token authenticates the browser; it is transmitted via the WebSocket subprotocol, not a URL parameter.
- Bridge HTTP requests and WebSockets require a matching browser Origin. The server checks site/session authorization for every operation, and denies edits on read-only sessions.
- One-time codes expire in ten minutes and are consumed atomically; failed pairing attempts are rate limited.
- When the browser is closed or disconnected, editing is unavailable. Revoked or expired sessions cannot be used even with a previously issued OAuth token.
- Browser saves are confirmed before an edit is reported as successful. If a site is also synced to Tsumu's server, that existing sync remains asynchronous; MCP does not claim that publication or cloud sync has completed.
- In production, configure Cloudflare WAF/rate limits for public pairing endpoints, monitor error rates, verify custom-domain OAuth redirects and exercise end-to-end tests with the targeted MCP clients.
This repository does not copy the Tsumu editor's AI-operation engine, document model, or persistence code. MIT licensed.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues