@drawpro/mcp 0.3.0 → 0.4.1

package/README.md

@@ -121,6 +121,75 @@ 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
+
+Turning telemetry on is enough to start recording:
+
+```bash
+npx -y @drawpro/mcp telemetry      # show the state and the exact payload
+npx -y @drawpro/mcp telemetry on   # records to ~/.drawpro/usage.jsonl and shares an aggregate
+npx -y @drawpro/mcp telemetry off
+npx -y @drawpro/mcp report         # send once, without turning anything on
+```
+
+Consenting to *send* usage implies consent to *record* it — recording is the
+lesser act — so opting in does not also require configuring a log. The
+implication does not run the other way: setting `DRAWPRO_MCP_LOG` records
+locally and shares nothing.
+
+To record without ever sharing, set the path yourself:
+
+```bash
+claude mcp add drawpro --scope user \
+  -e DRAWPRO_TOKEN="dp_live_..." \
+  -e DRAWPRO_MCP_LOG="$HOME/.drawpro/usage.jsonl" \
+  -- npx -y @drawpro/mcp
+
+npx -y @drawpro/mcp stats
+```
+
+> Run these from anywhere except a checkout of this repository. Inside it, npm
+> resolves `@drawpro/mcp` to the workspace copy, whose bin is not linked, and
+> npx fails with `drawpro-mcp: command not found`. Use
+> `node packages/mcp/dist/server.js <command>` there instead.
+
+```
+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,8 +24,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/server.ts
-var import_node_fs2 = require("node:fs");
-var import_node_path2 = require("node:path");
+var import_node_fs3 = require("node:fs");
+var import_node_os3 = require("node:os");
+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");
@@ -191,11 +192,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: {
@@ -204,7 +207,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)}`);
     }
@@ -387,6 +402,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_-";
@@ -1358,10 +1402,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.1";
+var inFlight = [];
 var cachedUser = null;
 async function currentUser() {
   if (!cachedUser) cachedUser = await api().me();
@@ -1386,8 +1433,90 @@ 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(
+var DEFAULT_LOG = (0, import_node_path3.join)((0, import_node_os3.homedir)(), ".drawpro", "usage.jsonl");
+function logPath() {
+  const explicit = process.env.DRAWPRO_MCP_LOG;
+  if (explicit) return explicit;
+  return telemetryEnabled() ? DEFAULT_LOG : void 0;
+}
+function logCall(entry) {
+  const path = logPath();
+  if (!path) return;
+  try {
+    (0, import_node_fs3.mkdirSync)((0, import_node_path3.join)((0, import_node_os3.homedir)(), ".drawpro"), { recursive: true, mode: 448 });
+    (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.",
   {},
@@ -1406,7 +1535,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") },
@@ -1425,7 +1554,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.",
   {
@@ -1470,7 +1599,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,
@@ -1492,7 +1621,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.",
   {
@@ -1519,7 +1648,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.",
   {
@@ -1578,7 +1707,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.",
   {
@@ -1640,7 +1769,7 @@ ${sheetUrl(workspace_id, sheet_id)}`
     );
   }
 );
-server.tool(
+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.",
   {
@@ -1652,7 +1781,7 @@ server.tool(
   async ({ workspace_id, file_path, name, sheet_id }) => {
     let parsed;
     try {
-      parsed = JSON.parse((0, import_node_fs2.readFileSync)((0, import_node_path2.resolve)(file_path), "utf8"));
+      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}`);
     }
@@ -1679,16 +1808,184 @@ ${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 ?? logPath();
+  if (!file) {
+    console.error(
+      "No usage is being recorded. Either set DRAWPRO_MCP_LOG, turn on telemetry\n(which records to ~/.drawpro/usage.jsonl), 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 = logPath();
+  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. Usage is recorded to ${logPath()}`);
+    console.log("Roughly once a day, an aggregate of it is sent:\n");
+    console.log(
+      report ? JSON.stringify(report, null, 2) : "  (no calls recorded yet \u2014 the first report goes out once you have used the tools)"
+    );
+    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) : `  (no calls recorded yet; recording ${logPath() ? `to ${logPath()}` : "is off"})`
+  );
+  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 \u2014 no usage has been recorded. Set DRAWPRO_MCP_LOG, or\nturn on telemetry, which records to ~/.drawpro/usage.jsonl."
+    );
+    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.3.0",
+  "version": "0.4.1",
   "description": "MCP server for DrawPro \u2014 read and create end-to-end encrypted Excalidraw diagrams from Claude",
   "license": "MIT",
   "repository": {