@venturewild/workspace 0.6.1 → 0.6.2

package/server/src/canvas/index.mjs

@@ -1,42 +1,42 @@
-// Canvas runtime glue for the main server: the agent-facing system prompt and the
-// path to the canvas MCP server (wired into the turn's --mcp-config by turn-mcp.mjs).
-
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-export const CANVAS_MCP_SERVER_PATH = path.join(__dirname, 'mcp-server.mjs');
-
-// Appended to the agent's system prompt on user chat turns. Sets the disposition:
-// the canvas is the user's space and the agent can build them a widget on request,
-// but it builds DATA (a declarative block), never code, and it touches the canvas
-// lightly (offer/confirm, don't spam). Plain language, no jargon.
-export const CANVAS_SYSTEM_PROMPT = [
-  "The user's workspace is a *block canvas* — a home screen of widget-cards (like iPhone widgets or",
-  "Notion blocks) they arrange themselves. You can BUILD them a custom block with the canvas tools",
-  "(mcp__canvas__make_block, update_block, list_blocks).",
-  "",
-  "When the user asks to \"make/add a block\", wants a small dashboard or widget, or asks to \"show me",
-  "<something>\" that's worth keeping in view (a count, a leaderboard, a status, a short note), build it:",
-  "first work out the ACTUAL data yourself (read files or run commands as needed), then call make_block",
-  "with the simplest kind that fits — metric (one headline number), list ({label,value} rows), table",
-  "(columns + rows), or markdown (a short note). The block appears on their canvas right away; then say",
-  "in one short line what you added.",
-  "",
-  "You are shipping DATA, not code — you pass values, and the canvas renders them. Don't try to write a",
-  "component or HTML; pick a kind and fill its fields.",
-  "",
-  "To keep a block current, call update_block with its id and the changed fields (that's how a block",
-  "stays \"live\" — you re-push when the numbers change). Use list_blocks to find an id when the user",
-  "refers to a block you made earlier. Only make a block when it genuinely helps — don't clutter their",
-  "canvas with blocks they didn't ask for.",
-  "",
-  "You can also RESTYLE the whole workspace with set_theme when the user asks to change the look",
-  "(\"make it dark\", \"match my brand\", \"give me a calm sunset theme\", etc.). Choose a base mode",
-  "(light|dark) and the token colours (bg, surface, text, border, and the three wallpaper stops",
-  "canvas1/2/3) that complete the look — pass hex values like \"#1a0f14\". You're shipping COLOURS, not",
-  "CSS; the change applies to their screen at once. You do NOT set the accent — that's the user's own",
-  "signature colour, preserved across restyles — so describe the mode and background you applied, never",
-  "an accent change. Call get_theme first if you're tweaking the current look. Keep good contrast.",
-].join('\n');
+// Canvas runtime glue for the main server: the agent-facing system prompt and the
+// path to the canvas MCP server (wired into the turn's --mcp-config by turn-mcp.mjs).
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export const CANVAS_MCP_SERVER_PATH = path.join(__dirname, 'mcp-server.mjs');
+
+// Appended to the agent's system prompt on user chat turns. Sets the disposition:
+// the canvas is the user's space and the agent can build them a widget on request,
+// but it builds DATA (a declarative block), never code, and it touches the canvas
+// lightly (offer/confirm, don't spam). Plain language, no jargon.
+export const CANVAS_SYSTEM_PROMPT = [
+  "The user's workspace is a *block canvas* — a home screen of widget-cards (like iPhone widgets or",
+  "Notion blocks) they arrange themselves. You can BUILD them a custom block with the canvas tools",
+  "(mcp__canvas__make_block, update_block, list_blocks).",
+  "",
+  "When the user asks to \"make/add a block\", wants a small dashboard or widget, or asks to \"show me",
+  "<something>\" that's worth keeping in view (a count, a leaderboard, a status, a short note), build it:",
+  "first work out the ACTUAL data yourself (read files or run commands as needed), then call make_block",
+  "with the simplest kind that fits — metric (one headline number), list ({label,value} rows), table",
+  "(columns + rows), or markdown (a short note). The block appears on their canvas right away; then say",
+  "in one short line what you added.",
+  "",
+  "You are shipping DATA, not code — you pass values, and the canvas renders them. Don't try to write a",
+  "component or HTML; pick a kind and fill its fields.",
+  "",
+  "To keep a block current, call update_block with its id and the changed fields (that's how a block",
+  "stays \"live\" — you re-push when the numbers change). Use list_blocks to find an id when the user",
+  "refers to a block you made earlier. Only make a block when it genuinely helps — don't clutter their",
+  "canvas with blocks they didn't ask for.",
+  "",
+  "You can also RESTYLE the whole workspace with set_theme when the user asks to change the look",
+  "(\"make it dark\", \"match my brand\", \"give me a calm sunset theme\", etc.). Choose a base mode",
+  "(light|dark) and the token colours (bg, surface, text, border, and the three wallpaper stops",
+  "canvas1/2/3) that complete the look — pass hex values like \"#1a0f14\". You're shipping COLOURS, not",
+  "CSS; the change applies to their screen at once. You do NOT set the accent — that's the user's own",
+  "signature colour, preserved across restyles — so describe the mode and background you applied, never",
+  "an accent change. Call get_theme first if you're tweaking the current look. Keep good contrast.",
+].join('\n');

package/server/src/canvas/mcp-server.mjs

@@ -1,253 +1,253 @@
-// Canvas MCP server — the tools the agent uses to BUILD the user a block (§3.3).
-//
-// Same hand-rolled stdio JSON-RPC 2.0 shape as the bazaar MCP server (no new dep,
-// wrap-don't-embed). `claude` spawns this per turn via --mcp-config and exposes the
-// tools as mcp__canvas__<name>. It imports the SAME core.mjs the main server uses
-// (state under ~/.wild-workspace/canvas/), so there is one source of truth and no
-// HTTP/port handshake. Tool results are JSON envelopes the UI parses to mount the
-// block on the canvas.
-//
-// stdout carries ONLY JSON-RPC. Any diagnostics go to stderr.
-
-import readline from 'node:readline';
-import { createCanvas, KINDS } from './core.mjs';
-
-// The theme-token params set_theme accepts (each an optional hex color). Kept here
-// as schema; core.mjs is the validator (hex-only, allowlisted). "Data, not CSS."
-const THEME_TOKEN_PROPS = {
-  bg: { type: 'string', description: 'page background, hex e.g. "#0a0c10".' },
-  surface: { type: 'string', description: 'card / panel face, hex.' },
-  text: { type: 'string', description: 'primary text, hex.' },
-  textMuted: { type: 'string', description: 'secondary/muted text, hex.' },
-  border: { type: 'string', description: 'hairline borders, hex.' },
-  canvas1: { type: 'string', description: 'wallpaper gradient stop 1, hex.' },
-  canvas2: { type: 'string', description: 'wallpaper gradient stop 2, hex.' },
-  canvas3: { type: 'string', description: 'wallpaper gradient stop 3, hex.' },
-};
-
-const canvas = createCanvas(); // baseDir from WILD_WORKSPACE_GLOBAL_DIR (set by parent)
-const PROTOCOL_VERSION = '2025-06-18';
-
-function send(msg) {
-  process.stdout.write(`${JSON.stringify(msg)}\n`);
-}
-function result(id, res) {
-  send({ jsonrpc: '2.0', id, result: res });
-}
-function errorReply(id, code, message) {
-  send({ jsonrpc: '2.0', id, error: { code, message } });
-}
-function textContent(obj) {
-  return { content: [{ type: 'text', text: JSON.stringify(obj) }] };
-}
-
-// --- tool definitions -----------------------------------------------------
-
-// Shared description of the spec vocabulary, kept in one place so make/update agree.
-const SHAPE_HELP =
-  "Pick the simplest `kind` that fits and fill only that kind's fields:\n" +
-  "- metric: a single headline number. value (required, e.g. \"42\" or \"$1,240\"), " +
-  "label (what it counts), delta (\"+12 today\"), trend (\"up\"|\"down\"|\"flat\"), " +
-  "spark (array of recent numbers for a tiny chart).\n" +
-  "- list: items — an array of { label, value } (value optional). Good for leaderboards/breakdowns.\n" +
-  "- table: columns (array of headers) + rows (array of arrays of cells).\n" +
-  "- markdown: markdown — a short rich-text note.\n" +
-  "Compute the actual values yourself first (read files / run commands as needed), then pass them in. " +
-  "You are shipping DATA, not code.";
-
-const TOOLS = [
-  {
-    name: 'make_block',
-    description:
-      "Build the user a custom block and pin it to their canvas. Use this when the user asks to " +
-      "\"make/add a block\", wants a dashboard/widget, or asks to \"show me <something>\" that's worth " +
-      "keeping in view. The block appears on their canvas immediately. " +
-      SHAPE_HELP,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        title: { type: 'string', description: 'Short title shown on the block header.' },
-        kind: { type: 'string', enum: KINDS, description: 'The presentation primitive.' },
-        icon: { type: 'string', description: 'A single emoji for the block (optional).' },
-        note: { type: 'string', description: 'A one-line subtitle: what this shows (optional).' },
-        value: { type: 'string', description: 'metric: the headline value.' },
-        label: { type: 'string', description: 'metric: what the value counts.' },
-        delta: { type: 'string', description: 'metric: a change indicator, e.g. "+12 today".' },
-        trend: { type: 'string', enum: ['up', 'down', 'flat'], description: 'metric: colours the delta.' },
-        spark: { type: 'array', items: { type: 'number' }, description: 'metric: recent numbers for a sparkline.' },
-        items: {
-          type: 'array',
-          description: 'list: { label, value } entries.',
-          items: { type: 'object', properties: { label: { type: 'string' }, value: { type: 'string' } } },
-        },
-        columns: { type: 'array', items: { type: 'string' }, description: 'table: column headers.' },
-        rows: { type: 'array', items: { type: 'array', items: { type: 'string' } }, description: 'table: rows of cells.' },
-        markdown: { type: 'string', description: 'markdown: the rich-text body.' },
-      },
-      required: ['title', 'kind'],
-    },
-  },
-  {
-    name: 'update_block',
-    description:
-      "Refresh an existing custom block with new data (this is how a block stays \"live\" — you re-push " +
-      "when the underlying numbers change). Pass the block id and only the fields that change. " +
-      SHAPE_HELP,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        id: { type: 'string', description: 'The block id returned by make_block.' },
-        title: { type: 'string' },
-        kind: { type: 'string', enum: KINDS },
-        icon: { type: 'string' },
-        note: { type: 'string' },
-        value: { type: 'string' },
-        label: { type: 'string' },
-        delta: { type: 'string' },
-        trend: { type: 'string', enum: ['up', 'down', 'flat'] },
-        spark: { type: 'array', items: { type: 'number' } },
-        items: { type: 'array', items: { type: 'object', properties: { label: { type: 'string' }, value: { type: 'string' } } } },
-        columns: { type: 'array', items: { type: 'string' } },
-        rows: { type: 'array', items: { type: 'array', items: { type: 'string' } } },
-        markdown: { type: 'string' },
-      },
-      required: ['id'],
-    },
-  },
-  {
-    name: 'list_blocks',
-    description:
-      "List the custom blocks currently on the user's canvas (id, title, kind) — use this to find the " +
-      "id of a block the user refers to before calling update_block.",
-    inputSchema: { type: 'object', properties: {} },
-  },
-  {
-    name: 'set_theme',
-    description:
-      "Restyle the user's whole workspace (the \"make it mine\" surface). Use this when the user asks to " +
-      "change the look — \"make it dark\", \"match my brand\", \"give me a sunset / forest / high-contrast " +
-      "theme\", etc. Pick a `mode` (light|dark) as the base, then the token colours that complete the look — " +
-      "the background, surfaces, text, and the three wallpaper stops. The change applies immediately. You " +
-      "ship COLOURS (hex values), not CSS. NOTE: you do NOT set the accent colour — that is the user's own " +
-      "signature colour (chosen in onboarding or the theme picker) and is preserved across every restyle. " +
-      "Describe the mode and background/wallpaper you applied; do NOT claim to have changed their accent.",
-    inputSchema: {
-      type: 'object',
-      properties: {
-        mode: { type: 'string', enum: ['light', 'dark'], description: 'Base palette: light or dark.' },
-        name: { type: 'string', description: 'A short name for the theme (optional, e.g. "Sunset").' },
-        ...THEME_TOKEN_PROPS,
-      },
-    },
-  },
-  {
-    name: 'get_theme',
-    description: "Read the user's current theme (mode, accent, tokens) — use before tweaking it.",
-    inputSchema: { type: 'object', properties: {} },
-  },
-];
-
-// --- tool dispatch --------------------------------------------------------
-
-function callTool(name, args = {}) {
-  switch (name) {
-    case 'make_block': {
-      try {
-        const block = canvas.addBlock(args);
-        return textContent({
-          kind: 'block',
-          op: 'make',
-          block,
-          note: 'Block is now on the user\'s canvas. Tell them in one short line what you added.',
-        });
-      } catch (e) {
-        return { ...textContent({ kind: 'error', error: e?.message || String(e) }), isError: true };
-      }
-    }
-    case 'update_block': {
-      const block = canvas.updateBlock(args.id, args);
-      if (!block) return { ...textContent({ kind: 'error', error: `no block "${args.id}"` }), isError: true };
-      return textContent({ kind: 'block', op: 'update', block, note: 'Block updated in place on the canvas.' });
-    }
-    case 'list_blocks': {
-      const blocks = canvas.listBlocks().map((b) => ({ id: b.id, title: b.title, kind: b.kind }));
-      return textContent({ kind: 'blocks', count: blocks.length, blocks });
-    }
-    case 'set_theme': {
-      const theme = canvas.setTheme(args);
-      return textContent({
-        kind: 'theme',
-        op: 'set',
-        theme,
-        note:
-          "The user's workspace is now restyled (mode + background/wallpaper). Their accent colour is " +
-          "preserved — it's their own. Tell them in one short line what look you applied; describe the " +
-          "mode and background, NOT an accent colour.",
-      });
-    }
-    case 'get_theme': {
-      return textContent({ kind: 'theme', op: 'get', theme: canvas.getTheme() });
-    }
-    default:
-      return { ...textContent({ kind: 'error', error: `unknown tool ${name}` }), isError: true };
-  }
-}
-
-// --- JSON-RPC loop --------------------------------------------------------
-
-export function handleMessage(msg) {
-  if (!msg || msg.jsonrpc !== '2.0') return;
-  const { id, method, params } = msg;
-  const isNotification = id === undefined || id === null;
-
-  switch (method) {
-    case 'initialize':
-      return result(id, {
-        protocolVersion: params?.protocolVersion || PROTOCOL_VERSION,
-        capabilities: { tools: {} },
-        serverInfo: { name: 'canvas', version: '1.0.0' },
-      });
-    case 'notifications/initialized':
-    case 'initialized':
-      return; // notification, no response
-    case 'ping':
-      return result(id, {});
-    case 'tools/list':
-      return result(id, { tools: TOOLS });
-    case 'tools/call': {
-      try {
-        const out = callTool(params?.name, params?.arguments || {});
-        return result(id, out);
-      } catch (e) {
-        return errorReply(id, -32603, `tool error: ${e?.message || e}`);
-      }
-    }
-    default:
-      if (!isNotification) errorReply(id, -32601, `method not found: ${method}`);
-      return;
-  }
-}
-
-// Only run the stdio loop when executed as the MCP process (not when imported by a test).
-const isDirectRun = process.argv[1] && process.argv[1].endsWith('mcp-server.mjs');
-if (isDirectRun) {
-  const rl = readline.createInterface({ input: process.stdin });
-  rl.on('line', (line) => {
-    const trimmed = line.trim();
-    if (!trimmed) return;
-    let msg;
-    try {
-      msg = JSON.parse(trimmed);
-    } catch {
-      return; // ignore non-JSON noise
-    }
-    try {
-      handleMessage(msg);
-    } catch (e) {
-      process.stderr.write(`canvas mcp error: ${e?.message || e}\n`);
-    }
-  });
-  process.stderr.write('canvas mcp server ready\n');
-}
-
-export { TOOLS, callTool };
+// Canvas MCP server — the tools the agent uses to BUILD the user a block (§3.3).
+//
+// Same hand-rolled stdio JSON-RPC 2.0 shape as the bazaar MCP server (no new dep,
+// wrap-don't-embed). `claude` spawns this per turn via --mcp-config and exposes the
+// tools as mcp__canvas__<name>. It imports the SAME core.mjs the main server uses
+// (state under ~/.wild-workspace/canvas/), so there is one source of truth and no
+// HTTP/port handshake. Tool results are JSON envelopes the UI parses to mount the
+// block on the canvas.
+//
+// stdout carries ONLY JSON-RPC. Any diagnostics go to stderr.
+
+import readline from 'node:readline';
+import { createCanvas, KINDS } from './core.mjs';
+
+// The theme-token params set_theme accepts (each an optional hex color). Kept here
+// as schema; core.mjs is the validator (hex-only, allowlisted). "Data, not CSS."
+const THEME_TOKEN_PROPS = {
+  bg: { type: 'string', description: 'page background, hex e.g. "#0a0c10".' },
+  surface: { type: 'string', description: 'card / panel face, hex.' },
+  text: { type: 'string', description: 'primary text, hex.' },
+  textMuted: { type: 'string', description: 'secondary/muted text, hex.' },
+  border: { type: 'string', description: 'hairline borders, hex.' },
+  canvas1: { type: 'string', description: 'wallpaper gradient stop 1, hex.' },
+  canvas2: { type: 'string', description: 'wallpaper gradient stop 2, hex.' },
+  canvas3: { type: 'string', description: 'wallpaper gradient stop 3, hex.' },
+};
+
+const canvas = createCanvas(); // baseDir from WILD_WORKSPACE_GLOBAL_DIR (set by parent)
+const PROTOCOL_VERSION = '2025-06-18';
+
+function send(msg) {
+  process.stdout.write(`${JSON.stringify(msg)}\n`);
+}
+function result(id, res) {
+  send({ jsonrpc: '2.0', id, result: res });
+}
+function errorReply(id, code, message) {
+  send({ jsonrpc: '2.0', id, error: { code, message } });
+}
+function textContent(obj) {
+  return { content: [{ type: 'text', text: JSON.stringify(obj) }] };
+}
+
+// --- tool definitions -----------------------------------------------------
+
+// Shared description of the spec vocabulary, kept in one place so make/update agree.
+const SHAPE_HELP =
+  "Pick the simplest `kind` that fits and fill only that kind's fields:\n" +
+  "- metric: a single headline number. value (required, e.g. \"42\" or \"$1,240\"), " +
+  "label (what it counts), delta (\"+12 today\"), trend (\"up\"|\"down\"|\"flat\"), " +
+  "spark (array of recent numbers for a tiny chart).\n" +
+  "- list: items — an array of { label, value } (value optional). Good for leaderboards/breakdowns.\n" +
+  "- table: columns (array of headers) + rows (array of arrays of cells).\n" +
+  "- markdown: markdown — a short rich-text note.\n" +
+  "Compute the actual values yourself first (read files / run commands as needed), then pass them in. " +
+  "You are shipping DATA, not code.";
+
+const TOOLS = [
+  {
+    name: 'make_block',
+    description:
+      "Build the user a custom block and pin it to their canvas. Use this when the user asks to " +
+      "\"make/add a block\", wants a dashboard/widget, or asks to \"show me <something>\" that's worth " +
+      "keeping in view. The block appears on their canvas immediately. " +
+      SHAPE_HELP,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title: { type: 'string', description: 'Short title shown on the block header.' },
+        kind: { type: 'string', enum: KINDS, description: 'The presentation primitive.' },
+        icon: { type: 'string', description: 'A single emoji for the block (optional).' },
+        note: { type: 'string', description: 'A one-line subtitle: what this shows (optional).' },
+        value: { type: 'string', description: 'metric: the headline value.' },
+        label: { type: 'string', description: 'metric: what the value counts.' },
+        delta: { type: 'string', description: 'metric: a change indicator, e.g. "+12 today".' },
+        trend: { type: 'string', enum: ['up', 'down', 'flat'], description: 'metric: colours the delta.' },
+        spark: { type: 'array', items: { type: 'number' }, description: 'metric: recent numbers for a sparkline.' },
+        items: {
+          type: 'array',
+          description: 'list: { label, value } entries.',
+          items: { type: 'object', properties: { label: { type: 'string' }, value: { type: 'string' } } },
+        },
+        columns: { type: 'array', items: { type: 'string' }, description: 'table: column headers.' },
+        rows: { type: 'array', items: { type: 'array', items: { type: 'string' } }, description: 'table: rows of cells.' },
+        markdown: { type: 'string', description: 'markdown: the rich-text body.' },
+      },
+      required: ['title', 'kind'],
+    },
+  },
+  {
+    name: 'update_block',
+    description:
+      "Refresh an existing custom block with new data (this is how a block stays \"live\" — you re-push " +
+      "when the underlying numbers change). Pass the block id and only the fields that change. " +
+      SHAPE_HELP,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'The block id returned by make_block.' },
+        title: { type: 'string' },
+        kind: { type: 'string', enum: KINDS },
+        icon: { type: 'string' },
+        note: { type: 'string' },
+        value: { type: 'string' },
+        label: { type: 'string' },
+        delta: { type: 'string' },
+        trend: { type: 'string', enum: ['up', 'down', 'flat'] },
+        spark: { type: 'array', items: { type: 'number' } },
+        items: { type: 'array', items: { type: 'object', properties: { label: { type: 'string' }, value: { type: 'string' } } } },
+        columns: { type: 'array', items: { type: 'string' } },
+        rows: { type: 'array', items: { type: 'array', items: { type: 'string' } } },
+        markdown: { type: 'string' },
+      },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'list_blocks',
+    description:
+      "List the custom blocks currently on the user's canvas (id, title, kind) — use this to find the " +
+      "id of a block the user refers to before calling update_block.",
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'set_theme',
+    description:
+      "Restyle the user's whole workspace (the \"make it mine\" surface). Use this when the user asks to " +
+      "change the look — \"make it dark\", \"match my brand\", \"give me a sunset / forest / high-contrast " +
+      "theme\", etc. Pick a `mode` (light|dark) as the base, then the token colours that complete the look — " +
+      "the background, surfaces, text, and the three wallpaper stops. The change applies immediately. You " +
+      "ship COLOURS (hex values), not CSS. NOTE: you do NOT set the accent colour — that is the user's own " +
+      "signature colour (chosen in onboarding or the theme picker) and is preserved across every restyle. " +
+      "Describe the mode and background/wallpaper you applied; do NOT claim to have changed their accent.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        mode: { type: 'string', enum: ['light', 'dark'], description: 'Base palette: light or dark.' },
+        name: { type: 'string', description: 'A short name for the theme (optional, e.g. "Sunset").' },
+        ...THEME_TOKEN_PROPS,
+      },
+    },
+  },
+  {
+    name: 'get_theme',
+    description: "Read the user's current theme (mode, accent, tokens) — use before tweaking it.",
+    inputSchema: { type: 'object', properties: {} },
+  },
+];
+
+// --- tool dispatch --------------------------------------------------------
+
+function callTool(name, args = {}) {
+  switch (name) {
+    case 'make_block': {
+      try {
+        const block = canvas.addBlock(args);
+        return textContent({
+          kind: 'block',
+          op: 'make',
+          block,
+          note: 'Block is now on the user\'s canvas. Tell them in one short line what you added.',
+        });
+      } catch (e) {
+        return { ...textContent({ kind: 'error', error: e?.message || String(e) }), isError: true };
+      }
+    }
+    case 'update_block': {
+      const block = canvas.updateBlock(args.id, args);
+      if (!block) return { ...textContent({ kind: 'error', error: `no block "${args.id}"` }), isError: true };
+      return textContent({ kind: 'block', op: 'update', block, note: 'Block updated in place on the canvas.' });
+    }
+    case 'list_blocks': {
+      const blocks = canvas.listBlocks().map((b) => ({ id: b.id, title: b.title, kind: b.kind }));
+      return textContent({ kind: 'blocks', count: blocks.length, blocks });
+    }
+    case 'set_theme': {
+      const theme = canvas.setTheme(args);
+      return textContent({
+        kind: 'theme',
+        op: 'set',
+        theme,
+        note:
+          "The user's workspace is now restyled (mode + background/wallpaper). Their accent colour is " +
+          "preserved — it's their own. Tell them in one short line what look you applied; describe the " +
+          "mode and background, NOT an accent colour.",
+      });
+    }
+    case 'get_theme': {
+      return textContent({ kind: 'theme', op: 'get', theme: canvas.getTheme() });
+    }
+    default:
+      return { ...textContent({ kind: 'error', error: `unknown tool ${name}` }), isError: true };
+  }
+}
+
+// --- JSON-RPC loop --------------------------------------------------------
+
+export function handleMessage(msg) {
+  if (!msg || msg.jsonrpc !== '2.0') return;
+  const { id, method, params } = msg;
+  const isNotification = id === undefined || id === null;
+
+  switch (method) {
+    case 'initialize':
+      return result(id, {
+        protocolVersion: params?.protocolVersion || PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: { name: 'canvas', version: '1.0.0' },
+      });
+    case 'notifications/initialized':
+    case 'initialized':
+      return; // notification, no response
+    case 'ping':
+      return result(id, {});
+    case 'tools/list':
+      return result(id, { tools: TOOLS });
+    case 'tools/call': {
+      try {
+        const out = callTool(params?.name, params?.arguments || {});
+        return result(id, out);
+      } catch (e) {
+        return errorReply(id, -32603, `tool error: ${e?.message || e}`);
+      }
+    }
+    default:
+      if (!isNotification) errorReply(id, -32601, `method not found: ${method}`);
+      return;
+  }
+}
+
+// Only run the stdio loop when executed as the MCP process (not when imported by a test).
+const isDirectRun = process.argv[1] && process.argv[1].endsWith('mcp-server.mjs');
+if (isDirectRun) {
+  const rl = readline.createInterface({ input: process.stdin });
+  rl.on('line', (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    let msg;
+    try {
+      msg = JSON.parse(trimmed);
+    } catch {
+      return; // ignore non-JSON noise
+    }
+    try {
+      handleMessage(msg);
+    } catch (e) {
+      process.stderr.write(`canvas mcp error: ${e?.message || e}\n`);
+    }
+  });
+  process.stderr.write('canvas mcp server ready\n');
+}
+
+export { TOOLS, callTool };