@excaliwow/mcp 0.4.0 → 0.5.0

package/README.md

@@ -37,7 +37,7 @@ token to your account:
   "mcpServers": {
     "excaliwow": {
       "command": "npx",
-      "args": ["-y", "@excaliwow/mcp@0.4.0"],
+      "args": ["-y", "@excaliwow/mcp@0.5.0"],
       "env": {
         "EXCALIWOW_TOKEN": "excw_pat_…"
       }
@@ -53,7 +53,7 @@ you've reviewed a new release.
 
 ## Troubleshooting
 
-**`npx -y @excaliwow/mcp@0.4.0` fails with `ENOENT … /@excaliwow/mcp@0.4.0/package.json`.**
+**`npx -y @excaliwow/mcp@0.5.0` fails with `ENOENT … /@excaliwow/mcp@0.5.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.4.0
+npm i -g @excaliwow/mcp@0.5.0
 ```
 
 ```json
@@ -102,19 +102,24 @@ npx -y @excaliwow/mcp --health
 
 Eight 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 element counts) **plus** a rendered PNG.    |
-| `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. |
+| `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. `trash_diagram` / `restore_diagram` are a **reversible** pair
+context small. Pass `includeGeometry: true` to additionally get a compact,
+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.
+`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`,
 so a `read` + `write` token can't trash anything. Hard-delete/purge and making a

package/dist/bin.js

@@ -279,6 +279,49 @@ var COMPACT_GRAMMAR = `DiagramSpec (auto-laid-out node/edge DSL):
 }
 Caps: <=1000 nodes, <=2000 edges, label <=2000 chars, <=5000 total scene elements.`;
 
+// src/geometry.ts
+function num(v) {
+  return typeof v === "number" && Number.isFinite(v) ? Math.round(v) : 0;
+}
+function isObject(v) {
+  return typeof v === "object" && v !== null;
+}
+function extractGeometry(elements) {
+  const els = Array.isArray(elements) ? elements : [];
+  const labelByContainer = /* @__PURE__ */ new Map();
+  for (const el of els) {
+    if (!isObject(el) || el.isDeleted === true) continue;
+    if (el.type === "text" && typeof el.containerId === "string" && el.containerId) {
+      labelByContainer.set(el.containerId, typeof el.text === "string" ? el.text : "");
+    }
+  }
+  const items = [];
+  for (const el of els) {
+    if (!isObject(el) || el.isDeleted === true) continue;
+    const id = typeof el.id === "string" ? el.id : String(el.id ?? "");
+    const type = typeof el.type === "string" ? el.type : "unknown";
+    const label = el.type === "text" ? typeof el.text === "string" ? el.text : "" : labelByContainer.get(id) ?? "";
+    items.push({
+      id,
+      type,
+      label,
+      x: num(el.x),
+      y: num(el.y),
+      w: num(el.width),
+      h: num(el.height)
+    });
+  }
+  return items;
+}
+function formatGeometry(items) {
+  if (items.length === 0) return "geometry: (none \u2014 empty diagram)";
+  const body = items.map((it) => JSON.stringify(it)).join(",\n");
+  return `geometry (${items.length} element${items.length === 1 ? "" : "s"}):
+[
+${body}
+]`;
+}
+
 // src/reference.ts
 var DSL_REFERENCE_URI = "excaliwow://dsl/reference";
 var DSL_REFERENCE_MARKDOWN = `# Excaliwow DSL reference
@@ -457,7 +500,7 @@ var EditFragmentZ = z.object({
 });
 
 // src/version.ts
-var VERSION = "0.4.0";
+var VERSION = "0.5.0";
 
 // src/server.ts
 function textResult(text) {
@@ -542,10 +585,10 @@ function createServer(deps) {
     "read_diagram",
     {
       title: "Read a diagram",
-      description: "Read a diagram as a compact text summary (title + element counts) plus a PNG image block so a vision model can see it. Never returns the raw scene JSON. A failed or empty render degrades to text-only with a note (the read never fails on a render error).",
-      inputSchema: { id: z2.string() }
+      description: "Read a diagram as a compact text summary (title + element counts) plus a PNG image block so a vision model can see it. Never returns the raw scene JSON. A failed or empty render degrades to text-only with a note (the read never fails on a render error). Pass includeGeometry=true to also get a compact, bounded list of element bounds ({ id, type, label, x, y, w, h }, top-left x/y) so you can DETECT label/box collisions or misplaced nodes programmatically \u2014 it comes from the scene, so it is present even when the render fails.",
+      inputSchema: { id: z2.string(), includeGeometry: z2.boolean().optional() }
     },
-    async ({ id }) => {
+    async ({ id, includeGeometry }) => {
       let detail;
       try {
         const ctx = buildCtx(deps);
@@ -553,28 +596,33 @@ function createServer(deps) {
         const { total, byType } = elementBreakdown(detail);
         const breakdown = Object.entries(byType).sort(([a], [b]) => a.localeCompare(b)).map(([t, n]) => `${t}: ${n}`).join(", ");
         const summary = `${detail.title || "(untitled)"} \u2014 ${total} element${total === 1 ? "" : "s"}` + (breakdown ? ` (${breakdown})` : "");
+        let summaryNote = "";
+        let imageBlock;
         try {
           const png = await renderDiagram(ctx, id, { format: "png" });
           if (png && png.bytes.length > 0) {
-            const text = png.quality && png.quality !== "faithful" ? `${summary}
-preview fidelity: ${png.quality} \u2014 faithful renderer unavailable; layout/fonts approximate` : summary;
-            return {
-              content: [
-                { type: "text", text },
-                {
-                  type: "image",
-                  data: Buffer.from(png.bytes).toString("base64"),
-                  mimeType: "image/png"
-                }
-              ]
+            if (png.quality && png.quality !== "faithful") {
+              summaryNote = `
+preview fidelity: ${png.quality} \u2014 faithful renderer unavailable; layout/fonts approximate`;
+            }
+            imageBlock = {
+              type: "image",
+              data: Buffer.from(png.bytes).toString("base64"),
+              mimeType: "image/png"
             };
+          } else {
+            summaryNote = "\n(no preview: the diagram renders empty)";
           }
-          return textResult(`${summary}
-(no preview: the diagram renders empty)`);
         } catch {
-          return textResult(`${summary}
-(no preview: render failed)`);
+          summaryNote = "\n(no preview: render failed)";
+        }
+        const content = [{ type: "text", text: summary + summaryNote }];
+        if (includeGeometry) {
+          const elements = Array.isArray(detail.scene?.elements) ? detail.scene.elements : [];
+          content.push({ type: "text", text: formatGeometry(extractGeometry(elements)) });
         }
+        if (imageBlock) content.push(imageBlock);
+        return { content };
       } catch (err) {
         return toErrorResult(err);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@excaliwow/mcp",
-  "version": "0.4.0",
+  "version": "0.5.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": {