@ansuman-shukla/whiteboard-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ansuman Shukla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+<a href="#quick-start">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/media/readme/hero-dark.svg">
+    <img src="docs/media/readme/hero-light.svg" width="100%" alt="whiteboard-mcp: a live whiteboard your coding agent draws on. You draw back.">
+  </picture>
+</a>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<br>
+
+<img src="docs/media/dots-and-boxes.gif" width="100%" alt="Playing Dots and Boxes with a coding agent: the human draws a line on the board, the agent sees the move and plays back, until red wins 12 to 4">
+
+<p align="center"><sub>Playing Dots and Boxes with an agent: you draw a line, it sees your move and plays back.</sub></p>
+
+<br>
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/media/readme/features-dark.svg">
+  <img src="docs/media/readme/features-light.svg" width="100%" alt="Why whiteboard-mcp: draws step by step, sees what you draw, right beside the chat, remembers boards, local and private, tiny (one runtime dependency, about 7 KB of tool schema per turn).">
+</picture>
+
+<br><br>
+
+**Understand an architecture.** *"How does a typical checkout backend work? Draw it on the whiteboard."* The agent draws it piece by piece and highlights what it's explaining. You move a box, circle the part you're unsure about and leave a note. It reads exactly what you changed and answers on the board.
+
+<img src="docs/media/architecture.gif" width="100%" alt="An agent chat beside a live whiteboard: the agent draws a checkout architecture step by step, the human drags Postgres, circles the queue and sends a note asking what happens if the email worker is down, and the agent reads the changes and adds a dead-letter queue">
+
+**Explain a flow.** *"How does login work here?"* Arrows stay attached as things move, and the agent answers your notes on its next look.
+
+<img src="docs/media/demo.gif" width="100%" alt="The agent draws a login flow step by step, highlights the parts it explains, then answers a note left by the human">
+
+**Make something.** *"Paint the Mona Lisa, then refine it with the pencil."* Shapes, freehand strokes and frames, all editable.
+
+<img src="docs/media/mona-lisa.gif" width="100%" alt="An agent paints the Mona Lisa on the board, then refines the sky, hair and dress with pencil strokes">
+
+More to try:
+
+- *"Explain how a request flows through this repo, on the whiteboard."*
+- *"Teach me how a TCP handshake works, step by step."*
+- *"Draw our deploy pipeline and mark the single points of failure."*
+- *"Compare option A and option B side by side on the board."*
+- *"I circled something on the board, take a look."*
+
+<br>
+
+<a name="quick-start"></a>
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/media/readme/steps-dark.svg">
+  <img src="docs/media/readme/steps-light.svg" width="100%" alt="Get started in a minute: 1. Add it to your agent with one npx line. 2. Start a new chat. 3. Ask for a drawing.">
+</picture>
+
+Requires Node.js 20+.
+
+```sh
+claude mcp add whiteboard --scope user -- npx -y @ansuman-shukla/whiteboard-mcp
+```
+
+Codex, Cursor, Gemini CLI, OpenCode, Devin, VS Code, Claude Desktop and agents without MCP: see [client setup](docs/clients.md). For boards in a tab beside the chat, install the [IDE panel](docs/ide-panel.md). The bundled [skill](docs/clients.md#the-skill-recommended-for-every-agent) teaches the agent when a drawing helps.
+
+<br>
+
+<a href="docs/comparison.md">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/media/readme/compare-dark.svg">
+    <img src="docs/media/readme/compare-light.svg" width="100%" alt="whiteboard-mcp vs Excalidraw MCP: whiteboard-mcp sees what you draw back as a short list of changes, screenshots its own board, edits one shape in place, keeps boards beyond the chat, works in any MCP client plus a CLI, and converts Mermaid. Excalidraw MCP has animated camera moves and zero install.">
+  </picture>
+</a>
+
+<p align="center"><sub>Want a quick one-off diagram inside Claude or ChatGPT on the web? Excalidraw MCP is great for that. <a href="docs/comparison.md">Full comparison →</a></sub></p>
+
+<br>
+
+<p align="center">
+  <a href="docs/clients.md">Client setup</a> · <a href="docs/boards.md">Boards</a> · <a href="docs/ide-panel.md">IDE panel</a> · <a href="docs/tools.md">Tools &amp; how it works</a> · <a href="docs/configuration.md">Configuration</a> · <a href="docs/security.md">Security</a> · <a href="CONTRIBUTING.md">Contributing</a>
+  <br>
+  MIT License · built on <a href="https://github.com/excalidraw/excalidraw">Excalidraw</a>
+</p>

package/dist/canvas/client.js

@@ -0,0 +1,244 @@
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { APP_NAME, stateDir, statePath } from '../shared/config.js';
+import { API, } from '../shared/protocol.js';
+export class CanvasError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'CanvasError';
+    }
+}
+const HTTP_TIMEOUT_MS = 10_000;
+const HEALTH_TIMEOUT_MS = 1000;
+const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
+const POLL_MS = 50;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** fetch() rejects with a TypeError ("fetch failed") when the daemon is gone; timeouts are DOMExceptions. */
+const isConnectionError = (err) => err instanceof TypeError;
+function readJsonFile(file) {
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function fetchHealth(baseUrl) {
+    try {
+        const res = await fetch(`${baseUrl}${API.health}`, { signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS) });
+        const body = await res.json();
+        return res.ok && isObject(body) && typeof body.pid === 'number' ? body : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The daemon advertised in daemon.json, if it answers /health as whiteboard-mcp with the same pid. */
+async function probe() {
+    const info = readJsonFile(statePath('daemon.json'));
+    if (!isObject(info) || typeof info.port !== 'number' || typeof info.pid !== 'number')
+        return undefined;
+    let token;
+    try {
+        token = readFileSync(statePath('token'), 'utf8').trim();
+    }
+    catch {
+        return undefined;
+    }
+    const baseUrl = `http://127.0.0.1:${info.port}`;
+    const health = await fetchHealth(baseUrl);
+    return token && health?.app === APP_NAME && health.pid === info.pid ? { baseUrl, token } : undefined;
+}
+/** Why a daemon we started gave up, from its own last line in daemon.log (it logs e.g. `listen failed: ...` before exiting). */
+function startFailure(pid, code, signal) {
+    const logFile = statePath('daemon.log');
+    let log = '';
+    try {
+        log = readFileSync(logFile, 'utf8');
+    }
+    catch {
+        // the daemon could not write its log either
+    }
+    const reason = pid === undefined ? undefined : log.split('\n').filter((line) => line.includes(` [${pid}] `)).pop()?.replace(/^\S+ \[\d+\] /, '');
+    const how = code === null ? `was stopped (${signal})` : `exited with code ${code}`;
+    const sandboxed = /\b(EPERM|EACCES)\b/.test(reason ?? '')
+        ? ' Listening on 127.0.0.1 is not permitted here, probably a sandbox: run whiteboard-mcp outside it (e.g. as an MCP server rather than from a sandboxed shell) or allow local network access.'
+        : '';
+    return new CanvasError(`canvas daemon ${how} before it was ready${reason ? `: ${reason}` : ''} (see ${logFile}).${sandboxed}`, 503, 'daemon_start_failed');
+}
+async function discover(opts) {
+    const found = await probe();
+    if (found)
+        return found;
+    if (opts.autoStart === false)
+        throw new CanvasError('canvas daemon is not running', 503, 'daemon_not_running');
+    const entry = opts.entry ?? (process.env.WHITEBOARD_ENTRY || fileURLToPath(new URL('../cli.js', import.meta.url)));
+    let spawnError;
+    // cwd = state dir so the daemon never pins the caller's project directory. Concurrent spawns are
+    // safe: the daemon's lock lets exactly one of them run.
+    const child = spawn(process.execPath, [entry, 'serve'], { detached: true, stdio: 'ignore', env: process.env, cwd: stateDir() });
+    let exit;
+    child.once('error', (err) => (spawnError = err));
+    child.once('exit', (code, signal) => (exit = { code, signal }));
+    child.unref();
+    const timeoutMs = opts.startTimeoutMs ?? 8000;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (spawnError)
+            throw new CanvasError(`could not start the canvas daemon: ${spawnError.message}`, 503, 'daemon_start_failed');
+        await sleep(POLL_MS);
+        const endpoint = await probe();
+        if (endpoint)
+            return endpoint;
+        // Exit code 0 means another daemon holds the lock; keep probing for that one.
+        if (exit && exit.code !== 0)
+            throw startFailure(child.pid, exit.code, exit.signal);
+    }
+    throw new CanvasError(`canvas daemon did not start within ${timeoutMs}ms (see ${statePath('daemon.log')})`, 503, 'daemon_start_timeout');
+}
+export class CanvasClient {
+    opts;
+    endpoint;
+    rediscovering;
+    constructor(endpoint, opts) {
+        this.opts = opts;
+        this.endpoint = endpoint;
+    }
+    static async connect(opts = {}) {
+        return new CanvasClient(await discover(opts), opts);
+    }
+    get baseUrl() {
+        return this.endpoint.baseUrl;
+    }
+    get token() {
+        return this.endpoint.token;
+    }
+    async health() {
+        const { ok, version, pid } = await this.call('GET', API.health);
+        return { ok, version, pid };
+    }
+    list() {
+        return this.call('GET', API.canvases);
+    }
+    ensureCanvas(id, meta = {}) {
+        return this.call('PUT', API.canvas(id), meta);
+    }
+    /** Asks the IDE panel host of the chat's window (`host`) or workspace to show the board. False when none qualifies. */
+    async show(id, workspace, host) {
+        const request = { workspace, ...(host ? { host } : {}) };
+        try {
+            await this.call('POST', API.show(id), request, 8000);
+            return true;
+        }
+        catch (err) {
+            if (err instanceof CanvasError && err.status === 409)
+                return false;
+            throw err;
+        }
+    }
+    snapshot(id) {
+        return this.call('GET', API.canvas(id));
+    }
+    apply(id, elements, opts = {}) {
+        return this.call('POST', API.elements(id), { elements, ...opts });
+    }
+    clear(id) {
+        return this.call('POST', API.clear(id), {});
+    }
+    changes(id, since) {
+        return this.call('GET', API.changes(id, since));
+    }
+    addNote(id, text) {
+        return this.call('POST', API.notes(id), { text });
+    }
+    /** Relays a request to the canvas's browser viewer. Fails with code no_viewer, timeout or viewer_error. */
+    async request(id, type, payload, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
+        try {
+            const body = await this.call('POST', API.request(id), { type, payload, timeoutMs }, timeoutMs + 2000);
+            return body.result;
+        }
+        catch (err) {
+            if (!(err instanceof CanvasError))
+                throw err;
+            if (err.status === 409)
+                throw new CanvasError(`no browser viewer has canvas "${id}" open`, 409, 'no_viewer');
+            if (err.status === 504)
+                throw new CanvasError(`the viewer did not answer the ${type} request in time`, 504, 'timeout');
+            if (err.status === 502)
+                throw new CanvasError(`the viewer failed the ${type} request: ${err.code}`, 502, 'viewer_error');
+            throw err;
+        }
+    }
+    /** Saves a frozen copy of the canvas to the library, named after the board unless `name` is given. */
+    save(id, name) {
+        return this.call('POST', API.save(id), name === undefined ? {} : { name });
+    }
+    searchSaved(query = '', workspace = '', limit) {
+        return this.call('GET', API.saved(query, workspace, limit));
+    }
+    /** Live boards of every folder matching the query, this workspace's first. */
+    searchBoards(query = '', workspace = '', limit) {
+        return this.call('GET', API.search(query, workspace, limit));
+    }
+    /** Replaces the canvas's scene with a copy of a saved board. */
+    loadSaved(id, savedId) {
+        return this.call('POST', API.load(id), { saved: savedId });
+    }
+    async deleteSaved(savedId) {
+        await this.call('DELETE', API.savedBoard(savedId));
+    }
+    async deleteCanvas(id) {
+        await this.call('DELETE', API.canvas(id));
+    }
+    viewerUrl(id) {
+        return `${this.baseUrl}${API.viewer(id)}?token=${this.token}`;
+    }
+    async call(method, path, body, timeoutMs = HTTP_TIMEOUT_MS, retry = true) {
+        let res;
+        try {
+            res = await fetch(`${this.baseUrl}${path}`, {
+                method,
+                headers: { Authorization: `Bearer ${this.token}`, ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (err) {
+            if (err instanceof DOMException && err.name === 'TimeoutError')
+                throw new CanvasError(`${method} ${path.split('?')[0]} timed out after ${timeoutMs}ms`, 504, 'timeout');
+            // The daemon idled out or restarted (maybe on another port): find or start it once, then retry once.
+            if (!retry || !isConnectionError(err))
+                throw err;
+            await this.rediscover();
+            return this.call(method, path, body, timeoutMs, false);
+        }
+        const text = await res.text();
+        let data;
+        try {
+            data = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            data = undefined;
+        }
+        if (res.ok)
+            return data;
+        const code = isObject(data) && typeof data.error === 'string' ? data.error : `http_${res.status}`;
+        throw new CanvasError(`${method} ${path.split('?')[0]} failed (${res.status}): ${code}`, res.status, code);
+    }
+    rediscover() {
+        this.rediscovering ??= discover(this.opts)
+            .then((endpoint) => {
+            this.endpoint = endpoint;
+        })
+            .finally(() => {
+            this.rediscovering = undefined;
+        });
+        return this.rediscovering;
+    }
+}