@excaliwow/mcp 0.5.0 → 0.7.0

package/README.md

@@ -9,7 +9,7 @@ client (Claude Desktop, Claude Code, etc.) can launch it with `npx`.
 
 First mint a Personal Access Token at https://excaliwow.com/app/settings
 (Settings → Developer / API tokens) with **`read` + `write`** capabilities —
-enough for six of the eight tools. Add **`delete`** only if you want the agent
+enough for seven of the nine tools. Add **`delete`** only if you want the agent
 to trash and restore diagrams (see [Security notes](#security-notes)). Pass it as
 `EXCALIWOW_TOKEN`.
 
@@ -37,7 +37,7 @@ token to your account:
   "mcpServers": {
     "excaliwow": {
       "command": "npx",
-      "args": ["-y", "@excaliwow/mcp@0.5.0"],
+      "args": ["-y", "@excaliwow/mcp@0.6.0"],
       "env": {
         "EXCALIWOW_TOKEN": "excw_pat_…"
       }
@@ -53,7 +53,7 @@ you've reviewed a new release.
 
 ## Troubleshooting
 
-**`npx -y @excaliwow/mcp@0.5.0` fails with `ENOENT … /@excaliwow/mcp@0.5.0/package.json`.**
+**`npx -y @excaliwow/mcp@0.6.0` fails with `ENOENT … /@excaliwow/mcp@0.6.0/package.json`.**
 On some npm/Node versions, `npx` misreads a scoped package + `@version` spec as a
 local directory. It's an upstream npm bug (it reproduces with other scoped
 packages, e.g. `@modelcontextprotocol/server-filesystem@1.0.0`), not an Excaliwow one. Either
@@ -62,7 +62,7 @@ above does), or pin safely by installing once and pointing the client at the
 binary:
 
 ```sh
-npm i -g @excaliwow/mcp@0.5.0
+npm i -g @excaliwow/mcp@0.6.0
 ```
 
 ```json
@@ -100,18 +100,19 @@ npx -y @excaliwow/mcp --health
 
 ## Tools
 
-Eight tools, scoped to safe agent use:
+Nine tools, scoped to safe agent use:
 
-| Tool                 | Capability | What it does                                                                                                     |
-| -------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------- |
-| `generate_diagram`   | `write`    | Create a diagram from the high-level node/edge DSL; returns the editor URL.                                      |
-| `read_diagram`       | `read`     | Compact summary (title + per-type counts) **plus** a rendered PNG; opt into `includeGeometry` for a bounds list. |
-| `list_diagrams`      | `read`     | Page through your diagrams (`filter: active \| trash`).                                                          |
-| `move_diagram`       | `write`    | Move a diagram to a folder (or to root).                                                                         |
-| `edit_diagram`       | `write`    | Additively merge a DSL fragment (add nodes/edges, update node style/label).                                      |
-| `regenerate_diagram` | `write`    | Replace a diagram's contents in place from a fresh spec (re-layout, same id).                                    |
-| `trash_diagram`      | `delete`   | Soft-delete a diagram to trash. **Reversible** (see `restore_diagram`).                                          |
-| `restore_diagram`    | `delete`   | Restore a trashed diagram, reopening it at its original id and URL.                                              |
+| Tool                 | Capability | What it does                                                                                                        |
+| -------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------- |
+| `generate_diagram`   | `write`    | Create a diagram from the high-level node/edge DSL; returns the editor URL.                                         |
+| `read_diagram`       | `read`     | Compact summary (title + per-type counts) **plus** a rendered PNG; opt into `includeGeometry` for a bounds list.    |
+| `export_diagram`     | `read`     | Render to full-fidelity bytes to **save** (png base64, or svg as raw text) — the bytes to keep, not a vision image. |
+| `list_diagrams`      | `read`     | Page through your diagrams (`filter: active \| trash`).                                                             |
+| `move_diagram`       | `write`    | Move a diagram to a folder (or to root).                                                                            |
+| `edit_diagram`       | `write`    | Additively merge a DSL fragment (add nodes/edges, update node style/label).                                         |
+| `regenerate_diagram` | `write`    | Replace a diagram's contents in place from a fresh spec (re-layout, same id).                                       |
+| `trash_diagram`      | `delete`   | Soft-delete a diagram to trash. **Reversible** (see `restore_diagram`).                                             |
+| `restore_diagram`    | `delete`   | Restore a trashed diagram, reopening it at its original id and URL.                                                 |
 
 `read_diagram` returns a summary + image, **never** the raw scene JSON, to keep
 context small. Pass `includeGeometry: true` to additionally get a compact,
@@ -119,6 +120,15 @@ bounded `{ id, type, label, x, y, w, h }` list (top-left x/y) so the agent can
 **detect** label/box collisions or misplaced nodes programmatically instead of
 eyeballing the PNG — it is derived from the scene, so it is present even when the
 render fails, and it is a small fixed-field summary, not the raw element dump.
+`export_diagram` returns the rendered **bytes** to save to a file — png as
+base64, svg as raw text — distinct from `read_diagram`, which returns an image
+block for a vision model to look at. An MCP server runs over stdio and cannot
+write to your repo, so a client with filesystem access (e.g. Claude Code) decodes
+and saves the bytes itself. Or skip the round-trip through the model and stream
+straight to disk with the CLI: `excaliwow diagrams render <id> -o
+docs/architecture.png` (or `.svg`) — also the fallback when a render is too large
+to return inline.
+
 `trash_diagram` / `restore_diagram` are a **reversible** pair
 gated on the `delete` capability — registered always, they return a clean
 `insufficient_scope` error (changing nothing) unless the token carries `delete`,
@@ -148,7 +158,7 @@ project`) puts the token into git history. Use a user- or local-scoped config
   (`--scope local`), or reference an environment variable instead of pasting the
   literal token.
 - **Mint with `read` + `write` (add `delete` only if you want trash/restore).**
-  Six of the eight tools need just `read` + `write`; a `read` + `write` PAT can
+  Seven of the nine tools need just `read` + `write`; a `read` + `write` PAT can
   neither expose your diagrams publicly nor delete them, even if the agent is
   misled (`trash_diagram` / `restore_diagram` simply return `insufficient_scope`
   and do nothing). Add the `delete` capability only if you want the agent to be

package/dist/bin.js

@@ -266,7 +266,8 @@ var COMPACT_GRAMMAR = `DiagramSpec (auto-laid-out node/edge DSL):
       "width": 140, "height": 60,       // optional; treated as a minimum
       "strokeColor": "#1e1e1e",         // optional
       "backgroundColor": "transparent", // optional
-      "fillStyle": "solid" }            // hachure | cross-hatch | solid | zigzag
+      "fillStyle": "solid",             // hachure | cross-hatch | solid | zigzag
+      "group": "hardware" }             // optional layout hint (not a guarantee); clusters same-group nodes; members with edges among them still span ranks
   ],
   "edges": [                            // optional
     { "from": "id", "to": "id",         // both must name existing node ids
@@ -279,6 +280,26 @@ var COMPACT_GRAMMAR = `DiagramSpec (auto-laid-out node/edge DSL):
 }
 Caps: <=1000 nodes, <=2000 edges, label <=2000 chars, <=5000 total scene elements.`;
 
+// src/export.ts
+var MAX_INLINE_EXPORT_BYTES = 1e6;
+function buildExportPayload(id, format, img) {
+  const { bytes } = img;
+  if (bytes.length > MAX_INLINE_EXPORT_BYTES) {
+    return { ok: false, bytes: bytes.length };
+  }
+  const buf = Buffer.from(bytes);
+  const payload = {
+    id,
+    format,
+    encoding: format === "svg" ? "utf8" : "base64",
+    bytes: bytes.length,
+    ...img.quality ? { quality: img.quality } : {},
+    ...img.note ? { note: img.note } : {},
+    data: format === "svg" ? buf.toString("utf8") : buf.toString("base64")
+  };
+  return { ok: true, payload };
+}
+
 // src/geometry.ts
 function num(v) {
   return typeof v === "number" && Number.isFinite(v) ? Math.round(v) : 0;
@@ -357,7 +378,8 @@ and the **EditFragment** for \`edit_diagram\`.
   "height": 60,
   "strokeColor": "#1e1e1e",
   "backgroundColor": "transparent",
-  "fillStyle": "solid"
+  "fillStyle": "solid",
+  "group": "hardware"
 }
 \`\`\`
 
@@ -370,6 +392,7 @@ and the **EditFragment** for \`edit_diagram\`.
 | \`strokeColor\` | string? | Any CSS color. |
 | \`backgroundColor\` | string? | Any CSS color, or \`transparent\`. |
 | \`fillStyle\` | enum? | \`hachure\` \\| \`cross-hatch\` \\| \`solid\` \\| \`zigzag\`. |
+| \`group\` | string? | Layout **hint** (not a guarantee). Nodes sharing a \`group\` are clustered together by auto-layout \u2014 kept in the same region, and a member that an edge would otherwise float onto a separate rank is pulled back toward the group. Sibling nodes with no edges *among themselves* (e.g. a set of sensors hanging off one controller) band into a single row; members that have edges between them still span ranks. Affects auto-layout (generate / regenerate) only \u2014 not \`edit_diagram\`; a one-member group is a no-op. |
 
 Default sizes: rectangle 140x60, ellipse 140x80, diamond 160x90. A \`text\` node IS its text.
 
@@ -462,7 +485,8 @@ var NodeSpecZ = z.object({
   height: z.number().optional(),
   strokeColor: z.string().optional(),
   backgroundColor: z.string().optional(),
-  fillStyle: FillStyleZ.optional()
+  fillStyle: FillStyleZ.optional(),
+  group: z.string().optional()
 });
 var EdgeObjectZ = z.object({
   from: z.string(),
@@ -500,7 +524,7 @@ var EditFragmentZ = z.object({
 });
 
 // src/version.ts
-var VERSION = "0.5.0";
+var VERSION = "0.7.0";
 
 // src/server.ts
 function textResult(text) {
@@ -779,6 +803,33 @@ preview fidelity: ${png.quality} \u2014 faithful renderer unavailable; layout/fo
       }
     }
   );
+  server2.registerTool(
+    "export_diagram",
+    {
+      title: "Export a diagram to render bytes (for saving)",
+      description: "Render a diagram to full-fidelity bytes intended to be SAVED to a file. Returns a JSON text block { id, format, encoding, bytes, data } \u2014 for png, data is base64; for svg, data is the raw SVG text. In a client with filesystem access (e.g. Claude Code) decode `data` and write it yourself (e.g. docs/architecture.png). Defaults to png; pass format='svg' for the resolution-independent faithful vector. This differs from read_diagram, which returns an image block for a VISION model to look at \u2014 export_diagram gives you the bytes to keep. Requires only the `read` capability. An empty diagram returns a clean error (nothing to export); a render too large to return inline returns a clean error pointing at the CLI (`excaliwow diagrams render <id> -o <file>`), which streams straight to disk.",
+      inputSchema: { id: z2.string(), format: z2.enum(["png", "svg"]).optional() }
+    },
+    async ({ id, format }) => {
+      try {
+        const ctx = buildCtx(deps);
+        const fmt = format ?? "png";
+        const img = await renderDiagram(ctx, id, { format: fmt });
+        if (img == null) {
+          return errorResult(`diagram_empty: ${id} renders empty \u2014 there is nothing to export.`);
+        }
+        const built = buildExportPayload(id, fmt, img);
+        if (!built.ok) {
+          return errorResult(
+            `export_too_large: the ${fmt} render is ${built.bytes} bytes, over the ${MAX_INLINE_EXPORT_BYTES}-byte inline limit. Save it directly with the CLI instead: excaliwow diagrams render ${id} -o <file>.${fmt}`
+          );
+        }
+        return textResult(JSON.stringify(built.payload));
+      } catch (err) {
+        return toErrorResult(err);
+      }
+    }
+  );
   server2.registerResource(
     "dsl-reference",
     DSL_REFERENCE_URI,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@excaliwow/mcp",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Excaliwow Model Context Protocol (MCP) server — lets AI agents create, read, render, and edit Excaliwow diagrams over the public REST API, via stdio.",
   "private": false,
   "publishConfig": {