@excaliwow/mcp 0.1.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,4 @@
+Excaliwow MCP server (@excaliwow/mcp)
+Copyright 2026 Excaliwow
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).

package/README.md

@@ -0,0 +1,81 @@
+# @excaliwow/mcp
+
+The Excaliwow **Model Context Protocol** server — lets an AI agent create, read,
+render, manage, and edit diagrams in your Excaliwow account through the same
+public REST API (`/api/v1`) the CLI uses. It runs over **stdio**, so any MCP
+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
+`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
+token to your account:
+
+```json
+{
+  "mcpServers": {
+    "excaliwow": {
+      "command": "npx",
+      "args": ["-y", "@excaliwow/mcp@0.1.1"],
+      "env": {
+        "EXCALIWOW_TOKEN": "excw_pat_…"
+      }
+    }
+  }
+}
+```
+
+`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.
+
+## 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). |
+
+`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.
+
+### DSL discovery
+
+The diagram DSL grammar + a worked example are embedded in the
+`generate_diagram` tool description, and the full reference is served as an MCP
+resource at **`excaliwow://dsl/reference`**.
+
+## Environment variables
+
+| Var                 | Effect                                                                                      |
+| ------------------- | ------------------------------------------------------------------------------------------- |
+| `EXCALIWOW_TOKEN`   | **Required** (standalone). Bearer PAT; read per call, never written to disk by this server. |
+| `EXCALIWOW_API_URL` | API origin. Default `https://excaliwow.com`; normally leave unset.                          |
+
+## Security notes
+
+- **Pin the version** in your client config (above) 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
+
+Apache-2.0 — see [LICENSE](./LICENSE) and [NOTICE](./NOTICE).

package/dist/bin.js

@@ -0,0 +1,635 @@
+#!/usr/bin/env node
+
+// 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";
+import { join } from "path";
+var DEFAULT_BASE_URL = "https://excaliwow.com";
+function configDir() {
+  const base = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+  return join(base, "excaliwow");
+}
+function configFile() {
+  return join(configDir(), "config.json");
+}
+function readConfig() {
+  const file = configFile();
+  let raw;
+  try {
+    statSync(file);
+    raw = readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.token === "string") return parsed;
+    return null;
+  } catch {
+    return null;
+  }
+}
+function resolveToken() {
+  const fromEnv = process.env.EXCALIWOW_TOKEN;
+  if (fromEnv !== void 0 && fromEnv !== "") return fromEnv;
+  return readConfig()?.token;
+}
+function resolveBaseUrl(opts) {
+  const raw = opts?.apiUrl ?? process.env.EXCALIWOW_API_URL ?? DEFAULT_BASE_URL;
+  return String(raw).replace(/\/+$/, "");
+}
+
+// ../core/src/errors.ts
+var ApiError = class extends Error {
+  code;
+  status;
+  requestId;
+  /** Seconds, from the `Retry-After` header on a 429. */
+  retryAfter;
+  constructor(args) {
+    super(args.message ?? args.code);
+    this.name = "ApiError";
+    this.code = args.code;
+    this.status = args.status;
+    if (args.requestId !== void 0) this.requestId = args.requestId;
+    if (args.retryAfter !== void 0) this.retryAfter = args.retryAfter;
+  }
+};
+var NotAuthenticatedError = class extends Error {
+  /** Stable machine code so the `--json` error envelope reads `not_authenticated`. */
+  code = "not_authenticated";
+  constructor(message = "Not authenticated. Run `excaliwow auth login` first \u2014 create a token at https://excaliwow.com/app/settings.") {
+    super(message);
+    this.name = "NotAuthenticatedError";
+  }
+};
+
+// ../core/src/http.ts
+function buildUrl(baseUrl, path, query) {
+  const url = new URL(path, `${baseUrl}/`);
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value === void 0) continue;
+      url.searchParams.set(key, String(value));
+    }
+  }
+  return url.toString();
+}
+async function request(opts) {
+  const doFetch = opts.fetchImpl ?? globalThis.fetch;
+  const headers = {
+    authorization: `Bearer ${opts.token}`,
+    accept: opts.accept ?? "application/json"
+  };
+  let body;
+  if (opts.body !== void 0) {
+    body = JSON.stringify(opts.body);
+    headers["content-type"] = "application/json";
+  }
+  const url = buildUrl(opts.baseUrl, opts.path, opts.query);
+  const res = await doFetch(url, { method: opts.method, headers, body });
+  const contentType = res.headers.get("content-type") ?? "";
+  if (res.ok) {
+    if (res.status === 204) return null;
+    if (contentType.includes("image/")) {
+      const buf = new Uint8Array(await res.arrayBuffer());
+      return { bytes: buf, contentType };
+    }
+    const text = await res.text();
+    if (text === "") return null;
+    return JSON.parse(text);
+  }
+  let code = `http_${res.status}`;
+  let message;
+  try {
+    const text = await res.text();
+    if (text !== "") {
+      const parsed = JSON.parse(text);
+      if (parsed && typeof parsed.error === "string") code = parsed.error;
+      if (parsed && typeof parsed.message === "string") message = parsed.message;
+    }
+  } catch {
+  }
+  const requestId = res.headers.get("x-request-id") ?? void 0;
+  let retryAfter;
+  if (res.status === 429) {
+    const raw = res.headers.get("retry-after");
+    if (raw !== null) {
+      const n = Number.parseInt(raw, 10);
+      if (Number.isFinite(n)) retryAfter = n;
+    }
+  }
+  throw new ApiError({ code, status: res.status, message, requestId, retryAfter });
+}
+
+// ../core/src/api.ts
+var PREFIX = "/api/v1";
+function listDiagrams(ctx, opts) {
+  return request({
+    method: "GET",
+    path: `${PREFIX}/diagrams`,
+    token: ctx.token,
+    baseUrl: ctx.baseUrl,
+    query: { filter: opts?.filter, cursor: opts?.cursor, limit: opts?.limit },
+    fetchImpl: ctx.fetchImpl
+  });
+}
+async function createDiagram(ctx, args) {
+  const hasSpec = args.spec != null;
+  const hasScene = args.scene != null;
+  if (hasSpec === hasScene) {
+    throw new Error("createDiagram requires exactly one of `spec` or `scene`.");
+  }
+  const body = {};
+  if (args.title !== void 0) body.title = args.title;
+  if (args.folderId !== void 0) body.folderId = args.folderId;
+  if (hasSpec) body.spec = args.spec;
+  if (hasScene) body.scene = args.scene;
+  return request({
+    method: "POST",
+    path: `${PREFIX}/diagrams`,
+    token: ctx.token,
+    baseUrl: ctx.baseUrl,
+    body,
+    fetchImpl: ctx.fetchImpl
+  });
+}
+function getDiagram(ctx, id) {
+  return request({
+    method: "GET",
+    path: `${PREFIX}/diagrams/${encodeURIComponent(id)}`,
+    token: ctx.token,
+    baseUrl: ctx.baseUrl,
+    fetchImpl: ctx.fetchImpl
+  });
+}
+function renderDiagram(ctx, id, opts) {
+  const accept = opts.format === "png" ? "image/png" : opts.format === "svg" ? "image/svg+xml" : "application/json";
+  return request({
+    method: "GET",
+    path: `${PREFIX}/diagrams/${encodeURIComponent(id)}/render`,
+    token: ctx.token,
+    baseUrl: ctx.baseUrl,
+    query: { format: opts.format },
+    accept,
+    fetchImpl: ctx.fetchImpl
+  });
+}
+function editDiagram(ctx, id, fragment) {
+  return request({
+    method: "POST",
+    path: `${PREFIX}/diagrams/${encodeURIComponent(id)}/edit`,
+    token: ctx.token,
+    baseUrl: ctx.baseUrl,
+    body: fragment,
+    fetchImpl: ctx.fetchImpl
+  });
+}
+function moveDiagram(ctx, id, folderId) {
+  return request({
+    method: "PATCH",
+    path: `${PREFIX}/diagrams/${encodeURIComponent(id)}`,
+    token: ctx.token,
+    baseUrl: ctx.baseUrl,
+    body: { folderId },
+    fetchImpl: ctx.fetchImpl
+  });
+}
+
+// src/bootstrap.ts
+var DSL_BOOTSTRAP_EXAMPLE = {
+  version: "1",
+  nodes: [
+    { id: "client", label: "Client", shape: "rectangle" },
+    { id: "api", label: "API Server", shape: "rectangle" },
+    { id: "db", label: "Database", shape: "diamond" },
+    { id: "cache", label: "Cache", shape: "ellipse" }
+  ],
+  edges: [
+    { from: "client", to: "api", label: "request" },
+    { from: "api", to: "db" },
+    { from: "api", to: "cache" }
+  ],
+  layout: { direction: "TB" }
+};
+var COMPACT_GRAMMAR = `DiagramSpec (auto-laid-out node/edge DSL):
+{
+  "version": "1",                       // optional; only "1" is accepted
+  "nodes": [                            // required
+    { "id": "unique",                   // required; must be unique
+      "label": "Text",                  // optional; defaults to id, "" suppresses
+      "shape": "rectangle",             // rectangle | ellipse | diamond | text (default rectangle)
+      "width": 140, "height": 60,       // optional; treated as a minimum
+      "strokeColor": "#1e1e1e",         // optional
+      "backgroundColor": "transparent", // optional
+      "fillStyle": "solid" }            // hachure | cross-hatch | solid | zigzag
+  ],
+  "edges": [                            // optional
+    { "from": "id", "to": "id",         // both must name existing node ids
+      "label": "Text",                  // optional
+      "arrowhead": "arrow" },           // arrow | triangle | null
+    "from -> to",                       // shorthand string form, or
+    "from -> to: label"                 // shorthand with a label
+  ],
+  "layout": { "direction": "TB" }       // TB | BT | LR | RL; optional nodeSep / rankSep
+}
+Caps: <=1000 nodes, <=2000 edges, label <=2000 chars, <=5000 total scene elements.`;
+
+// src/reference.ts
+var DSL_REFERENCE_URI = "excaliwow://dsl/reference";
+var DSL_REFERENCE_MARKDOWN = `# Excaliwow DSL reference
+
+The Excaliwow content model has two representations. The MCP tools use the
+high-level **DiagramSpec** (node/edge DSL, auto-laid-out) for \`generate_diagram\`
+and the **EditFragment** for \`edit_diagram\`.
+
+## DiagramSpec
+
+\`\`\`json
+{
+  "version": "1",
+  "nodes": [ /* required, >=1 */ ],
+  "edges": [ /* optional */ ],
+  "layout": { "direction": "TB" }
+}
+\`\`\`
+
+- \`version\` \u2014 optional. Only \`"1"\` is accepted; anything else \u2192 \`UNSUPPORTED_VERSION\`.
+- \`nodes\` \u2014 required array.
+- \`edges\` \u2014 optional array (object form or shorthand string).
+- \`layout\` \u2014 optional.
+
+### Nodes
+
+\`\`\`json
+{
+  "id": "client",
+  "label": "Client",
+  "shape": "rectangle",
+  "width": 140,
+  "height": 60,
+  "strokeColor": "#1e1e1e",
+  "backgroundColor": "transparent",
+  "fillStyle": "solid"
+}
+\`\`\`
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| \`id\` | string | **Required, unique.** Avoid \`-label\` suffixes and \`__\` infixes \u2014 they collide with generated label/arrow ids (\`ID_COLLISION\`). |
+| \`label\` | string? | Defaults to \`id\`. \`""\` suppresses the label entirely. |
+| \`shape\` | enum? | \`rectangle\` \\| \`ellipse\` \\| \`diamond\` \\| \`text\`. Defaults to \`rectangle\`. |
+| \`width\` / \`height\` | number? | Positive. Treated as a **minimum** \u2014 a shape grows to fit its label. |
+| \`strokeColor\` | string? | Any CSS color. |
+| \`backgroundColor\` | string? | Any CSS color, or \`transparent\`. |
+| \`fillStyle\` | enum? | \`hachure\` \\| \`cross-hatch\` \\| \`solid\` \\| \`zigzag\`. |
+
+Default sizes: rectangle 140x60, ellipse 140x80, diamond 160x90. A \`text\` node IS its text.
+
+### Edges
+
+Object form:
+
+\`\`\`json
+{ "from": "client", "to": "api", "label": "request", "arrowhead": "arrow" }
+\`\`\`
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| \`from\` / \`to\` | string | **Required.** Each must name an existing node \`id\` \u2192 else \`DANGLING_EDGE\`. |
+| \`label\` | string? | Optional edge label. |
+| \`arrowhead\` | enum? | \`arrow\` \\| \`triangle\` \\| \`null\`. Defaults to \`arrow\`. |
+
+Shorthand string form (DiagramSpec only \u2014 NOT in EditFragment.addEdges):
+
+\`\`\`
+"client -> api"
+"client -> api: request"
+\`\`\`
+
+Everything after the first colon is the label. Missing/empty endpoint or no single
+\`->\` \u2192 \`MALFORMED_SHORTHAND\`.
+
+### Layout
+
+\`\`\`json
+{ "direction": "TB", "nodeSep": 50, "rankSep": 80 }
+\`\`\`
+
+- \`direction\` \u2014 \`TB\` \\| \`BT\` \\| \`LR\` \\| \`RL\`. Defaults to \`TB\`.
+- \`nodeSep\` / \`rankSep\` \u2014 optional positive numbers (defaults 50 / 80).
+
+## EditFragment (edit_diagram)
+
+\`edit_diagram\` additively MERGES a fragment into an existing diagram. Existing
+elements are **never moved, resized, or deleted** \u2014 the edit is additive plus a
+narrow non-reflow node-update allowlist.
+
+\`\`\`json
+{
+  "addNodes":    [ /* NodeSpec + optional absolute x/y */ ],
+  "addEdges":    [ /* EdgeObject \u2014 object form only, NO shorthand */ ],
+  "updateNodes": [ /* { id } + non-reflow allowlist only */ ]
+}
+\`\`\`
+
+- \`addNodes\` \u2014 new node ids (must not collide with ANY existing element id \u2192
+  \`ID_COLLISION\`). Optional explicit \`x\`/\`y\` (both or neither); else auto-placed
+  below the existing bbox.
+- \`addEdges\` \u2014 object form only. \`from\`/\`to\` resolve against existing \u222A added
+  node ids \u2192 else \`DANGLING_EDGE\`.
+- \`updateNodes\` \u2014 patch EXISTING nodes. **NON-REFLOW ALLOWLIST ONLY**:
+  \`strokeColor\`, \`backgroundColor\`, \`fillStyle\`, \`label\` (plus the required
+  \`id\`). ANY other field \u2014 \`x\`, \`y\`, \`width\`, \`height\`, \`shape\`, \u2026 \u2014 is
+  rejected with \`INVALID_SPEC\` (these can't alter geometry, so an
+  already-placed node never starts overlapping a neighbor).
+
+## Caps
+
+| Limit | Value |
+| --- | --- |
+| nodes | 1000 |
+| edges | 2000 |
+| label length | 2000 chars |
+| total scene elements | 5000 |
+
+## Error codes (selected)
+
+\`INVALID_SPEC\`, \`UNSUPPORTED_VERSION\`, \`MISSING_NODE_ID\`, \`DUPLICATE_NODE_ID\`,
+\`UNKNOWN_SHAPE\`, \`DANGLING_EDGE\`, \`MALFORMED_SHORTHAND\`, \`MALFORMED_EDGE\`,
+\`ID_COLLISION\`, \`SPEC_TOO_LARGE\`, \`SCENE_TOO_LARGE\`, \`PROTO_KEY\`. Each tool
+surfaces these verbatim as a clean error result (\`code: message\`).
+`;
+
+// src/schemas.ts
+import { z } from "zod";
+var NodeShapeZ = z.enum(["rectangle", "ellipse", "diamond", "text"]);
+var FillStyleZ = z.enum(["hachure", "cross-hatch", "solid", "zigzag"]);
+var LayoutDirectionZ = z.enum(["TB", "BT", "LR", "RL"]);
+var EdgeArrowheadZ = z.union([z.enum(["arrow", "triangle"]), z.null()]);
+var NodeSpecZ = z.object({
+  id: z.string(),
+  label: z.string().optional(),
+  shape: NodeShapeZ.optional(),
+  width: z.number().optional(),
+  height: z.number().optional(),
+  strokeColor: z.string().optional(),
+  backgroundColor: z.string().optional(),
+  fillStyle: FillStyleZ.optional()
+});
+var EdgeObjectZ = z.object({
+  from: z.string(),
+  to: z.string(),
+  label: z.string().optional(),
+  arrowhead: EdgeArrowheadZ.optional()
+});
+var EdgeSpecZ = z.union([EdgeObjectZ, z.string()]);
+var LayoutOptionsZ = z.object({
+  direction: LayoutDirectionZ.optional(),
+  nodeSep: z.number().optional(),
+  rankSep: z.number().optional()
+});
+var DiagramSpecZ = z.object({
+  version: z.literal("1").optional(),
+  nodes: z.array(NodeSpecZ),
+  edges: z.array(EdgeSpecZ).optional(),
+  layout: LayoutOptionsZ.optional()
+});
+var AddNodeSpecZ = NodeSpecZ.extend({
+  x: z.number().optional(),
+  y: z.number().optional()
+});
+var UpdateNodePatchZ = z.object({
+  id: z.string(),
+  strokeColor: z.string().optional(),
+  backgroundColor: z.string().optional(),
+  fillStyle: FillStyleZ.optional(),
+  label: z.string().optional()
+}).strict();
+var EditFragmentZ = z.object({
+  addNodes: z.array(AddNodeSpecZ).optional(),
+  addEdges: z.array(EdgeObjectZ).optional(),
+  updateNodes: z.array(UpdateNodePatchZ).optional()
+});
+
+// src/server.ts
+function textResult(text) {
+  return { content: [{ type: "text", text }] };
+}
+function errorResult(text) {
+  return { isError: true, content: [{ type: "text", text }] };
+}
+function toErrorResult(err) {
+  if (err instanceof ApiError) {
+    const base = err.message && err.message !== err.code ? `${err.code}: ${err.message}` : err.code;
+    return errorResult(err.requestId ? `${base} (request ${err.requestId})` : base);
+  }
+  if (err instanceof NotAuthenticatedError) {
+    return errorResult(err.message);
+  }
+  if (err instanceof Error) return errorResult(err.message);
+  return errorResult("unexpected error");
+}
+function buildCtx(deps) {
+  if (deps?.ctx) return deps.ctx();
+  const token = resolveToken();
+  if (!token) {
+    throw new NotAuthenticatedError(
+      "Not authenticated. Set EXCALIWOW_TOKEN to a Personal Access Token created at https://excaliwow.com/app/settings (or, if you use the CLI, run `excaliwow auth login`)."
+    );
+  }
+  return { token, baseUrl: resolveBaseUrl({}) };
+}
+function editorUrl(ctx, id) {
+  return `${ctx.baseUrl}/c/${id}`;
+}
+function elementBreakdown(detail) {
+  const byType = {};
+  const elements = Array.isArray(detail.scene?.elements) ? detail.scene.elements : [];
+  for (const el of elements) {
+    const t = el && typeof el === "object" && typeof el.type === "string" ? el.type : "unknown";
+    byType[t] = (byType[t] ?? 0) + 1;
+  }
+  return { total: elements.length, byType };
+}
+function createServer(deps) {
+  const server2 = new McpServer({ name: "excaliwow", version: "0.1.1" });
+  server2.registerTool(
+    "generate_diagram",
+    {
+      title: "Generate a diagram",
+      description: [
+        "Create a new Excalidraw diagram from a high-level node/edge DSL (DiagramSpec).",
+        "The spec is auto-laid-out server-side. Returns the diagram id, title, and editor url.",
+        "",
+        COMPACT_GRAMMAR,
+        "",
+        "Worked example (spec):",
+        JSON.stringify(DSL_BOOTSTRAP_EXAMPLE, null, 2),
+        "",
+        "See the `" + DSL_REFERENCE_URI + "` resource for the full DSL reference."
+      ].join("\n"),
+      inputSchema: {
+        title: z2.string(),
+        spec: DiagramSpecZ,
+        folderId: z2.string().nullish()
+      }
+    },
+    async ({ title, spec, folderId }) => {
+      try {
+        const ctx = buildCtx(deps);
+        const created = await createDiagram(ctx, {
+          title,
+          spec,
+          folderId: folderId ?? void 0
+        });
+        return textResult(
+          JSON.stringify({ id: created.id, title: created.title, url: editorUrl(ctx, created.id) })
+        );
+      } catch (err) {
+        return toErrorResult(err);
+      }
+    }
+  );
+  server2.registerTool(
+    "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() }
+    },
+    async ({ id }) => {
+      let detail;
+      try {
+        const ctx = buildCtx(deps);
+        detail = await getDiagram(ctx, id);
+        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})` : "");
+        try {
+          const png = await renderDiagram(ctx, id, { format: "png" });
+          if (png && png.bytes.length > 0) {
+            return {
+              content: [
+                { type: "text", text: summary },
+                {
+                  type: "image",
+                  data: Buffer.from(png.bytes).toString("base64"),
+                  mimeType: "image/png"
+                }
+              ]
+            };
+          }
+          return textResult(`${summary}
+(no preview: the diagram renders empty)`);
+        } catch {
+          return textResult(`${summary}
+(no preview: render failed)`);
+        }
+      } catch (err) {
+        return toErrorResult(err);
+      }
+    }
+  );
+  server2.registerTool(
+    "list_diagrams",
+    {
+      title: "List diagrams",
+      description: "List the caller's owned diagrams (keyset-paginated). Returns items with id, title, folderId, and updatedAt, plus a nextCursor for the following page.",
+      inputSchema: {
+        cursor: z2.string().optional(),
+        limit: z2.number().int().optional(),
+        filter: z2.enum(["active", "trash"]).optional()
+      }
+    },
+    async ({ cursor, limit, filter }) => {
+      try {
+        const ctx = buildCtx(deps);
+        const page = await listDiagrams(ctx, { cursor, limit, filter });
+        const items = page.items.map((d) => ({
+          id: d.id,
+          title: d.title,
+          folderId: d.folderId,
+          updatedAt: d.updatedAt
+        }));
+        return textResult(JSON.stringify({ items, nextCursor: page.nextCursor }, null, 2));
+      } catch (err) {
+        return toErrorResult(err);
+      }
+    }
+  );
+  server2.registerTool(
+    "move_diagram",
+    {
+      title: "Move a diagram",
+      description: "Move a diagram into a folder, or to the root with folderId=null. Returns the diagram id and its new folderId.",
+      inputSchema: {
+        id: z2.string(),
+        folderId: z2.string().nullable()
+      }
+    },
+    async ({ id, folderId }) => {
+      try {
+        const ctx = buildCtx(deps);
+        const moved = await moveDiagram(ctx, id, folderId);
+        return textResult(JSON.stringify({ id: moved.id, folderId: moved.folderId }));
+      } catch (err) {
+        return toErrorResult(err);
+      }
+    }
+  );
+  server2.registerTool(
+    "edit_diagram",
+    {
+      title: "Edit a diagram (additive merge)",
+      description: "Additively merge an edit fragment into an existing diagram. Existing elements are never moved, resized, or deleted. addNodes/addEdges append; updateNodes patches only the non-reflow allowlist (strokeColor, backgroundColor, fillStyle, label). Returns the added/updated ids and merged count. A subsequent read_diagram reflects the change immediately.",
+      inputSchema: {
+        id: z2.string(),
+        addNodes: EditFragmentZ.shape.addNodes,
+        addEdges: EditFragmentZ.shape.addEdges,
+        updateNodes: EditFragmentZ.shape.updateNodes
+      }
+    },
+    async ({ id, addNodes, addEdges, updateNodes }) => {
+      try {
+        const ctx = buildCtx(deps);
+        const result = await editDiagram(ctx, id, { addNodes, addEdges, updateNodes });
+        return textResult(
+          JSON.stringify({
+            added: result.added,
+            updated: result.updated,
+            merged: result.merged
+          })
+        );
+      } catch (err) {
+        return toErrorResult(err);
+      }
+    }
+  );
+  server2.registerResource(
+    "dsl-reference",
+    DSL_REFERENCE_URI,
+    {
+      title: "Excaliwow DSL reference",
+      description: "The full Excaliwow diagram DSL grammar: nodes, shapes, edges (object + shorthand), layout, caps, the EditFragment, and the updateNodes non-reflow allowlist.",
+      mimeType: "text/markdown"
+    },
+    () => ({
+      contents: [
+        { uri: DSL_REFERENCE_URI, mimeType: "text/markdown", text: DSL_REFERENCE_MARKDOWN }
+      ]
+    })
+  );
+  return server2;
+}
+
+// src/bin.ts
+var server = createServer();
+await server.connect(new StdioServerTransport());

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@excaliwow/mcp",
+  "version": "0.1.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": {
+    "access": "public"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Excaliwow",
+    "url": "https://excaliwow.com"
+  },
+  "homepage": "https://excaliwow.com",
+  "keywords": [
+    "excalidraw",
+    "diagrams",
+    "mcp",
+    "model-context-protocol",
+    "excaliwow",
+    "ai",
+    "agents"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.11.0"
+  },
+  "bin": {
+    "excaliwow-mcp": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.9.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.9",
+    "@excaliwow/core": "0.0.0",
+    "@excaliwow/db": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest --run",
+    "dev": "tsup --watch"
+  }
+}