@endiagram/mcp 0.2.37 → 0.3.0

package/README.md

@@ -104,6 +104,37 @@ waiter do: deliver needs: meal yields: served customer
 
 Learn more at [endiagram.com](https://endiagram.com).
 
+## Telemetry
+
+`@endiagram/mcp` generates a random install ID on first run, stored at
+`~/.endiagram/install-id` (mode `0600`). It is sent with every request as
+the `X-Endiagram-Install-Id` HTTP header so we can correlate requests
+from the same install for debugging issues that the per-IP signal alone
+cannot track (mobile networks, VPNs, CGNAT all collapse or churn IPs).
+
+**No source code, no file paths, no environment variables, and no PII
+are sent.** The install ID is a random opaque UUIDv4 generated locally.
+
+A first-run notice prints to **stderr** (never stdout — stdout is the
+MCP JSON-RPC channel) with the disclosure and the opt-out instructions.
+The notice fires once per install and never again.
+
+### Opting out
+
+Any of these three methods disables the install ID:
+
+1. Set `ENDIAGRAM_TELEMETRY=off` as an environment variable (also
+   accepts `0`, `false`, `no`).
+2. Create a file at `~/.endiagram/telemetry` containing the word `off`.
+3. Delete `~/.endiagram/install-id`. (A new one is generated on next
+   run unless option 1 or 2 is also set.)
+
+When any of these is active, the `X-Endiagram-Install-Id` header is not
+sent at all — the server falls back to its per-IP HMAC `cid` for
+correlation, which works fine for short-term per-session tracing.
+
+Full privacy policy: [endiagram.com/privacy](https://endiagram.com/privacy)
+
 ## License
 
 MIT

package/dist/index.js

@@ -2,12 +2,95 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { randomUUID } from "node:crypto";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const toolsConfig = JSON.parse(readFileSync(join(__dirname, "../tools.json"), "utf-8"));
+const pkg = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf-8"));
 const EN_API_URL = process.env.EN_API_URL ?? "https://api.endiagram.com";
+// ─────────────────────────────────────────────────────────────────────
+// Install ID — persistent, opt-out by env var or file
+//
+// On first run, generate a UUIDv4 and store it at ~/.endiagram/install-id
+// (chmod 0600). Sent on every request as the X-Endiagram-Install-Id header
+// so the server can correlate requests from the same install for debugging
+// per-installation issues that the per-IP cid HMAC can't track (mobile
+// rotation, CGNAT, VPN).
+//
+// No source code, no file paths, no environment variables, no PII are
+// sent. The install ID is a random opaque UUID generated locally.
+//
+// Three opt-out mechanisms (any one disables the header):
+//   1. ENDIAGRAM_TELEMETRY=off  (env var, also accepts 0/false/no)
+//   2. ~/.endiagram/telemetry   (file containing "off")
+//   3. delete ~/.endiagram/install-id  (regenerated unless 1 or 2 set)
+// ─────────────────────────────────────────────────────────────────────
+const UUIDV4_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+function resolveInstallId() {
+    // Tier 1: env var opt-out
+    const envFlag = process.env.ENDIAGRAM_TELEMETRY?.trim().toLowerCase();
+    if (envFlag && /^(off|0|false|no)$/.test(envFlag)) {
+        return null;
+    }
+    const stateDir = join(homedir(), ".endiagram");
+    const telemetryFile = join(stateDir, "telemetry");
+    const installFile = join(stateDir, "install-id");
+    // Tier 2: disk flag opt-out
+    if (existsSync(telemetryFile)) {
+        try {
+            const flag = readFileSync(telemetryFile, "utf-8").trim().toLowerCase();
+            if (/^(off|0|false|no)$/.test(flag))
+                return null;
+        }
+        catch {
+            // unreadable telemetry file — fall through, prefer enabled state
+        }
+    }
+    // Read existing install-id
+    if (existsSync(installFile)) {
+        try {
+            const existing = readFileSync(installFile, "utf-8").trim().toLowerCase();
+            if (UUIDV4_REGEX.test(existing))
+                return existing;
+            // malformed — fall through to regenerate
+        }
+        catch {
+            // unreadable — fall through to regenerate
+        }
+    }
+    // First run (or corrupted file): generate, persist, print notice
+    const fresh = randomUUID();
+    try {
+        mkdirSync(stateDir, { recursive: true });
+        writeFileSync(installFile, fresh, { encoding: "utf-8" });
+        // Restrict to owner rw only — install ID is effectively a stable
+        // pseudonymous identifier; treat it like a low-sensitivity secret.
+        try {
+            chmodSync(installFile, 0o600);
+        }
+        catch {
+            // Some filesystems don't support POSIX perms — best effort.
+        }
+        // First-run disclosure to STDERR (never stdout — stdout is the
+        // MCP JSON-RPC channel and any bytes there corrupt Claude Desktop).
+        process.stderr.write(`[endiagram] First run: generated install ID at ${installFile}\n` +
+            `[endiagram] This ID is sent with requests so we can correlate per\n` +
+            `            installation for debugging. No source code, file paths,\n` +
+            `            env vars, or PII are sent.\n` +
+            `            Opt out: ENDIAGRAM_TELEMETRY=off  (or delete the file)\n` +
+            `            Privacy: https://endiagram.com/privacy\n`);
+    }
+    catch {
+        // Could not persist (read-only home dir, etc.) — return the
+        // generated id anyway so the current process still gets correlation
+        // within its own lifetime. Next run will try again.
+    }
+    return fresh;
+}
+const INSTALL_ID = resolveInstallId();
 /**
  * Resolve the `source` parameter: if it looks like a file path (.en, .txt,
  * or starts with / or ~), read the file and return its contents.
@@ -30,9 +113,16 @@ function resolveSource(source) {
 }
 async function callApi(toolName, args) {
     try {
+        const headers = {
+            "Content-Type": "application/json",
+            "User-Agent": `endiagram-mcp/${pkg.version} node/${process.version.replace(/^v/, "")}`,
+        };
+        if (INSTALL_ID) {
+            headers["X-Endiagram-Install-Id"] = INSTALL_ID;
+        }
         const response = await fetch(`${EN_API_URL}/mcp`, {
             method: "POST",
-            headers: { "Content-Type": "application/json" },
+            headers,
             body: JSON.stringify({
                 jsonrpc: "2.0",
                 id: Date.now(),
@@ -76,7 +166,7 @@ async function callApi(toolName, args) {
     }
 }
 const EN_INSTRUCTIONS = toolsConfig.instructions;
-const server = new McpServer({ name: "endiagram", version: "0.2.0" }, { instructions: EN_INSTRUCTIONS });
+const server = new McpServer({ name: "endiagram", version: pkg.version }, { instructions: EN_INSTRUCTIONS });
 for (const tool of toolsConfig.tools) {
     const schemaProps = {};
     for (const param of tool.parameters) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@endiagram/mcp",
-  "version": "0.2.37",
+  "version": "0.3.0",
   "description": "MCP server for EN Diagram — deterministic structural analysis backed by named theorems",
   "type": "module",
   "main": "dist/index.js",