@drawpro/mcp 0.2.1 → 0.4.0

package/README.md

@@ -76,6 +76,7 @@ passcode itself.
 | `create_diagram` | no | returns a link to the new sheet |
 | `update_diagram` | no | replaces the sheet wholesale — regenerates layout |
 | `edit_sheet_text` | yes | rewrites named text in place, preserving every other element |
+| `import_sheet` | no | writes a local .excalidraw file into a sheet, coordinates verbatim |
 
 ### Editing a sheet a person drew
 
@@ -97,8 +98,16 @@ and nothing else moves — reflowing neighbours would be the wholesale rewrite
 this tool exists to avoid. Any box it grows is named in the result, so overlap
 with a neighbour is easy to spot and one drag to fix.
 
-It cannot add elements. A correction that needs a new box or a new annotation
-line is still a manual edit.
+It cannot add elements or move anything. A correction that needs a new box, a
+repositioned column, or a re-anchored arrow is a geometry change, and no spec or
+text edit can express one.
+
+`import_sheet` covers that case. Point it at a local `.excalidraw` file and it
+writes the scene in verbatim — every coordinate exactly as in the file. Because
+the server runs on your machine it can simply read the file, so a geometry pass
+can be done with a real editor, or by a model editing the file directly, and
+then pushed without a clipboard round trip. The file's contents go into the
+encrypted blob, never into the model's context.
 
 `update_diagram` remains the right tool for sheets this package generated, where
 regenerating the layout is the point.
@@ -112,6 +121,56 @@ Diagram specs describe *what connects to what*. Layout, sizing, text wrapping,
 and arrow binding are derived by `@drawpro/diagram` — a spec never contains
 coordinates.
 
+## Usage log
+
+Set `DRAWPRO_MCP_LOG` to record every tool call as JSONL:
+
+```bash
+claude mcp add drawpro --scope user \
+  -e DRAWPRO_TOKEN="dp_live_..." \
+  -e DRAWPRO_MCP_LOG="$HOME/.drawpro/usage.jsonl" \
+  -- npx -y @drawpro/mcp
+
+drawpro-mcp stats                 # or: npx -y @drawpro/mcp stats
+```
+
+```
+5 calls  2026-08-29 .. 2026-08-29
+
+  tool               calls  refused  failed  median
+  read_sheet             2     0   0%       0    881ms
+  edit_sheet_text        1     1 100%       0     62ms
+```
+
+Opt-in, and never transmitted. `logCall` does one thing — append to that file —
+and the only outbound request this package can make is to your own DrawPro
+account's sheets. Unset the variable and nothing is written at all; there is no
+default path and no fallback.
+
+### How that feeds back into the package
+
+The raw log stays on your machine and carries workspace and sheet ids, so you
+can correlate calls against your own account. `stats` is the aggregate: tool
+names, counts, timings, and nothing that identifies an account, a workspace, a
+sheet, or anything drawn on one.
+
+That split is the point. Sharing is a decision you make, not a default the
+package makes for you:
+
+```bash
+drawpro-mcp stats --json    # paste into an issue
+```
+
+There is no telemetry endpoint, and adding one to a product built on the server
+never seeing your diagrams would be the wrong trade. If a tool is refusing
+often, the aggregate says so without anyone learning what you were drawing.
+
+The column worth watching is **refused**. A tool that frequently declines is one
+whose description is not steering the model well, and that is cheaper to learn
+from real use than from a synthetic eval — both `edit_sheet_text` and
+`import_sheet` exist because real use found them missing, and no eval written
+beforehand would have predicted either.
+
 ## Tests
 
 ```bash

package/dist/server.js

@@ -24,6 +24,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/server.ts
+var import_node_fs3 = require("node:fs");
+var import_node_path3 = require("node:path");
 var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
 var import_zod = require("zod");
@@ -189,11 +191,13 @@ async function decryptSheet(encryptedData, privateKeyBytes) {
 
 // ../client/src/api.ts
 var DrawProClient = class {
-  constructor(baseUrl, token) {
+  constructor(baseUrl, token, onRequest) {
     this.baseUrl = baseUrl;
     this.token = token;
+    this.onRequest = onRequest;
   }
   async request(path, init) {
+    const started = Date.now();
     const res = await fetch(`${this.baseUrl}${path}`, {
       ...init,
       headers: {
@@ -202,7 +206,19 @@ var DrawProClient = class {
         ...init?.headers ?? {}
       }
     });
-    const body = await res.json().catch(() => ({}));
+    const raw = await res.text();
+    this.onRequest?.({
+      method: init?.method ?? "GET",
+      path: path.replace(/\/[a-z0-9]{20,}/gi, "/:id"),
+      status: res.status,
+      ms: Date.now() - started,
+      bytes: raw.length
+    });
+    let body = {};
+    try {
+      body = JSON.parse(raw);
+    } catch {
+    }
     if (!res.ok) {
       throw new Error(`${path} -> ${res.status} ${body.error ?? JSON.stringify(body)}`);
     }
@@ -338,7 +354,7 @@ function forgetKey(email) {
 
 // ../client/src/prompt.ts
 function askHidden(question) {
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     const input = process.stdin;
     process.stdout.write(question);
     if (!input.isTTY) {
@@ -347,7 +363,7 @@ function askHidden(question) {
       input.on("data", (chunk) => {
         buffered += chunk;
       });
-      input.on("end", () => resolve(buffered.split("\n")[0].trim()));
+      input.on("end", () => resolve2(buffered.split("\n")[0].trim()));
       return;
     }
     const wasRaw = input.isRaw;
@@ -363,7 +379,7 @@ function askHidden(question) {
       if (result === null) {
         process.exit(130);
       }
-      resolve(result);
+      resolve2(result);
     };
     const onData = (chunk) => {
       for (const ch of chunk) {
@@ -385,6 +401,35 @@ function askHidden(question) {
   });
 }
 
+// ../client/src/config.ts
+var import_node_fs2 = require("node:fs");
+var import_node_os2 = require("node:os");
+var import_node_path2 = require("node:path");
+var import_node_crypto3 = require("node:crypto");
+var DIR = (0, import_node_path2.join)((0, import_node_os2.homedir)(), ".drawpro");
+var FILE = (0, import_node_path2.join)(DIR, "config.json");
+function readConfig() {
+  try {
+    return JSON.parse((0, import_node_fs2.readFileSync)(FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function writeConfig(patch) {
+  const next = { ...readConfig(), ...patch };
+  (0, import_node_fs2.mkdirSync)(DIR, { recursive: true, mode: 448 });
+  (0, import_node_fs2.writeFileSync)(FILE, JSON.stringify(next, null, 2) + "\n", { mode: 384 });
+  return next;
+}
+function installId() {
+  const config = readConfig();
+  if (config.installId) return config.installId;
+  return writeConfig({ installId: (0, import_node_crypto3.randomUUID)() }).installId;
+}
+function telemetryEnabled() {
+  return readConfig().telemetry === "on";
+}
+
 // ../diagram/src/ids.ts
 var import_fractional_indexing = require("fractional-indexing");
 var ALPHABET = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-";
@@ -1356,10 +1401,13 @@ function api() {
         'DRAWPRO_TOKEN is not set. Create a token in DrawPro under "Connect to Claude Code", then:\n  claude mcp add drawpro --scope user -e DRAWPRO_TOKEN="dp_live_..." -- npx -y @drawpro/mcp'
       );
     }
-    clientInstance = new DrawProClient(BASE_URL, token);
+    clientInstance = new DrawProClient(BASE_URL, token, (t) => inFlight.push(t));
   }
   return clientInstance;
 }
+var SESSION_ID = Math.random().toString(36).slice(2, 10);
+var VERSION = "0.4.0";
+var inFlight = [];
 var cachedUser = null;
 async function currentUser() {
   if (!cachedUser) cachedUser = await api().me();
@@ -1384,8 +1432,83 @@ function text(body) {
 function sheetUrl(workspaceId, sheetId) {
   return `${APP_URL}/workspace/${workspaceId}/sheet/${sheetId}`;
 }
-var server = new import_mcp.McpServer({ name: "drawpro", version: "0.0.1" });
-server.tool(
+function logCall(entry) {
+  const path = process.env.DRAWPRO_MCP_LOG;
+  if (!path) return;
+  try {
+    (0, import_node_fs3.appendFileSync)(path, JSON.stringify({ ts: (/* @__PURE__ */ new Date()).toISOString(), ...entry }) + "\n");
+  } catch {
+  }
+}
+var REFUSALS = [
+  "Nothing was written",
+  "The diagram was not created",
+  "is locked",
+  "Could not read",
+  'has no "elements" array'
+];
+function summarise(args) {
+  const spec = args.spec;
+  const edits = args.edits;
+  return {
+    workspace_id: args.workspace_id,
+    sheet_id: args.sheet_id,
+    ...spec ? { nodes: spec.nodes?.length ?? 0, edges: spec.edges?.length ?? 0 } : {},
+    ...edits ? { edits: edits.length } : {},
+    ...args.file_path ? { from_file: true } : {}
+  };
+}
+function instrument(name, handler) {
+  return (async (args) => {
+    const started = Date.now();
+    inFlight = [];
+    try {
+      const result = await handler(args);
+      const body = result.content.map((c) => c.text).join("\n");
+      const apiMs = inFlight.reduce((sum, t) => sum + t.ms, 0);
+      const total = Date.now() - started;
+      logCall({
+        session: SESSION_ID,
+        tool: name,
+        ok: true,
+        refused: REFUSALS.some((r) => body.includes(r)),
+        ms: total,
+        api_ms: apiMs,
+        local_ms: total - apiMs,
+        requests: inFlight.map((t) => ({ m: t.method, p: t.path, s: t.status, ms: t.ms, bytes: t.bytes })),
+        args: summarise(args),
+        // Tools word this two ways: "38 elements" and "elements: 38".
+        elements: Number(body.match(/(\d+) elements/)?.[1] ?? body.match(/elements: (\d+)/)?.[1]) || void 0
+      });
+      return result;
+    } catch (err) {
+      const apiMs = inFlight.reduce((sum, t) => sum + t.ms, 0);
+      const total = Date.now() - started;
+      logCall({
+        session: SESSION_ID,
+        tool: name,
+        ok: false,
+        ms: total,
+        api_ms: apiMs,
+        local_ms: total - apiMs,
+        requests: inFlight.map((t) => ({ m: t.method, p: t.path, s: t.status, ms: t.ms, bytes: t.bytes })),
+        args: summarise(args),
+        error: err.message.slice(0, 200)
+      });
+      throw err;
+    }
+  });
+}
+var server = new import_mcp.McpServer({ name: "drawpro", version: VERSION });
+var tool = ((name, ...rest) => {
+  const handler = rest.pop();
+  return server.tool(
+    name,
+    ...rest,
+    instrument(name, handler)
+  );
+});
+tool(
   "list_workspaces",
   "List the DrawPro workspaces this account can access. Workspace names are encrypted at rest and are only readable once the account is unlocked.",
   {},
@@ -1404,7 +1527,7 @@ Names are encrypted. ${unlocked.error}` : "";
     return text(rows.join("\n") + note);
   }
 );
-server.tool(
+tool(
   "list_sheets",
   "List the sheets in a DrawPro workspace, with their decrypted names.",
   { workspace_id: import_zod.z.string().describe("Workspace id, from list_workspaces") },
@@ -1423,7 +1546,7 @@ Names are encrypted. ${unlocked.error}` : "";
     return text((rows.join("\n") || "(no sheets)") + note);
   }
 );
-server.tool(
+tool(
   "read_sheet",
   "Read what a DrawPro sheet contains: its shapes, and which arrows connect what. Returns a readable outline rather than raw Excalidraw JSON, which is mostly coordinates and style.",
   {
@@ -1468,7 +1591,7 @@ var specShape = {
     "What connects to what. Layout, sizing, text wrapping, and arrow binding are derived \u2014 never supply coordinates."
   )
 };
-server.tool(
+tool(
   "validate_spec",
   "Check a diagram spec without creating anything. Use this before writing if the diagram is large or the spec was assembled programmatically.",
   specShape,
@@ -1490,7 +1613,7 @@ function buildOrExplain(spec) {
   const warnings = issues.filter((i) => i.level === "warning");
   return { ok: true, scene, warnings: warnings.map((w) => w.message) };
 }
-server.tool(
+tool(
   "create_diagram",
   "Create a new sheet in DrawPro from a diagram spec. Returns a link to open it.",
   {
@@ -1517,7 +1640,7 @@ ${sheetUrl(workspace_id, sheet.id)}${warned}`
     );
   }
 );
-server.tool(
+tool(
   "update_diagram",
   "Replace a sheet\u2019s contents with a new diagram. This overwrites the whole sheet, so read_sheet first if you intend to preserve anything already there.",
   {
@@ -1576,7 +1699,7 @@ async function login(forget) {
   console.log(`Unlocked ${user.email}. Key stored in the ${location}.`);
   console.log("Claude can now read your sheets. The passcode was not stored or sent anywhere.");
 }
-server.tool(
+tool(
   "edit_sheet_text",
   "Correct the wording on an existing sheet without redrawing it. Use this for any sheet a person drew: update_diagram regenerates layout from a spec, so it discards hand-placed elements, region containers, and unbound annotations. This rewrites only the text you name and leaves every other element, and every coordinate, exactly as it was.",
   {
@@ -1638,16 +1761,214 @@ ${sheetUrl(workspace_id, sheet_id)}`
     );
   }
 );
+tool(
+  "import_sheet",
+  "Write a local .excalidraw file into a sheet, exactly as it is. Use this when geometry has to change \u2014 repositioning, resizing, re-anchoring arrows \u2014 which no spec can express and edit_sheet_text will not touch. Every coordinate in the file is preserved verbatim.",
+  {
+    workspace_id: import_zod.z.string(),
+    file_path: import_zod.z.string().describe("Path to a .excalidraw file on this machine"),
+    name: import_zod.z.string().describe("Sheet name"),
+    sheet_id: import_zod.z.string().optional().describe("Omit to create a new sheet; supply it to replace an existing one")
+  },
+  async ({ workspace_id, file_path, name, sheet_id }) => {
+    let parsed;
+    try {
+      parsed = JSON.parse((0, import_node_fs3.readFileSync)((0, import_node_path3.resolve)(file_path), "utf8"));
+    } catch (err) {
+      return text(`Could not read ${file_path}: ${err.message}`);
+    }
+    const elements = parsed.elements;
+    if (!Array.isArray(elements) || elements.length === 0) {
+      return text(`${file_path} has no "elements" array \u2014 is it an .excalidraw file?`);
+    }
+    const issues = validateScene(elements);
+    const noted = issues.length ? `
+
+${issues.length} thing(s) worth a look (imported anyway):
+` + issues.slice(0, 5).map((i) => `  ${i.level}: ${i.message}`).join("\n") : "";
+    const user = await currentUser();
+    const payload = {
+      name,
+      elements,
+      appState: parsed.appState ?? {}
+    };
+    const sheet = sheet_id ? await api().updateSheet(workspace_id, sheet_id, payload, user.publicKey) : await api().createSheet(workspace_id, payload, user.publicKey);
+    const id = sheet_id ?? sheet.id;
+    return text(
+      `${sheet_id ? "Replaced" : "Created"} "${name}" from ${file_path} \u2014 ${elements.length} elements, every coordinate as in the file.
+${sheetUrl(workspace_id, id)}${noted}`
+    );
+  }
+);
+var WRITE_TOOLS = ["create_diagram", "update_diagram", "edit_sheet_text", "import_sheet"];
+function summariseLog(file) {
+  let rows;
+  try {
+    rows = (0, import_node_fs3.readFileSync)(file, "utf8").split("\n").filter(Boolean).flatMap((line) => {
+      try {
+        return [JSON.parse(line)];
+      } catch {
+        return [];
+      }
+    });
+  } catch {
+    return null;
+  }
+  if (rows.length === 0) return null;
+  const byTool = /* @__PURE__ */ new Map();
+  for (const r of rows) {
+    const name = String(r.tool);
+    const acc = byTool.get(name) ?? { n: 0, refused: 0, failed: 0, ms: [] };
+    acc.n++;
+    if (r.refused) acc.refused++;
+    if (r.ok === false) acc.failed++;
+    if (typeof r.ms === "number") acc.ms.push(r.ms);
+    byTool.set(name, acc);
+  }
+  const median = (xs) => xs.length ? [...xs].sort((a, b) => a - b)[Math.floor(xs.length / 2)] : 0;
+  return {
+    calls: rows.length,
+    writes: rows.filter(
+      (r) => WRITE_TOOLS.includes(String(r.tool)) && !r.refused && r.ok !== false
+    ).length,
+    from: String(rows[0].ts).slice(0, 10),
+    to: String(rows[rows.length - 1].ts).slice(0, 10),
+    tools: [...byTool.entries()].sort((x, y) => y[1].n - x[1].n).map(([tool2, a]) => ({
+      tool: tool2,
+      calls: a.n,
+      refused: a.refused,
+      failed: a.failed,
+      median_ms: median(a.ms)
+    }))
+  };
+}
+function stats(path, asJson) {
+  const file = path ?? process.env.DRAWPRO_MCP_LOG;
+  if (!file) {
+    console.error("Set DRAWPRO_MCP_LOG, or pass a path: drawpro-mcp stats <file>");
+    process.exit(2);
+  }
+  const summary = summariseLog(file);
+  if (!summary) {
+    console.log(asJson ? '{"calls":0}' : "No calls recorded yet.");
+    return;
+  }
+  if (asJson) {
+    console.log(JSON.stringify({ version: VERSION, ...summary }, null, 2));
+    return;
+  }
+  console.log(`${summary.calls} calls  ${summary.from} .. ${summary.to}
+`);
+  console.log("  tool               calls  refused  failed  median");
+  for (const t of summary.tools) {
+    const pct = t.calls ? Math.round(t.refused / t.calls * 100) : 0;
+    console.log(
+      `  ${t.tool.padEnd(18)} ${String(t.calls).padStart(5)}  ${String(t.refused).padStart(4)} ${String(pct).padStart(3)}%  ${String(t.failed).padStart(6)}  ${String(t.median_ms).padStart(5)}ms`
+    );
+  }
+  console.log(`
+  ${summary.writes} successful writes to sheets`);
+  console.log(
+    "\n  No ids, account details, or diagram content above \u2014 safe to paste into a bug report."
+  );
+  console.log("  Add --json for a machine-readable copy.");
+}
+function buildReport() {
+  const file = process.env.DRAWPRO_MCP_LOG;
+  if (!file) return null;
+  const summary = summariseLog(file);
+  if (!summary) return null;
+  return {
+    installId: installId(),
+    mcpVersion: VERSION,
+    calls: summary.calls,
+    writes: summary.writes,
+    tools: summary.tools
+  };
+}
+async function sendReport(report) {
+  try {
+    const res = await fetch(`${BASE_URL}/telemetry`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(report)
+    });
+    return { ok: res.ok, detail: `HTTP ${res.status}` };
+  } catch (err) {
+    return { ok: false, detail: err.message };
+  }
+}
+async function telemetry(action) {
+  if (action === "off") {
+    writeConfig({ telemetry: "off" });
+    console.log("Telemetry off. Nothing will be sent.");
+    return;
+  }
+  const report = buildReport();
+  if (action === "on") {
+    writeConfig({ telemetry: "on" });
+    console.log("Telemetry on. Roughly once a day, this is sent:\n");
+    console.log(report ? JSON.stringify(report, null, 2) : "  (nothing yet \u2014 set DRAWPRO_MCP_LOG to record usage)");
+    console.log("\nTurn it off any time with: drawpro-mcp telemetry off");
+    return;
+  }
+  console.log(`Telemetry is ${telemetryEnabled() ? "ON" : "OFF"}.
+`);
+  console.log("If enabled, this is the entire payload \u2014 tool counts and timings,");
+  console.log("no account, no token, no workspace or sheet ids, nothing drawn:\n");
+  console.log(report ? JSON.stringify(report, null, 2) : "  (nothing recorded yet \u2014 set DRAWPRO_MCP_LOG first)");
+  console.log("\n  drawpro-mcp telemetry on     share it");
+  console.log("  drawpro-mcp telemetry off    stop");
+  console.log("  drawpro-mcp report           send once now, without turning it on");
+}
+async function reportOnce() {
+  const report = buildReport();
+  if (!report) {
+    console.error("Nothing to report. Set DRAWPRO_MCP_LOG to record usage first.");
+    process.exit(2);
+  }
+  console.log("Sending:\n");
+  console.log(JSON.stringify(report, null, 2));
+  const { ok, detail } = await sendReport(report);
+  console.log(ok ? "\nSent. Thank you." : `
+Could not send (${detail}). Paste the JSON above into an issue instead.`);
+}
+function maybeSendInBackground() {
+  if (!telemetryEnabled()) return;
+  const last = readConfig().lastReportAt;
+  if (last && Date.now() - Date.parse(last) < 24 * 60 * 60 * 1e3) return;
+  const report = buildReport();
+  if (!report) return;
+  void sendReport(report).then(({ ok }) => {
+    if (ok) writeConfig({ lastReportAt: (/* @__PURE__ */ new Date()).toISOString() });
+  });
+}
 async function main() {
   const command = process.argv[2];
   if (command === "login") {
     await login(process.argv.includes("--forget"));
     return;
   }
+  if (command === "telemetry") {
+    await telemetry(process.argv[3]);
+    return;
+  }
+  if (command === "report") {
+    await reportOnce();
+    return;
+  }
+  if (command === "stats") {
+    const rest = process.argv.slice(3);
+    stats(rest.find((a) => !a.startsWith("--")), rest.includes("--json"));
+    return;
+  }
   if (command && command !== "serve") {
-    console.error(`Unknown command "${command}". Use: drawpro-mcp [serve|login] [--forget]`);
+    console.error(
+      `Unknown command "${command}". Use: drawpro-mcp [serve|login|stats|telemetry|report]`
+    );
     process.exit(2);
   }
+  maybeSendInBackground();
   await server.connect(new import_stdio.StdioServerTransport());
 }
 main().catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawpro/mcp",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "MCP server for DrawPro \u2014 read and create end-to-end encrypted Excalidraw diagrams from Claude",
   "license": "MIT",
   "repository": {