@venturewild/workspace 0.1.13 → 0.2.0

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

@@ -0,0 +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 };