@excaliwow/mcp 0.2.0 → 0.3.0

package/README.md

@@ -7,7 +7,26 @@ client (Claude Desktop, Claude Code, etc.) can launch it with `npx`.
 
 ## Install
 
-Add it to your MCP client's config file (e.g. Claude Desktop's
+First mint a Personal Access Token at https://excaliwow.com/app/settings
+(Settings → Developer / API tokens) with **`read` + `write`** capabilities —
+enough for five of the seven 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)
+
+One command. `--scope local` stores the server in your own settings, so the
+token never lands in a file you might commit:
+
+```sh
+claude mcp add excaliwow --scope local \
+  --env EXCALIWOW_TOKEN=excw_pat_… \
+  -- npx -y @excaliwow/mcp
+```
+
+### Claude Desktop (and other JSON-config clients)
+
+Add it to your client's config file (e.g. Claude Desktop's
 `claude_desktop_config.json`, or your client's MCP settings — see your client's
 MCP setup docs). **Pin the version** — `npx -y` otherwise always pulls the newest
 release, which is an avoidable supply-chain surface for a process that holds a
@@ -18,7 +37,7 @@ token to your account:
   "mcpServers": {
     "excaliwow": {
       "command": "npx",
-      "args": ["-y", "@excaliwow/mcp@0.1.1"],
+      "args": ["-y", "@excaliwow/mcp@0.3.0"],
       "env": {
         "EXCALIWOW_TOKEN": "excw_pat_…"
       }
@@ -27,30 +46,80 @@ token to your account:
 }
 ```
 
-`EXCALIWOW_TOKEN` is a Personal Access Token created at
-https://excaliwow.com/app/settings (Settings → Developer / API tokens). The
-server reads it per call from the environment (or, if you also use
-`@excaliwow/cli` and have run `excaliwow auth login`, that stored login) and never
-writes the token to disk itself. For a standalone MCP install, set
-`EXCALIWOW_TOKEN` as shown. Bump the pinned version deliberately when you've
-reviewed a new release.
+The server reads `EXCALIWOW_TOKEN` per call from the environment (or, if you also
+use `@excaliwow/cli` and have run `excaliwow auth login`, that stored login) and
+never writes the token to disk itself. Bump the pinned version deliberately when
+you've reviewed a new release.
+
+## Troubleshooting
+
+**`npx -y @excaliwow/mcp@0.3.0` fails with `ENOENT … /@excaliwow/mcp@0.3.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
+use the unversioned spec `npx -y @excaliwow/mcp` (as the Claude Code command
+above does), or pin safely by installing once and pointing the client at the
+binary:
+
+```sh
+npm i -g @excaliwow/mcp@0.3.0
+```
+
+```json
+{
+  "mcpServers": {
+    "excaliwow": {
+      "command": "excaliwow-mcp",
+      "env": { "EXCALIWOW_TOKEN": "excw_pat_…" }
+    }
+  }
+}
+```
+
+With Claude Code: `claude mcp add excaliwow --scope local --env EXCALIWOW_TOKEN=… -- excaliwow-mcp`.
+
+**"Not authenticated" / 401 / the agent's tool calls fail.** The server starts
+even without a token (so it can list its tools), so a missing or invalid
+`EXCALIWOW_TOKEN` only surfaces when the agent first calls a tool. Starting with
+no token prints a one-line `EXCALIWOW_TOKEN is not set` warning to **stderr**. To
+check a token directly, run the health probe — it makes one authenticated read
+and prints a clear verdict (`ok`, `401 — token is invalid or expired`, or
+unreachable):
+
+```sh
+npx -y @excaliwow/mcp --health
+```
+
+### CLI flags
+
+| Flag        | Effect                                                             |
+| ----------- | ------------------------------------------------------------------ |
+| `--health`  | Check the token + API reachability, then exit (0 ok, 1 bad token). |
+| `--version` | Print the installed version and exit.                              |
+| `--help`    | Print usage (flags + env vars) and exit.                           |
 
 ## Tools
 
-Five tools, scoped to safe agent use:
+Seven tools, scoped to safe agent use:
 
-| Tool               | What it does                                                                |
-| ------------------ | --------------------------------------------------------------------------- |
-| `generate_diagram` | Create a diagram from the high-level node/edge DSL; returns the editor URL. |
-| `read_diagram`     | Compact summary (title + per-type element counts) **plus** a rendered PNG.  |
-| `list_diagrams`    | Page through your diagrams.                                                 |
-| `move_diagram`     | Move a diagram to a folder (or to root).                                    |
-| `edit_diagram`     | 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). |
+| `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
 
@@ -67,14 +136,24 @@ resource at **`excaliwow://dsl/reference`**.
 
 ## Security notes
 
-- **Pin the version** in your client config (above) rather than floating on
-  `@latest`, and review release notes before bumping.
+- **Keep the token out of anything you commit.** A project-scoped config that
+  lives in the repo (a committed `.mcp.json`, or `claude mcp add --scope
+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).**
+  Five of the seven 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
   config / environment; this server does not persist it. Treat that config the
   way you'd treat any secrets file.
-- The token authorizes the same operations as a `read-write` PAT used by the
-  REST API and CLI — there is no separate per-capability scope, so treat it as
-  full read-write access to your account.
 
 ## License
 

package/dist/bin.js

@@ -3,10 +3,6 @@
 // src/bin.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
-// src/server.ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z as z2 } from "zod";
-
 // ../core/src/config.ts
 import { chmodSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "fs";
 import { homedir } from "os";
@@ -209,6 +205,28 @@ 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
+  });
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z as z2 } from "zod";
 
 // src/bootstrap.ts
 var DSL_BOOTSTRAP_EXAMPLE = {
@@ -426,6 +444,9 @@ var EditFragmentZ = z.object({
   updateNodes: z.array(UpdateNodePatchZ).optional()
 });
 
+// src/version.ts
+var VERSION = "0.3.0";
+
 // src/server.ts
 function textResult(text) {
   return { content: [{ type: "text", text }] };
@@ -467,7 +488,7 @@ function elementBreakdown(detail) {
   return { total: elements.length, byType };
 }
 function createServer(deps) {
-  const server2 = new McpServer({ name: "excaliwow", version: "0.1.1" });
+  const server2 = new McpServer({ name: "excaliwow", version: VERSION });
   server2.registerTool(
     "generate_diagram",
     {
@@ -622,6 +643,40 @@ 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.registerResource(
     "dsl-reference",
     DSL_REFERENCE_URI,
@@ -640,5 +695,83 @@ preview fidelity: ${png.quality} \u2014 faithful renderer unavailable; layout/fo
 }
 
 // src/bin.ts
+var argv = process.argv.slice(2);
+var has = (...flags) => argv.some((a) => flags.includes(a));
+if (has("--version", "-v")) {
+  process.stdout.write(`${VERSION}
+`);
+  process.exit(0);
+}
+if (has("--help", "-h")) {
+  process.stdout.write(
+    [
+      `excaliwow-mcp ${VERSION} \u2014 Excaliwow Model Context Protocol server (stdio).`,
+      "",
+      "An MCP client (Claude Desktop, Claude Code, \u2026) launches this on demand; you",
+      "do not normally run it by hand. The flags below are for setup/debugging.",
+      "",
+      "Usage:",
+      "  excaliwow-mcp            Start the MCP server on stdio (what a client runs).",
+      "  excaliwow-mcp --health   Check the token + API reachability, then exit.",
+      "  excaliwow-mcp --version  Print the version and exit.",
+      "  excaliwow-mcp --help     Print this help and exit.",
+      "",
+      "Environment:",
+      "  EXCALIWOW_TOKEN    Personal Access Token with read + write. Required.",
+      "                     Mint one at https://excaliwow.com/app/settings.",
+      "  EXCALIWOW_API_URL  API origin. Defaults to https://excaliwow.com.",
+      ""
+    ].join("\n")
+  );
+  process.exit(0);
+}
+if (has("--health")) {
+  process.exit(await health());
+}
+if (!resolveToken()) {
+  process.stderr.write(
+    "[excaliwow-mcp] warning: EXCALIWOW_TOKEN is not set (and no `excaliwow auth login` config was found). The server will start, but every tool call will fail with an auth error until you set a Personal Access Token. See https://excaliwow.com/docs/mcp\n"
+  );
+}
 var server = createServer();
 await server.connect(new StdioServerTransport());
+async function health() {
+  const token = resolveToken();
+  const baseUrl = resolveBaseUrl({});
+  if (!token) {
+    process.stderr.write(
+      "[excaliwow-mcp] health: EXCALIWOW_TOKEN is not set \u2014 no token to check.\n"
+    );
+    return 1;
+  }
+  try {
+    await listDiagrams({ token, baseUrl }, { limit: 1 });
+    process.stderr.write(`[excaliwow-mcp] health: ok \u2014 token authenticates against ${baseUrl}.
+`);
+    return 0;
+  } catch (err) {
+    if (err instanceof ApiError && err.status === 401) {
+      process.stderr.write(
+        `[excaliwow-mcp] health: 401 \u2014 token is invalid or expired (${baseUrl}).
+`
+      );
+      return 1;
+    }
+    if (err instanceof ApiError && err.status === 403) {
+      process.stderr.write(
+        `[excaliwow-mcp] health: token authenticates against ${baseUrl}, but lacks the \`read\` capability. Mint a token with read + write.
+`
+      );
+      return 0;
+    }
+    if (err instanceof NotAuthenticatedError) {
+      process.stderr.write(`[excaliwow-mcp] health: ${err.message}
+`);
+      return 1;
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[excaliwow-mcp] health: could not reach ${baseUrl} \u2014 ${msg}
+`);
+    return 2;
+  }
+}

package/package.json

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