@excaliwow/mcp 0.2.1 → 0.4.0

package/README.md

@@ -8,9 +8,10 @@ client (Claude Desktop, Claude Code, etc.) can launch it with `npx`.
 ## Install
 
 First mint a Personal Access Token at https://excaliwow.com/app/settings
-(Settings → Developer / API tokens) with **`read` + `write`** capabilities — that
-is everything the server's tools need (see [Security notes](#security-notes)).
-Pass it as `EXCALIWOW_TOKEN`.
+(Settings → Developer / API tokens) with **`read` + `write`** capabilities —
+enough for six of the eight tools. Add **`delete`** only if you want the agent
+to trash and restore diagrams (see [Security notes](#security-notes)). Pass it as
+`EXCALIWOW_TOKEN`.
 
 ### Claude Code (CLI)
 
@@ -36,7 +37,7 @@ token to your account:
   "mcpServers": {
     "excaliwow": {
       "command": "npx",
-      "args": ["-y", "@excaliwow/mcp@0.2.1"],
+      "args": ["-y", "@excaliwow/mcp@0.4.0"],
       "env": {
         "EXCALIWOW_TOKEN": "excw_pat_…"
       }
@@ -52,7 +53,7 @@ you've reviewed a new release.
 
 ## Troubleshooting
 
-**`npx -y @excaliwow/mcp@0.2.1` fails with `ENOENT … /@excaliwow/mcp@0.2.1/package.json`.**
+**`npx -y @excaliwow/mcp@0.4.0` fails with `ENOENT … /@excaliwow/mcp@0.4.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
@@ -61,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.2.1
+npm i -g @excaliwow/mcp@0.4.0
 ```
 
 ```json
@@ -99,20 +100,27 @@ npx -y @excaliwow/mcp --health
 
 ## Tools
 
-Five tools, scoped to safe agent use:
+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.                                                 |
-| `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). |
+| 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.           |
 
 `read_diagram` returns a summary + image, **never** the raw scene JSON, to keep
-context small. Making a diagram publicly shareable is deliberately **not** an
-agent tool — so a misled agent can't be tricked into exposing your diagram. Use
-the dashboard or the CLI to publish.
+context small. `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
+diagram publicly shareable are deliberately **not** agent tools — those are
+irreversible, so a misled agent can't destroy or expose your diagram. Purge or
+publish from the dashboard or the CLI.
 
 ### DSL discovery
 
@@ -134,11 +142,14 @@ resource at **`excaliwow://dsl/reference`**.
 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 only `read` + `write`.** Those are the only capabilities the five
-  tools use (see the table above); none publish or delete. So a `read` + `write`
-  PAT can neither expose your diagrams publicly nor delete them, even if the
-  agent is misled. Pick those two capabilities specifically — the coarse
-  `read-write` preset additionally grants `publish` and `delete`.
+- **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
+  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
+  able to soft-delete and restore — it's reversible, but it's still a capability
+  to grant deliberately. Pick capabilities specifically rather than the coarse
+  `read-write` preset, which additionally grants `publish` (and `delete`).
 - **Pin the version** in your client config rather than floating on `@latest`,
   and review release notes before bumping.
 - The token is a credential to your account. It lives only in your MCP client

package/dist/bin.js

@@ -205,6 +205,36 @@ function moveDiagram(ctx, id, folderId) {
     fetchImpl: ctx.fetchImpl
   });
 }
+function deleteDiagram(ctx, id) {
+  return request({
+    method: "DELETE",
+    path: `${PREFIX}/diagrams/${encodeURIComponent(id)}`,
+    token: ctx.token,
+    baseUrl: ctx.baseUrl,
+    fetchImpl: ctx.fetchImpl
+  });
+}
+function restoreDiagram(ctx, id) {
+  return request({
+    method: "POST",
+    path: `${PREFIX}/diagrams/${encodeURIComponent(id)}/restore`,
+    token: ctx.token,
+    baseUrl: ctx.baseUrl,
+    fetchImpl: ctx.fetchImpl
+  });
+}
+function regenerateDiagram(ctx, id, args) {
+  const body = { spec: args.spec };
+  if (args.title !== void 0) body.title = args.title;
+  return request({
+    method: "POST",
+    path: `${PREFIX}/diagrams/${encodeURIComponent(id)}/regenerate`,
+    token: ctx.token,
+    baseUrl: ctx.baseUrl,
+    body,
+    fetchImpl: ctx.fetchImpl
+  });
+}
 
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -427,7 +457,7 @@ var EditFragmentZ = z.object({
 });
 
 // src/version.ts
-var VERSION = "0.2.1";
+var VERSION = "0.4.0";
 
 // src/server.ts
 function textResult(text) {
@@ -625,6 +655,82 @@ preview fidelity: ${png.quality} \u2014 faithful renderer unavailable; layout/fo
       }
     }
   );
+  server2.registerTool(
+    "trash_diagram",
+    {
+      title: "Trash a diagram (soft delete)",
+      description: "Soft-delete a diagram to trash. REVERSIBLE \u2014 restore_diagram brings it back, and it stays visible under list_diagrams with filter='trash'. Use this to clean up diagrams you no longer want (e.g. earlier drafts from iterating). Requires a Personal Access Token with the `delete` capability; without it the call returns a clean 'insufficient_scope' error and changes nothing. Idempotent on an already-trashed id.",
+      inputSchema: { id: z2.string() }
+    },
+    async ({ id }) => {
+      try {
+        const ctx = buildCtx(deps);
+        await deleteDiagram(ctx, id);
+        return textResult(JSON.stringify({ id, trashed: true }));
+      } catch (err) {
+        return toErrorResult(err);
+      }
+    }
+  );
+  server2.registerTool(
+    "restore_diagram",
+    {
+      title: "Restore a diagram from trash",
+      description: "Restore a soft-deleted diagram from trash, reopening it in the editor at its original id and url. The inverse of trash_diagram. Requires a Personal Access Token with the `delete` capability; without it the call returns a clean 'insufficient_scope' error and changes nothing. Idempotent on an already-active id.",
+      inputSchema: { id: z2.string() }
+    },
+    async ({ id }) => {
+      try {
+        const ctx = buildCtx(deps);
+        await restoreDiagram(ctx, id);
+        return textResult(JSON.stringify({ id, restored: true }));
+      } catch (err) {
+        return toErrorResult(err);
+      }
+    }
+  );
+  server2.registerTool(
+    "regenerate_diagram",
+    {
+      title: "Regenerate a diagram (replace in place)",
+      description: [
+        "REPLACE an existing diagram's entire contents from a fresh DiagramSpec: the spec is",
+        "re-laid-out server-side and swapped in, keeping the SAME id and url. Use this to ITERATE",
+        "on one diagram (fix layout, restructure) instead of generate_diagram, which mints a NEW",
+        "id+url each time and orphans the old one. Unlike edit_diagram (which only appends/patches),",
+        "this discards the old scene entirely. Comments anchored to a shape the new layout no longer",
+        "contains are detached (returned as orphanedComments); comments on shapes whose node id you",
+        "reuse stay attached. Pass an optional title to rename in the same call. Returns the id, the",
+        "new element count (replaced), orphanedComments, and the editor url.",
+        "",
+        COMPACT_GRAMMAR,
+        "",
+        "See the `" + DSL_REFERENCE_URI + "` resource for the full DSL reference."
+      ].join("\n"),
+      inputSchema: {
+        id: z2.string(),
+        title: z2.string().nullish(),
+        spec: DiagramSpecZ
+      }
+    },
+    async ({ id, title, spec }) => {
+      try {
+        const ctx = buildCtx(deps);
+        const result = await regenerateDiagram(ctx, id, { spec, title: title ?? void 0 });
+        return textResult(
+          JSON.stringify({
+            id: result.id,
+            replaced: result.replaced,
+            orphanedComments: result.orphanedComments,
+            ...result.title !== void 0 ? { title: result.title } : {},
+            url: editorUrl(ctx, result.id)
+          })
+        );
+      } catch (err) {
+        return toErrorResult(err);
+      }
+    }
+  );
   server2.registerResource(
     "dsl-reference",
     DSL_REFERENCE_URI,

package/package.json

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