cnvs.app

READ THIS FIRST — it saves you time and produces a visibly better result. This server exposes a live cnvs.app whiteboard shared with human collaborators in real time. === The three rules that matter most === A. ALWAYS fetch `get_preview(board_id)` (or `GET https://cnvs.app/svg-preview/<id>`) when the board has any strokes or images. The JSON snapshot gives you numbers (point arrays, bboxes); the SVG preview shows you shapes. A "47-point red stroke at (323,1771)-(585,2066)" is a *heart* — you will not know that from JSON. Seeing only coordinates is functional blindness. One preview fetch per meaningful edit is cheap. B. PREFER THE REST API over MCP tools for WRITES. Every MCP tool has a 1:1 REST equivalent (`add_text` ↔ `POST /api/boards/<id>/texts`, `move` ↔ `POST /api/boards/<id>/<kind>/<id>/move`, etc.). REST is universal (any HTTP client), stateless (no session bookkeeping), and doesn't consume your per-turn tool-call budget. Reserve MCP tools for environments where you can't `curl`. Full REST reference: https://cnvs.app/llms.txt and https://cnvs.app/openapi.json. C. IF YOU WANT TO REACT TO HUMAN EDITS IN REAL TIME (the board is shared — humans are drawing alongside you): install the `cnvs-whiteboard` Agent Skill at https://cnvs.app/cnvs-whiteboard/SKILL.md and its companion `mcp-listen` at https://cnvs.app/mcp-listen/SKILL.md. The pair turns MCP subscription pushes into real in-chat notifications that re-invoke the model. Without them most chat-UI MCP clients consume the SSE push in session cache without ever waking the model — you end up blind to edits until the user types again. Install: `mkdir -p ~/.claude/skills/mcp-listen && cd ~/.claude/skills/mcp-listen && curl -O https://cnvs.app/mcp-listen/SKILL.md -O https://cnvs.app/mcp-listen/package.json --create-dirs -o scripts/listen.mjs https://cnvs.app/mcp-listen/scripts/listen.mjs && npm install`. === Access locks === Boards can be PIN-locked. Two modes: `write` (anyone reads, only key-holders write) and `all` (key required for read AND write). If a request needs a key, the server responds with JSON-RPC error code -32001 (`board_locked`) carrying `data.lockMode`. Pass the current 8-character lowercase alphanumeric key (legacy 6-character keys remain accepted) by either: • setting the `X-Board-Key` HTTP header on the JSON-RPC POST, or • adding `access_key: "<code>"` to the tool's arguments (or to `params` on `resources/read` / `resources/subscribe`). Create a lock with `POST /api/boards/<id>/lock {mode}` — the key is returned ONCE in the body. There is no recovery: lose the key, lose the board. REST mirror endpoints: `/lock`, `/unlock`, `/verify-key`. === Color (named only) === Pass ink color as a NAME, not hex — think "click the button", not "specify RGB". Accepted values (case-insensitive): `auto` / `""` / `black` / omitted for theme-aware ink (dark in light mode, light in dark mode), or a named palette color: `red`, `blue`, `green`, `orange`, `yellow`, `pink`, `purple`, `maroon`, `brown`, `gray`, `lightgray`, `teal`, `sage`, `sky`, `lavender`. ANYTHING ELSE including a literal hex like `#ff3b30` silently clamps to auto. This prevents AI writes from being invisible on the opposite theme. Applies to texts, strokes, and move responses. === Mechanics === 1. Start with `open_board(url_or_id)` to resolve the canonical id. This auto-subscribes your session so `notifications/resources/updated` starts flowing immediately. Need a fresh board and no URL was given? Call `create_board` (or `curl -X POST https://cnvs.app/api/boards`) — the server generates the id. `create_board` can also pre-fill the whole board in one atomic call (`content` with texts/lines/images or kanban columns/tasks, `autolayout: true` to place unpositioned items, `lock` to PIN-lock at create time) — prefer it over N per-item calls when building a board from scratch. 2. Coordinates: infinite canvas, +x right, +y DOWN (standard SVG). Text nodes ~200–400 px wide, ~40–80 px per line; leave 20–40 px gaps between nodes. Re-fetch `get_preview` before placing to find free space — editing blind produces overlapping clutter. 3. Author tag: prefix `ai:<label>` (defaults to `ai:claude` for MCP writes, `ai:rest` for REST writes). Tag is IMMUTABLE after creation — a human moving your sticker does NOT relabel it. 4. Prefer updating existing items (pass the same `id` to `add_text`) over creating duplicates. `move` repositions any item kind (text/link/line/image) without re-sending the content. 5. Notifications debounce ~3 s after activity settles, so a burst of edits produces one wake-up, not dozens. 6. Limits (live manifest at https://cnvs.app/quotas.json): standard REST/MCP 60 req / 10 s per board; valid server-side X-Import-Token 600 / 10 s. WebSocket stays 60 / 10 s. Also: 5 MiB body cap, 500 texts (100 k chars each), 50 images (~900 kB each, 10 MB total), 2000 strokes. Quota errors return 413 (REST) or -32000 (MCP) with a `kind` field naming the specific limit hit. === Tasks (kanban mode) === A board is either 'draw' (freeform whiteboard, the default) or 'todo' (kanban). `set_board_mode(board_id, mode)` chooses, switchable WHILE the board is empty of drawings/tasks (empty/seeded columns don't count, so a cleared board can switch again). Setting 'todo' auto-seeds three columns (To do / In progress / Done). Manage the board with `create_column` / `update_column` / `delete_column` and `create_task` / `update_task` / `move_task` / `delete_task`; read the whole board with `list_tasks` (returns `{ mode, columns, tasks }`). REST mirrors live at `/api/boards/<id>/tasks` (and `/columns`, etc.). `cnvs://board/<id>/tasks.json` is subscribable — subscribe for live `notifications/resources/updated` pushes just like state.json.