vizo-mcp 0.2.0 → 0.3.0

package/README.md

@@ -3,12 +3,16 @@
 stdio MCP proxy for a [Vizo](https://vizo.twinkle.hk) whiteboard server, for MCP clients that only speak stdio.
 
 ```sh
-claude mcp add vizo -- npx -y vizo-mcp --url https://vizo.twinkle.hk --token vz_…
+claude mcp add vizo -- npx -y vizo-mcp@latest --url https://vizo.twinkle.hk --token vz_…
 ```
 
 Create a token at `<url>/settings`. `VIZO_URL` and `VIZO_TOKEN` work instead of the flags.
 
-Diagrams (`draw_diagram`, `update_diagram`) are laid out on your machine and sent to the server finished. The proxy's layout version must match the server's: if they differ, the server refuses the call and asks you to update, e.g. `npx -y vizo-mcp@latest`.
+Diagrams (`draw_diagram`, `update_diagram`) are laid out on your machine and sent to the server finished. The proxy's layout version must match the server's: if they differ, the server refuses the call and asks you to update. With `vizo-mcp@latest` in the command, as above, restarting your MCP client is enough: npx checks for a newer version on each start (without `@latest` it keeps reusing the copy it cached first).
+
+## Adding images
+
+`add_image` also takes a local file `path` here: the proxy reads the file and uploads it. The image is placed on the board, or with `place: false` only uploaded, and the returned `fileId` can be used as a flowchart or component node's `image` to show the picture in a diagram.
 
 ## Exporting images
 

package/dist/index.js

@@ -15,6 +15,8 @@ import {
   ListToolsRequestSchema,
   ReadResourceRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
+import { readFileSync as readFileSync3, statSync } from "node:fs";
+import { resolve as resolve2 } from "node:path";
 
 // ../diagram/src/schema.ts
 import { z } from "zod";
@@ -41,11 +43,16 @@ var Group = z.object({
   children: z.array(id).describe("Node ids (or nested group ids) inside this group"),
   color: Color.optional()
 });
+var nodeImage = {
+  image: z.string().min(1).max(128).regex(/^[A-Za-z0-9_-]+$/, "image must be a fileId").optional().describe("fileId of an image on this board (from add_image, or an image's fileId in get_board). The node becomes a card: picture above the label."),
+  imageSize: z.number().min(16).max(800).optional().describe("Longer side of the picture in board units (default 96)")
+};
 var FlowchartNode = z.object({
   id,
   label,
-  shape: z.enum(["process", "decision", "terminal", "io", "database", "subroutine", "note"]).optional().describe("process (default) rectangle; decision diamond; terminal start/end pill; database; note sticky"),
-  color: Color.optional()
+  shape: z.enum(["process", "decision", "terminal", "io", "database", "subroutine", "note"]).optional().describe("process (default) rectangle; decision diamond; terminal start/end pill; database; note sticky. Nodes with an image are always rectangles."),
+  color: Color.optional(),
+  ...nodeImage
 });
 var FlowchartSpec = z.object({
   kind: z.literal("flowchart"),
@@ -61,7 +68,8 @@ var ComponentNode = z.object({
   type: z.enum(["service", "database", "queue", "cache", "client", "external", "storage", "function", "user", "generic"]).optional().describe("Drives the shape and color"),
   tech: z.string().max(60).optional().describe("Technology caption, e.g. 'PostgreSQL', 'React'"),
   description: z.string().max(200).optional(),
-  color: Color.optional()
+  color: Color.optional(),
+  ...nodeImage
 });
 var ComponentSpec = z.object({
   kind: z.literal("component"),
@@ -159,6 +167,10 @@ var DiagramSpec = z.discriminatedUnion("kind", [
   StateSpec,
   MindmapSpec
 ]);
+function specImageIds(spec) {
+  const nodes = spec.kind === "flowchart" || spec.kind === "component" ? spec.nodes : [];
+  return [...new Set(nodes.flatMap((n) => n.image ? [n.image] : []))];
+}
 function validateSpec(spec) {
   const errors = [];
   const check = (ids, refs, what, groups) => {
@@ -433,6 +445,15 @@ function arrowLabel(a2, value, o = {}) {
   a2.boundElements = [...a2.boundElements ?? [], { id: t.id, type: "text" }];
   return t;
 }
+function image(id2, x, y, w, h, fileId, o = {}) {
+  return {
+    ...base(id2, "image", x, y, w, h, { strokeColor: "transparent", ...o }),
+    fileId,
+    status: "saved",
+    scale: [1, 1],
+    crop: null
+  };
+}
 function frame(id2, x, y, w, h, name, o = {}) {
   return { ...base(id2, "frame", x, y, w, h, { roughness: 0, strokeColor: "#bbb", ...o }), roundness: null, name };
 }
@@ -677,6 +698,43 @@ function labelledNode(ctx, nodeId, label2, kind, colors, opts = {}) {
     }
   };
 }
+var CARD_PAD = 10;
+var CARD_GAP = 8;
+var BOUND_TEXT_PADDING = 5;
+function imageCard(ctx, nodeId, label2, fileId, size, colors, opts = {}) {
+  const fontSize = opts.fontSize ?? NODE_FONT;
+  const natural = ctx.images[fileId];
+  const k = size / Math.max(natural.width, natural.height);
+  const iw = Math.round(natural.width * k);
+  const ih = Math.round(natural.height * k);
+  const wrapped = wrapText(label2, fontSize, ctx.look.font, Math.max(MAX_LABEL_W, iw));
+  const m = measureText(wrapped, fontSize, ctx.look.font);
+  const w = Math.ceil(Math.max(opts.minW ?? 120, iw + CARD_PAD * 2, m.width + 10 + CARD_PAD * 2));
+  const h = Math.ceil(CARD_PAD + ih + CARD_GAP + m.height + BOUND_TEXT_PADDING);
+  const id2 = `${ctx.idPrefix}.n.${nodeId}`;
+  return {
+    id: nodeId,
+    width: w,
+    height: h,
+    bindId: id2,
+    render: (x, y) => {
+      const groupIds = [`${id2}.grp`];
+      const s = shape("rectangle", id2, x, y, w, h, {
+        strokeColor: colors.stroke,
+        backgroundColor: colors.bg,
+        strokeStyle: opts.strokeStyle,
+        roughness: ctx.look.roughness,
+        groupIds,
+        customData: ctx.cd("node", nodeId)
+      });
+      const pic = image(`${id2}.img`, x + (w - iw) / 2, y + CARD_PAD, iw, ih, fileId, { groupIds, customData: ctx.cd("node-image", nodeId) });
+      const t = boundText(s, wrapped, { fontSize, font: ctx.look.font, strokeColor: INK, verticalAlign: "bottom" });
+      t.y = y + h - BOUND_TEXT_PADDING - t.height;
+      return [s, pic, t];
+    }
+  };
+}
+var DEFAULT_IMAGE_SIZE = 96;
 var fill = (c) => ({ stroke: INK, bg: PALETTE[c][1] });
 function flowchartModel(spec, ctx) {
   const nodes = spec.nodes.map((n) => {
@@ -691,6 +749,11 @@ function flowchartModel(spec, ctx) {
       note: ["rectangle", "yellow"]
     };
     const [kind, color] = def[shp];
+    if (n.image)
+      return imageCard(ctx, n.id, n.label, n.image, n.imageSize ?? DEFAULT_IMAGE_SIZE, fill(n.color ?? color), {
+        strokeStyle: shp === "note" ? "dashed" : "solid",
+        fontSize: shp === "note" ? 16 : NODE_FONT
+      });
     return labelledNode(ctx, n.id, n.label, kind, fill(n.color ?? color), {
       strokeStyle: shp === "note" ? "dashed" : "solid",
       fontSize: shp === "note" ? 16 : NODE_FONT
@@ -725,6 +788,12 @@ function componentModel(spec, ctx) {
     if (n.tech) lines.push(`[${n.tech}]`);
     else if (st.caption) lines.push(`\xAB${st.caption}\xBB`);
     if (n.description) lines.push(wrapText(n.description, 16, ctx.look.font, MAX_LABEL_W));
+    if (n.image)
+      return imageCard(ctx, n.id, lines.join("\n"), n.image, n.imageSize ?? DEFAULT_IMAGE_SIZE, fill(n.color ?? st.color), {
+        strokeStyle: st.dashed ? "dashed" : "solid",
+        fontSize: n.description ? 16 : 18,
+        minW: 160
+      });
     return labelledNode(ctx, n.id, lines.join("\n"), st.kind, fill(n.color ?? st.color), {
       strokeStyle: st.dashed ? "dashed" : "solid",
       fontSize: n.description ? 16 : 18,
@@ -1215,7 +1284,7 @@ function layoutSequence(spec, ctx) {
 
 // ../diagram/src/render.ts
 var FRAME_PAD = 40;
-var LAYOUT_VERSION = 1;
+var LAYOUT_VERSION = 2;
 var SpecError = class extends Error {
   constructor(issues) {
     super(`Invalid diagram spec:
@@ -1238,7 +1307,10 @@ async function renderDiagram(spec, opts) {
   const look = LOOKS[spec.style ?? "sketch"];
   const idPrefix = opts.diagramId;
   const cd = (role, ref) => vizoData(opts.diagramId, role, ref);
-  const ctx = { idPrefix, look, cd };
+  const images = opts.images ?? {};
+  const missing = specImageIds(spec).filter((id2) => !images[id2]);
+  if (missing.length) throw new SpecError(missing.map((id2) => `image '${id2}' is not on this board; upload it with add_image and use the fileId it returns`));
+  const ctx = { idPrefix, look, cd, images };
   let els;
   switch (spec.kind) {
     case "flowchart":
@@ -3690,7 +3762,7 @@ function exportSvg(input, files, opts = {}) {
         const symbolId = `image-${file.id}`;
         if (!imageSymbols.has(symbolId)) {
           imageSymbols.add(symbolId);
-          defs.unshift(`<symbol id="${esc(symbolId)}"><image href="${esc(file.dataURL)}" preserveAspectRatio="none" width="100%" height="100%"/></symbol>`);
+          defs.unshift(`<symbol id="${esc(symbolId)}" viewBox="0 0 1 1" preserveAspectRatio="none"><image href="${esc(file.dataURL)}" preserveAspectRatio="none" width="1" height="1"/></symbol>`);
         }
         const flip = e.scale && (e.scale[0] !== 1 || e.scale[1] !== 1) ? `translate(${cx} ${cy}) scale(${e.scale[0]} ${e.scale[1]}) translate(${-cx} ${-cy})` : void 0;
         let g = `<g${attrs({ transform: transform() })}><use${attrs({ href: `#${symbolId}`, width: Math.round(e.width), height: Math.round(e.height), opacity, transform: flip })}/></g>`;
@@ -3989,7 +4061,10 @@ async function exportImage(scene, args) {
 var PROXY_HEADER = "X-Vizo-Proxy";
 var PUT_TOOL = "put_diagram_elements";
 var SCENE_TOOL = "get_board_scene";
-var HIDDEN = /* @__PURE__ */ new Set([PUT_TOOL, SCENE_TOOL]);
+var SIZES_TOOL = "get_image_sizes";
+var HIDDEN = /* @__PURE__ */ new Set([PUT_TOOL, SCENE_TOOL, SIZES_TOOL]);
+var IMAGE_TOOL = "add_image";
+var MAX_IMAGE_BYTES = 47e5;
 var LOCAL_TOOLS = /* @__PURE__ */ new Set(["draw_diagram", "update_diagram"]);
 var toolError = (text2) => ({ content: [{ type: "text", text: text2 }], isError: true });
 function arg(name) {
@@ -4008,14 +4083,14 @@ async function main() {
     process.exit(2);
   }
   const endpoint = new URL(base2.endsWith("/mcp") ? base2 : `${base2}/mcp`);
-  const upstream = new Client({ name: "vizo-mcp-proxy", version: "0.2.0" });
+  const upstream = new Client({ name: "vizo-mcp-proxy", version: "0.3.0" });
   await upstream.connect(
     new StreamableHTTPClientTransport(endpoint, { requestInit: { headers: { Authorization: `Bearer ${token}`, [PROXY_HEADER]: String(LAYOUT_VERSION) } } })
   );
   const caps = upstream.getServerCapabilities() ?? {};
   log(`connected to ${endpoint.href} (local layout v${LAYOUT_VERSION})`);
   const server = new Server(
-    { name: "vizo", version: "0.2.0" },
+    { name: "vizo", version: "0.3.0" },
     {
       capabilities: {
         tools: caps.tools ? {} : void 0,
@@ -4034,12 +4109,22 @@ This local proxy also has export_image: save a board or some of its diagrams as
       const r = await upstream.listTools(req.params);
       if (r.tools.some((t) => t.name === PUT_TOOL)) serverSupportsLocal = true;
       serverSupportsExport = r.tools.some((t) => t.name === SCENE_TOOL);
-      const tools = r.tools.filter((t) => !HIDDEN.has(t.name));
+      const tools = r.tools.filter((t) => !HIDDEN.has(t.name)).map((t) => t.name === IMAGE_TOOL ? withPath(t) : t);
       return { ...r, tools: serverSupportsExport && !r.nextCursor ? [...tools, EXPORT_TOOL] : tools };
     });
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
       const { name, arguments: args = {} } = req.params;
       if (name === EXPORT_TOOL.name) return exportLocally(args);
+      if (name === IMAGE_TOOL && typeof args.path === "string") {
+        const { path, ...rest } = args;
+        let dataURL;
+        try {
+          dataURL = readImage(path);
+        } catch (e) {
+          return toolError(e instanceof Error ? e.message : String(e));
+        }
+        return upstream.callTool({ ...req.params, arguments: { ...rest, dataURL } });
+      }
       if (!LOCAL_TOOLS.has(name)) return upstream.callTool(req.params);
       serverSupportsLocal ??= (await upstream.listTools()).tools.some((t) => t.name === PUT_TOOL);
       if (!serverSupportsLocal) {
@@ -4070,7 +4155,21 @@ This local proxy also has export_image: save a board or some of its diagrams as
     const drawing = name === "draw_diagram";
     const diagramId = drawing ? `d-${randomId(8)}` : String(args.diagramId ?? "");
     if (!diagramId) return toolError("diagramId is required");
-    const r = await renderDiagram(spec, { diagramId });
+    const imageIds = specImageIds(spec);
+    let images = {};
+    if (imageIds.length) {
+      const res = await upstream.callTool({ name: SIZES_TOOL, arguments: { boardId: args.boardId, fileIds: imageIds } });
+      const body = res.content?.find((c) => c.type === "text")?.text ?? "";
+      if (res.isError) return toolError(body || "Couldn't read the board's images.");
+      images = Object.fromEntries(JSON.parse(body).map((f) => [f.id, { width: f.width, height: f.height }]));
+    }
+    let r;
+    try {
+      r = await renderDiagram(spec, { diagramId, images });
+    } catch (e) {
+      if (e instanceof SpecError) return toolError(e.message);
+      throw e;
+    }
     return upstream.callTool({
       name: PUT_TOOL,
       arguments: {
@@ -4106,6 +4205,30 @@ This local proxy also has export_image: save a board or some of its diagrams as
   process.on("SIGTERM", shutdown);
   process.stdin.on("close", shutdown);
 }
+function withPath(t) {
+  const schema = t.inputSchema ?? { type: "object", properties: {} };
+  return {
+    ...t,
+    description: `${t.description ?? ""} Here you can also pass a local file \`path\` instead of url/dataURL.`,
+    inputSchema: {
+      ...schema,
+      properties: { path: { type: "string", description: "Image file on this machine (absolute, or relative to the working directory); use instead of url/dataURL" }, ...schema.properties }
+    }
+  };
+}
+var MIME = { png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp", bmp: "image/bmp", svg: "image/svg+xml" };
+function readImage(path) {
+  const full = resolve2(path);
+  let size;
+  try {
+    size = statSync(full).size;
+  } catch {
+    throw new Error(`No such file: ${full}`);
+  }
+  if (size > MAX_IMAGE_BYTES) throw new Error(`Image too large (${(size / 1e6).toFixed(1)} MB; max ${MAX_IMAGE_BYTES / 1e6} MB). Use a smaller or more compressed image.`);
+  const mime = MIME[full.split(".").pop()?.toLowerCase() ?? ""] ?? "application/octet-stream";
+  return `data:${mime};base64,${readFileSync3(full).toString("base64")}`;
+}
 main().catch((e) => {
   log(e instanceof Error ? e.message : e);
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vizo-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "stdio MCP proxy for a Vizo whiteboard server",
   "license": "MIT",
   "type": "module",