@ansuman-shukla/whiteboard-mcp 0.1.0 → 0.2.0

package/README.md

@@ -1,38 +1,52 @@
 <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.">
+    <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>
 
+<p align="center"><b>Whiteboard MCP</b> is a free, open-source <b>Excalidraw whiteboard MCP server</b> that runs locally, even offline. Your coding agent draws diagrams on a live board beside the chat, and sees what you draw back. Works with Claude Code, Codex, Cursor, Gemini CLI, VS Code, Windsurf, Devin and any other MCP client.</p>
+
+```sh
+claude mcp add whiteboard --scope user -- npx -y @ansuman-shukla/whiteboard-mcp
+```
+
+<p align="center"><sub>Needs Node.js 20+. Using Codex, Cursor, Gemini CLI, VS Code or another agent? <a href="#add-it-to-your-agent">Commands for every agent ↓</a></sub></p>
+
 <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>
+## Features
 
 <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).">
+  <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>
+## What you can do with it
+
+### Understand an architecture
 
-**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.
+*"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.
+### 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.
+### 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:
+### More to try
 
 - *"Explain how a request flows through this repo, on the whiteboard."*
 - *"Teach me how a TCP handshake works, step by step."*
@@ -40,34 +54,89 @@ More to try:
 - *"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>
+## Quick start
 
 <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+.
+### Add it to your agent
+
+Needs Node.js 20+. Add it, then start a new chat:
 
 ```sh
+# Claude Code
 claude mcp add whiteboard --scope user -- npx -y @ansuman-shukla/whiteboard-mcp
+
+# Codex CLI
+codex mcp add whiteboard -- npx -y @ansuman-shukla/whiteboard-mcp
+
+# Gemini CLI
+gemini mcp add --scope user whiteboard npx -y @ansuman-shukla/whiteboard-mcp
+
+# Devin CLI
+devin mcp add whiteboard --scope user -- npx -y @ansuman-shukla/whiteboard-mcp
+
+# VS Code
+code --add-mcp '{"name":"whiteboard","command":"npx","args":["-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.
+**Cursor, Claude Desktop, Windsurf and other JSON configs** (`~/.cursor/mcp.json`, Claude Desktop's config, …):
 
-<br>
+```json
+{ "mcpServers": { "whiteboard": { "command": "npx", "args": ["-y", "@ansuman-shukla/whiteboard-mcp"] } } }
+```
+
+**OpenCode** (`opencode.json`):
+
+```json
+{ "mcp": { "whiteboard": { "type": "local", "command": ["npx", "-y", "@ansuman-shukla/whiteboard-mcp"] } } }
+```
+
+Agents without MCP, project-level configs and more: [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.
+
+## Whiteboard MCP vs Excalidraw MCP
 
 <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.">
+    <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>
 
+## FAQ
+
+### Is there an Excalidraw MCP server that runs locally and works offline?
+
+Yes, that's Whiteboard MCP. It runs a small daemon on `127.0.0.1` and serves the Excalidraw viewer with its fonts bundled. After the first `npx` download it needs no internet, no account and no API key. Boards are plain JSON files in `~/.whiteboard-mcp`.
+
+### How do I let Claude Code, Codex or Cursor draw diagrams?
+
+Add the MCP server with the one-line command for your agent [above](#add-it-to-your-agent), start a new chat and ask: *"Draw how this repo handles a request on the whiteboard."* The agent draws step by step on a live Excalidraw board beside the chat.
+
+### Can the agent see what I draw on the whiteboard?
+
+Yes. Every time it looks, it gets a short list of what you added, moved or deleted, plus any notes you left. It can also take a PNG screenshot of the board to check its own layout.
+
+### Which agents and editors does it work with?
+
+Any MCP client: Claude Code, Claude Desktop, OpenAI Codex, Cursor, Gemini CLI, VS Code (Copilot agent mode), Windsurf, Devin, OpenCode and more. Agents without MCP can use the plain `whiteboard-mcp call` CLI. The [IDE panel](docs/ide-panel.md) shows boards in a tab beside the chat in VS Code, Cursor, Windsurf and Devin Desktop; elsewhere in an editor or desktop app, the agent opens them in the app's in-app browser, and in a plain terminal they open in your browser.
+
+### Can it turn Mermaid into an Excalidraw diagram, or export it?
+
+Yes. `canvas_mermaid` converts Mermaid (flowcharts, sequence diagrams, …) into editable hand-drawn elements, and `canvas_export` saves the board as `.excalidraw` or `.png` in your project.
+
+### Are boards saved? Can I reopen one later?
+
+Each chat gets its own board, saved on disk. Any later chat, even in another folder, can reopen it by name or find it by the text on it, and you can keep frozen copies in a saved library. See [boards](docs/boards.md).
+
+### Is it free and private?
+
+Yes. It's MIT licensed with no license key or paid tier. Everything stays on your machine: the daemon only listens on `127.0.0.1` and every API call needs a per-user token. See [security](docs/security.md).
+
 <br>
 
 <p align="center">

package/dist/canvas/client.js

@@ -130,8 +130,8 @@ export class CanvasClient {
         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 } : {}) };
+    async show(id, workspace, host, wait = false) {
+        const request = { workspace, ...(host ? { host } : {}), ...(wait ? { wait } : {}) };
         try {
             await this.call('POST', API.show(id), request, 8000);
             return true;

package/dist/canvas/daemon.js

@@ -262,14 +262,16 @@ export async function startDaemon(opts = {}) {
     }
     /**
      * The chat's own window (hostId equals the hint) wins. Otherwise a window whose folders contain the
-     * board's workspace, focused first, then the most recent; a window known to be another one than the
-     * hinted one is never used. No match means no host: showing a chat's board in an unrelated window
-     * would hide that window's own board.
+     * board's workspace, focused first, then the most recent. While the hinted window may still connect
+     * (`strict`), other identified windows are skipped; once it can't (a stale id after Reload Window),
+     * the folder decides. No match means no host: a board never opens in a window of another folder.
      */
-    function pickHost(workspace, hint) {
+    function pickHost(workspace, hint, strict) {
         const rank = (h) => {
-            if (hint !== undefined && h.hostId !== undefined)
-                return h.hostId === hint ? 3 : 0;
+            if (hint !== undefined && h.hostId === hint)
+                return 3;
+            if (strict && hint !== undefined && h.hostId !== undefined)
+                return 0;
             if (!workspace || !h.folders.some((f) => contains(f, workspace)))
                 return 0;
             return h.focused ? 2 : 1;
@@ -285,24 +287,26 @@ export async function startDaemon(opts = {}) {
     }
     /**
      * Right after the daemon starts (the agent's first call started it), the chat's window hasn't found it
-     * yet; a show that names its window waits briefly for that window's host instead of answering no_host.
+     * yet: a show that names its window, or comes from an agent inside an editor (`wait`), waits briefly
+     * for a host instead of answering no_host. A hinted show waits for its own window first.
      */
-    function show(canvasId, workspace, hint, res) {
-        const host = pickHost(workspace, hint);
+    function show(canvasId, workspace, hint, wait, res) {
+        const graceLeft = startedAt + hostGraceMs - Date.now();
+        const waiting = graceLeft > 0 && (hint !== undefined || wait);
+        const host = pickHost(workspace, hint, waiting);
         if (host)
             return showOn(host, canvasId, res);
-        const graceLeft = startedAt + hostGraceMs - Date.now();
-        if (hint === undefined || graceLeft <= 0)
+        if (!waiting)
             return Promise.resolve(sendJson(res, 409, { error: 'no_host' }));
         return new Promise((done) => {
             const end = () => {
-                hostWaits.delete(wait);
+                hostWaits.delete(waiter);
                 clearTimeout(timer);
                 res.off('close', onClientGone);
             };
-            const wait = {
+            const waiter = {
                 retry: () => {
-                    const found = pickHost(workspace, hint);
+                    const found = pickHost(workspace, hint, true);
                     if (!found)
                         return;
                     end();
@@ -318,9 +322,15 @@ export async function startDaemon(opts = {}) {
                 end();
                 done();
             };
-            const timer = setTimeout(() => wait.finish(409, { error: 'no_host' }), graceLeft);
+            const timer = setTimeout(() => {
+                const fallback = pickHost(workspace, hint, false);
+                if (!fallback)
+                    return waiter.finish(409, { error: 'no_host' });
+                end();
+                void showOn(fallback, canvasId, res).then(done);
+            }, graceLeft);
             res.once('close', onClientGone);
-            hostWaits.add(wait);
+            hostWaits.add(waiter);
         });
     }
     function showOn(host, canvasId, res) {
@@ -369,13 +379,15 @@ export async function startDaemon(opts = {}) {
                 return sendJson(res, 200, { ...store.ensure(id, { title, workspace, chat }), viewers: viewerCount(id) });
             }
             case 'POST show': {
-                const { workspace, host: hint } = await readJson(req);
+                const { workspace, host: hint, wait } = await readJson(req);
                 if (workspace !== undefined && typeof workspace !== 'string')
                     throw new HttpError(400, 'workspace must be a string');
+                if (wait !== undefined && typeof wait !== 'boolean')
+                    throw new HttpError(400, 'wait must be a boolean');
                 if (hint !== undefined && (typeof hint !== 'string' || !hint || hint.length > MAX_HOST_ID))
                     throw new HttpError(400, 'host must be a non-empty string');
                 requireCanvas();
-                return show(id, workspace, hint, res);
+                return show(id, workspace, hint, wait === true, res);
             }
             case 'DELETE ':
                 if (!store.remove(id))

package/dist/mcp/editor.js

@@ -0,0 +1,81 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+const IDE_ENV = ['WINDSURF_EXT_HOST_PID', 'VSCODE_PID', 'VSCODE_IPC_HOOK_CLI', 'CURSOR_TRACE_ID'];
+const HOST_ENV = ['WHITEBOARD_HOST_ID', 'WINDSURF_EXT_HOST_PID'];
+const WANTED = new Set([...IDE_ENV, ...HOST_ENV, 'TERM_PROGRAM']);
+const MAX_DEPTH = 12;
+const PS_TIMEOUT_MS = 2000;
+/**
+ * The editor window this agent runs in, as the `hostId` its panel host announces, so the board opens
+ * beside this chat and not in another window: `WHITEBOARD_HOST_ID` when a host sets it explicitly, else
+ * Windsurf/Devin Desktop's `WINDSURF_EXT_HOST_PID` (the extension host that started the chat, which is
+ * the process a panel extension runs in).
+ */
+export function hostHint(env = process.env) {
+    return env.WHITEBOARD_HOST_ID?.trim() || env.WINDSURF_EXT_HOST_PID?.trim() || undefined;
+}
+/** Agents running inside an editor should get the board in a panel, never a separate browser window. */
+export function insideIde(env = process.env) {
+    return IDE_ENV.some((k) => env[k]) || env.TERM_PROGRAM === 'vscode';
+}
+/** `ps -E` output: the parent pid, the command line, then the environment as KEY=value words. */
+export function parsePs(output) {
+    const words = output.trim().split(/\s+/);
+    if (!/^\d+$/.test(words[0] ?? ''))
+        return undefined;
+    const ppid = Number(words[0]);
+    const env = {};
+    for (const word of words.slice(1)) {
+        const eq = word.indexOf('=');
+        const key = word.slice(0, eq);
+        if (eq > 0 && WANTED.has(key))
+            env[key] = word.slice(eq + 1);
+    }
+    return { ppid, env };
+}
+/** A process's parent and the environment it started with; undefined where that can't be read (Windows, other users). */
+export async function readProc(pid, platform = process.platform) {
+    try {
+        if (platform === 'linux') {
+            const ppid = Number(/^PPid:\s*(\d+)/m.exec(await readFile(`/proc/${pid}/status`, 'utf8'))?.[1]);
+            const env = {};
+            for (const entry of (await readFile(`/proc/${pid}/environ`, 'utf8')).split('\0')) {
+                const eq = entry.indexOf('=');
+                if (eq > 0 && WANTED.has(entry.slice(0, eq)))
+                    env[entry.slice(0, eq)] = entry.slice(eq + 1);
+            }
+            return Number.isInteger(ppid) ? { ppid, env } : undefined;
+        }
+        if (platform !== 'darwin')
+            return undefined;
+        const output = await new Promise((done, fail) => execFile('ps', ['-E', '-ww', '-o', 'ppid=,command=', '-p', String(pid)], { timeout: PS_TIMEOUT_MS }, (err, stdout) => (err ? fail(err) : done(stdout))));
+        return parsePs(output);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The agent's own environment, else its ancestors': some agents (Codex) start MCP servers with only a few
+ * variables, so the window id their editor gave them, or the terminal they run in, is found up the
+ * process tree. `WHITEBOARD_HOST_ID` set but empty means "no window": nothing is looked up.
+ */
+export async function editorWindow(env = process.env, start = process.ppid, read = readProc) {
+    const host = hostHint(env);
+    let ide = insideIde(env);
+    if (host || env.WHITEBOARD_HOST_ID !== undefined)
+        return { ...(host ? { host } : {}), ide: ide || !!host };
+    const seen = new Set();
+    for (let pid = start; pid > 1 && !seen.has(pid) && seen.size < MAX_DEPTH;) {
+        seen.add(pid);
+        const proc = await read(pid);
+        if (!proc)
+            break;
+        const found = hostHint(proc.env);
+        if (found)
+            return { host: found, ide: true };
+        ide ||= insideIde(proc.env);
+        pid = proc.ppid;
+    }
+    return { ide };
+}

package/dist/mcp/guide.js

@@ -1,8 +1,8 @@
-export const INSTRUCTIONS = `Live whiteboard shown to the human beside the chat: you draw, they watch and can draw back or leave notes. Use it whenever a picture explains better than text (architecture, flows, sequences, state machines, data structures, comparisons). Each chat has its own board; call canvas_guide once, then canvas_open with a topic title, and draw step by step while narrating briefly. The tools show the board to the human themselves: never open board links in a browser or preview tool. To build on another chat's drawing (any folder), canvas_open {board}; canvas_search finds boards and saved copies (canvas_save). When the human mentions the board, call canvas_read.`;
+export const INSTRUCTIONS = `Live whiteboard shown to the human beside the chat: you draw, they watch and can draw back or leave notes. Use it whenever a picture explains better than text (architecture, flows, sequences, state machines, data structures, comparisons). Each chat has its own board; call canvas_guide once, then canvas_open with a topic title, and draw step by step while narrating briefly. The tools show the board themselves; open board links they give you in your in-app browser or preview tool, never an external browser. To build on another chat's drawing (any folder), canvas_open {board}; canvas_search finds boards and saved copies (canvas_save). When the human mentions the board, call canvas_read.`;
 export const GUIDE = `# Explaining on the live canvas
 
 ## Loop
-1. canvas_open {title:"<topic>"} once: it shows this chat's board beside the chat. Never open board links in a browser or preview tool. Plan: 3-8 boxes beat 30.
+1. canvas_open {title:"<topic>"} once: it shows this chat's board beside the chat. Board links go in your in-app browser or preview tool. Plan: 3-8 boxes beat 30.
 2. Draw in steps: one canvas_draw per idea (components, then flow, then notes), each followed by a sentence or two in chat that points at the canvas ("the blue boxes are services"). Keep chat short; the canvas carries the detail.
 3. canvas_focus {ids, highlight:true} to point at what you are talking about.
 4. canvas_screenshot once after the main layout to check overlaps and cut-off text.

package/dist/mcp/server.js

@@ -6,6 +6,17 @@ import { ToolContext, callTool, getTool, toolList } from './tools.js';
 export const SUPPORTED_PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
 const ROOTS_TIMEOUT_MS = 3000;
 const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const debug = (msg) => {
+    if (process.env.WHITEBOARD_DEBUG === '1')
+        process.stderr.write(`[whiteboard-mcp] ${msg}\n`);
+};
+/**
+ * A client that renders UI (it announces the `io.modelcontextprotocol/ui` extension) is a chat app with
+ * its own window, not a terminal: its agent opens boards in the app's in-app browser, never the system browser.
+ */
+export function clientIsApp(capabilities) {
+    return isObject(capabilities) && isObject(capabilities.extensions) && isObject(capabilities.extensions['io.modelcontextprotocol/ui']);
+}
 /** MCP over stdio. Never writes anything but JSON-RPC frames to `output`. */
 export function startMcpServer(opts = {}) {
     const session = opts.session ?? new Session();
@@ -29,6 +40,8 @@ export function startMcpServer(opts = {}) {
                 case 'initialize': {
                     const p = isObject(params) ? params : {};
                     clientWantsRoots = isObject(p.capabilities) && isObject(p.capabilities.roots);
+                    ctx.app = clientIsApp(p.capabilities);
+                    debug(`initialize: ${isObject(p.clientInfo) ? String(p.clientInfo.name) : 'unknown client'}${ctx.app ? ', chat app' : ''}`);
                     const requested = typeof p.protocolVersion === 'string' ? p.protocolVersion : '';
                     return {
                         protocolVersion: SUPPORTED_PROTOCOL_VERSIONS.includes(requested) ? requested : SUPPORTED_PROTOCOL_VERSIONS[0],

package/dist/mcp/tools.js

@@ -4,6 +4,7 @@ import { dirname, extname, isAbsolute, relative, resolve, sep } from 'node:path'
 import { CanvasClient, CanvasError } from '../canvas/client.js';
 import { describeChanges, describeScene } from '../shared/describe.js';
 import { ELEMENT_SPEC_FIELDS, buildElements, deleteElements } from '../shared/elements.js';
+import { editorWindow } from './editor.js';
 import { closestBoards, findBoard, whereFrom } from './find.js';
 import { GUIDE } from './guide.js';
 import { openViewer } from './open.js';
@@ -21,10 +22,17 @@ export class ToolContext {
     client;
     /** Boards already created this process, with their current titles. */
     titles = new Map();
+    /** The client is a chat app with its own window (not a terminal): boards go in its in-app browser. */
+    app = false;
+    window;
     constructor(session, connectOpts = {}) {
         this.session = session;
         this.connectOpts = connectOpts;
     }
+    /** The editor window the agent runs in, looked up once (it may take a walk up the process tree). */
+    editor() {
+        return (this.window ??= editorWindow());
+    }
     connect() {
         this.client ??= CanvasClient.connect({ autoStart: true, ...this.connectOpts }).catch((err) => {
             this.client = undefined;
@@ -41,18 +49,9 @@ export class ToolContext {
         return new ChatContext(this, await this.session.resolveChat(meta));
     }
 }
-const IDE_ENV = ['WINDSURF_EXT_HOST_PID', 'VSCODE_PID', 'VSCODE_IPC_HOOK_CLI', 'CURSOR_TRACE_ID'];
-/** Agents running inside an editor should get the board in a panel, never a separate browser window. */
-const insideIde = () => IDE_ENV.some((k) => process.env[k]) || process.env.TERM_PROGRAM === 'vscode';
-/**
- * The editor window this agent runs in, as the `hostId` its panel host announces, so the board opens
- * beside this chat and not in another window: `WHITEBOARD_HOST_ID` when a host sets it explicitly, else
- * Windsurf/Devin Desktop's `WINDSURF_EXT_HOST_PID` (the extension host that started the chat, which is
- * the process a panel extension runs in).
- */
-export function hostHint(env = process.env) {
-    return env.WHITEBOARD_HOST_ID?.trim() || env.WINDSURF_EXT_HOST_PID?.trim() || undefined;
-}
+/** Opening the board in the app's own browser keeps it beside the chat; an external browser takes the human away. */
+const IN_APP_BROWSER = 'your in-app browser or preview tool (not an external browser)';
+const SHOWN_BESIDE = 'Shown to the human beside the chat.';
 const SHOW_WAIT_MS = 8000;
 export class ChatContext {
     base;
@@ -81,24 +80,32 @@ export class ChatContext {
         return { client, ref: { id: ref.id, title: this.base.titles.get(ref.id) ?? '' } };
     }
     /**
-     * Puts the board in front of the human when nobody is watching it: an IDE panel host first;
-     * otherwise a browser, except inside an IDE where a stray browser window is never wanted.
+     * Puts the board in front of the human when nobody is watching it: an IDE panel host first; in an
+     * editor without one, or a chat app, the agent opens it in the app's in-app browser; else a browser.
      */
     async reveal(client, ref, viewers) {
         return viewers > 0 ? '' : (await this.show(client, ref)).note;
     }
+    /** The IDE panel host of this chat's window, else of its folder, shows the board. */
+    async panel(client, ref) {
+        const { host, ide } = await this.base.editor();
+        return client.show(ref.id, this.session.workspace, host, ide).catch(() => false);
+    }
     async show(client, ref) {
-        if (await client.show(ref.id, this.session.workspace, hostHint()).catch(() => false))
-            return { launched: true, note: 'Shown to the human beside the chat.' };
+        if (await this.panel(client, ref))
+            return { launched: true, note: SHOWN_BESIDE };
         const url = client.viewerUrl(ref.id);
         const mode = process.env.WHITEBOARD_OPEN?.trim();
         if (mode === 'none')
             return { launched: false, note: `Nobody is watching the board; the human can open ${url}.` };
-        if ((mode && mode !== 'auto') || !insideIde()) {
-            const { opened, note } = await openViewer(url);
-            return opened ? { launched: true, note: `${note}.` } : { launched: false, note: `${note}, so the human can't see the board yet; ask them to open ${url}.` };
+        const explicit = !!mode && mode !== 'auto';
+        // In an editor without a panel, or a chat app, the agent shows it in the app's own browser.
+        if (!explicit && (this.base.app || (await this.base.editor()).ide)) {
+            const where = this.base.app ? '' : 'No whiteboard panel is connected in this editor. ';
+            return { launched: false, note: `${where}Open the board in ${IN_APP_BROWSER}: ${url}` };
         }
-        return { launched: false, note: `No whiteboard panel is connected in the editor, so the human can't see the board yet. Ask them to open the whiteboard panel (or this link themselves: ${url}). Do not open board links in a browser or preview tool yourself.` };
+        const { opened, note } = await openViewer(url);
+        return opened ? { launched: true, note: `${note}.` } : { launched: false, note: `${note}, so the human can't see the board yet; ask them to open ${url}.` };
     }
     /** Shows the board and waits until a viewer is connected; false if none arrives. */
     async revealAndWait(client, ref) {
@@ -356,7 +363,8 @@ export const TOOLS = [
             const shown = args.open === false ? '' : await ctx.reveal(client, ref, snap.viewers);
             const others = boards.filter((b) => b.id !== ref.id).sort((a, b) => b.updatedAt - a.updatedAt).slice(0, 10);
             const mine = ref.id === own.id;
-            return text(`${mine ? "This chat's board" : `Board from another chat${elsewhere ? ` (${elsewhere})` : ''}`}: ${boardName(ref)} [${ref.id}]. ${snap.viewers ? 'The human is watching it.' : shown}`, loaded && `Loaded a copy of saved board "${loaded.name}" [${loaded.id}]; the saved copy stays unchanged.`, snap.elements.length ? describeScene(snap.elements, { maxElements: 12 }) : 'The board is empty.', others.length > 0 && `Other boards in this workspace (open one with board): ${others.map((b) => `${b.title === b.id ? '(untitled)' : b.title} [${b.id}, ${b.elementCount} el]`).join('; ')}`, !mine && 'Drawing now changes that board; canvas_open {board:"own"} switches back to this chat\'s board.');
+            const summary = text(`${mine ? "This chat's board" : `Board from another chat${elsewhere ? ` (${elsewhere})` : ''}`}: ${boardName(ref)} [${ref.id}]. ${snap.viewers ? 'The human is watching it.' : shown}`, loaded && `Loaded a copy of saved board "${loaded.name}" [${loaded.id}]; the saved copy stays unchanged.`, snap.elements.length ? describeScene(snap.elements, { maxElements: 12 }) : 'The board is empty.', others.length > 0 && `Other boards in this workspace (open one with board): ${others.map((b) => `${b.title === b.id ? '(untitled)' : b.title} [${b.id}, ${b.elementCount} el]`).join('; ')}`, !mine && 'Drawing now changes that board; canvas_open {board:"own"} switches back to this chat\'s board.');
+            return summary;
         },
     },
     {

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@ansuman-shukla/whiteboard-mcp",
-  "version": "0.1.0",
-  "description": "A live whiteboard your coding agent draws on to explain things, side by side with you. MCP server and CLI with a hand-drawn Excalidraw canvas.",
+  "version": "0.2.0",
+  "mcpName": "io.github.ansuman-shukla/whiteboard-mcp",
+  "description": "Local, offline Excalidraw whiteboard MCP server: your coding agent (Claude Code, Codex, Cursor, Gemini CLI, VS Code) draws diagrams live beside the chat and sees what you draw back. Also a CLI.",
   "type": "module",
   "bin": {
     "whiteboard-mcp": "dist/cli.js"
@@ -13,7 +14,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "npm run build:frontend && npm run build:server",
+    "build": "npm run build:frontend && npm run build:server && node scripts/build-vsix.mjs dist/vscode",
     "build:frontend": "vite build",
     "build:server": "tsc -p tsconfig.json && node -e \"require('fs').chmodSync('dist/cli.js',0o755)\"",
     "build:vscode": "node scripts/build-vsix.mjs",
@@ -51,13 +52,34 @@
   "keywords": [
     "mcp",
     "mcp-server",
+    "model-context-protocol",
     "excalidraw",
+    "excalidraw-mcp",
     "whiteboard",
+    "whiteboard-mcp",
+    "canvas",
+    "diagram",
     "diagrams",
+    "architecture-diagram",
+    "flowchart",
+    "mermaid",
+    "drawing",
+    "visualization",
+    "offline",
+    "local-first",
     "coding-agent",
+    "ai-agent",
+    "llm",
+    "claude",
     "claude-code",
+    "claude-desktop",
     "codex",
-    "opencode"
+    "cursor",
+    "gemini-cli",
+    "vscode",
+    "windsurf",
+    "opencode",
+    "devin"
   ],
   "license": "MIT",
   "publishConfig": {

package/skills/whiteboard-explainer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: whiteboard-explainer
-description: Explain code, architecture, data flows, algorithms, plans or trade-offs visually on a live whiteboard shown to the user beside the chat (they can draw on it or annotate). Use when a diagram would explain better than prose, when the user asks to "draw", "sketch", "diagram", "visualise" or "show" something, or when they mention the canvas, the whiteboard or something they drew.
+description: Explain code, architecture, data flows, algorithms, plans or trade-offs visually on a live Excalidraw whiteboard (Whiteboard MCP) shown to the user beside the chat (they can draw on it or annotate). Use when a diagram would explain better than prose, when the user asks to "draw", "sketch", "diagram", "visualise" or "show" something, or when they mention the canvas, the whiteboard or something they drew.
 ---
 
 # Excalidraw explainer
@@ -14,7 +14,7 @@ A live whiteboard shared with the user. You draw through the `whiteboard-mcp` MC
 
 ## The live explain loop
 
-1. **Open**: `canvas_open {"title":"<topic>"}` once per topic. It shows this chat's board to the user and tells you what is already on it. Never open board links in a browser or preview tool yourself. Call `canvas_guide` once if you haven't read it yet (layout, sizes, colours).
+1. **Open**: `canvas_open {"title":"<topic>"}` once per topic. It shows this chat's board to the user and tells you what is already on it, and where it showed it (see below). Call `canvas_guide` once if you haven't read it yet (layout, sizes, colours).
 2. **Draw step by step**: one `canvas_draw` per idea (the components, then the flow between them, then annotations). After each call, write one or two short sentences in chat that point at the canvas ("the blue boxes are the services"). The canvas carries the detail, keep the chat brief.
 3. **Point**: `canvas_focus {"ids":["api","db"],"highlight":true}` when you talk about specific parts.
 4. **Check once**: after the main layout, `canvas_screenshot` one time to catch overlaps or cut-off labels, then fix them with `canvas_draw` on the same ids.
@@ -22,6 +22,28 @@ A live whiteboard shared with the user. You draw through the `whiteboard-mcp` MC
 6. **Update, don't redraw**: re-send an existing id with only the fields that change (`{"id":"api","x":400}`, `{"id":"db","label":"Postgres"}`). Use `canvas_delete` for removals. Start over only with `canvas_open {"fresh":true}`.
 7. **Keep it**: when a drawing is worth reusing or the user asks to save it, `canvas_save {"name":"<topic>"}` stores a frozen copy in the user's library (the user can also save from the board's menu or with Cmd/Ctrl+S). In a later chat, in any workspace, `canvas_search {"query":"<words>"}` finds other chats' live boards and saved copies: `canvas_open {"board":"<id>"}` opens a live one, `canvas_open {"saved":"<id>"}` loads a copy into this chat's board (add `"fresh":true` if the board already has a drawing). When the user names a board loosely and `canvas_open {board}` doesn't find it, it lists the closest boards: pick the one they meant by id.
 
+## Editing an existing drawing
+
+When the user asks to change a drawing that's already there ("put a cache between the API and the DB"):
+
+1. **Read first**: `canvas_read` (or the `canvas_open` result) lists every element with its id, label, position, size and what each arrow connects. Work from those ids and coordinates, never from memory of what you drew earlier: the user may have moved or edited things.
+2. **Edit by id**: re-send only the fields that change, in one `canvas_draw`. Make room by moving existing shapes (`{"id":"db","x":520}`), then add the new ones in the freed space. Shapes the user drew have generated ids; use them as listed.
+3. **Re-point arrows**: change an existing arrow's ends (`{"id":"q","to":"cache"}`) rather than deleting and redrawing it. Arrows follow the shapes they're bound to when those move.
+4. **Delete**: `canvas_delete {"ids":["old"]}` for what goes away. Arrows bound to a deleted shape are detached, not deleted: re-point or delete them too.
+5. **Focus**: `canvas_focus {"ids":["cache"],"highlight":true}` on what changed, and say in a sentence what changed and why.
+6. **Check**: one `canvas_screenshot` after bigger edits; fix overlaps or cut-off labels with `canvas_draw` on the same ids.
+
+## Where the board shows
+
+The tools put the board in front of the user themselves; read the `canvas_open` result to know where:
+
+- **"Shown to the human beside the chat."**: an editor tab beside the chat (VS Code, Cursor, Windsurf and other VS Code-based editors, with the Whiteboard MCP extension). Nothing to do.
+- **"Open the board in your in-app browser or preview tool"**: no editor tab can show it here (an editor without the extension, or a desktop chat app). Open the link the result gives in your in-app browser or preview tool right away, so the board shows beside the chat.
+- **"opened with open"**: outside an editor (a plain terminal), the board opened in the browser. That's the right place there.
+- **"Nobody is watching the board"**: the user closed it; call `canvas_open` again when you want them to see it.
+
+Board links go in your in-app browser or preview tool (the editor's or app's built-in browser beside the chat), never an external browser: that would take the user out of the app.
+
 ## Element cheatsheet
 
 - Shapes: `{"id":"api","type":"rectangle","x":0,"y":0,"label":"API","backgroundColor":"blue"}`. ellipse = start/end/actor, diamond = decision, frame = zone.