@excaliwow/mcp 0.1.1 → 0.2.1

package/README.md

@@ -7,7 +7,25 @@ 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 — that
+is everything the server's tools need (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 +36,7 @@ token to your account:
   "mcpServers": {
     "excaliwow": {
       "command": "npx",
-      "args": ["-y", "@excaliwow/mcp@0.1.1"],
+      "args": ["-y", "@excaliwow/mcp@0.2.1"],
       "env": {
         "EXCALIWOW_TOKEN": "excw_pat_…"
       }
@@ -27,25 +45,69 @@ 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.2.1` fails with `ENOENT … /@excaliwow/mcp@0.2.1/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.2.1
+```
+
+```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:
 
-| 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.                                                 |
+| `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). |
 
 `read_diagram` returns a summary + image, **never** the raw scene JSON, to keep
 context small. Making a diagram publicly shareable is deliberately **not** an
@@ -67,14 +129,21 @@ 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 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`.
+- **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";
@@ -100,7 +96,12 @@ async function request(opts) {
     if (res.status === 204) return null;
     if (contentType.includes("image/")) {
       const buf = new Uint8Array(await res.arrayBuffer());
-      return { bytes: buf, contentType };
+      return {
+        bytes: buf,
+        contentType,
+        quality: res.headers.get("x-render-quality") ?? void 0,
+        note: res.headers.get("x-render-note") ?? void 0
+      };
     }
     const text = await res.text();
     if (text === "") return null;
@@ -177,7 +178,9 @@ function renderDiagram(ctx, id, opts) {
     path: `${PREFIX}/diagrams/${encodeURIComponent(id)}/render`,
     token: ctx.token,
     baseUrl: ctx.baseUrl,
-    query: { format: opts.format },
+    // `quality` (#220) — omitted ⇒ the server default (faithful). An older
+    // server ignores it and serves fast; the response's quality signal tells.
+    query: { format: opts.format, quality: opts.quality },
     accept,
     fetchImpl: ctx.fetchImpl
   });
@@ -203,6 +206,10 @@ function moveDiagram(ctx, id, folderId) {
   });
 }
 
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z as z2 } from "zod";
+
 // src/bootstrap.ts
 var DSL_BOOTSTRAP_EXAMPLE = {
   version: "1",
@@ -419,6 +426,9 @@ var EditFragmentZ = z.object({
   updateNodes: z.array(UpdateNodePatchZ).optional()
 });
 
+// src/version.ts
+var VERSION = "0.2.1";
+
 // src/server.ts
 function textResult(text) {
   return { content: [{ type: "text", text }] };
@@ -460,7 +470,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",
     {
@@ -516,9 +526,11 @@ function createServer(deps) {
         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: summary },
+                { type: "text", text },
                 {
                   type: "image",
                   data: Buffer.from(png.bytes).toString("base64"),
@@ -631,5 +643,83 @@ function createServer(deps) {
 }
 
 // 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.1.1",
+  "version": "0.2.1",
   "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": {