@endiagram/mcp 0.2.38 → 0.3.1

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(),
@@ -56,12 +146,17 @@ async function callApi(toolName, args) {
             const content = result?.content?.[0];
             const text = content?.text ?? body;
             const isError = result?.isError ?? false;
-            // Check for SVG in second content block (render tool)
-            const svgContent = result?.content?.[1];
-            const svg = svgContent?.text?.startsWith("<svg")
-                ? svgContent.text
+            // Check for rendered content in second content block (render tool).
+            // SVG: text block whose text starts with "<svg".
+            // PNG: image block with base64 data + mimeType "image/png".
+            const renderContent = result?.content?.[1];
+            const svg = renderContent?.text?.startsWith("<svg")
+                ? renderContent.text
+                : undefined;
+            const pngBase64 = renderContent?.type === "image" && renderContent?.mimeType === "image/png"
+                ? renderContent.data
                 : undefined;
-            return { text, isError, svg, data: undefined };
+            return { text, isError, svg, pngBase64, data: undefined };
         }
         catch {
             return { text: body, isError: false };
@@ -76,7 +171,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) {
@@ -98,33 +193,47 @@ for (const tool of toolsConfig.tools) {
             const msg = e instanceof Error ? e.message : String(e);
             return { content: [{ type: "text", text: `Failed to read source file: ${msg}` }], isError: true };
         }
-        // Special handling for render (save SVG to file)
+        // Special handling for render — save SVG or PNG to file.
+        // The rendered image is for the user's eyes (audience:user), never
+        // injected into the model's context. We save to disk and return the
+        // file path as a text content block.
         if (tool.name === "render") {
             const result = await callApi("render", args);
-            if (result.isError || !result.svg) {
+            const isPng = !!result.pngBase64;
+            const hasContent = isPng || !!result.svg;
+            if (result.isError || !hasContent) {
                 return {
                     content: [{ type: "text", text: result.text }],
                     isError: result.isError,
                 };
             }
             const outputPath = args.output;
+            const ext = isPng ? ".png" : ".svg";
             let filePath;
             if (outputPath) {
-                const dir = dirname(outputPath);
+                // If the user gave a path, respect it but fix the extension.
+                const base = outputPath.replace(/\.(svg|png)$/i, "");
+                filePath = base + ext;
+                const dir = dirname(filePath);
                 if (!existsSync(dir))
                     mkdirSync(dir, { recursive: true });
-                filePath = outputPath;
             }
             else {
                 const outDir = join(process.cwd(), ".endiagram");
                 if (!existsSync(outDir))
                     mkdirSync(outDir, { recursive: true });
-                filePath = join(outDir, `en-${Date.now()}.svg`);
+                filePath = join(outDir, `en-${Date.now()}${ext}`);
+            }
+            if (isPng) {
+                writeFileSync(filePath, Buffer.from(result.pngBase64, "base64"));
+            }
+            else {
+                writeFileSync(filePath, result.svg);
             }
-            writeFileSync(filePath, result.svg);
+            const label = isPng ? "PNG" : "SVG";
             return {
                 content: [
-                    { type: "text", text: `SVG saved: ${filePath}` },
+                    { type: "text", text: `${label} saved: ${filePath}` },
                 ],
                 isError: false,
             };

package/package.json

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

package/tools.json

@@ -1,9 +1,9 @@
 {
-  "instructions": "EN Diagram is a structural verification engine for concurrent systems. No AI inside.\n\nTo describe a system, write one statement per line:\n  actor do: action needs: input1, input2 yields: output1, output2 at: context\n\nEvery statement requires: actor, do:, needs:, and yields:. Shared names between yields and needs create connections automatically. Multi-word names work fine. Use commas to separate multiple inputs or outputs. at: scopes the action to a context (service, team, region, domain, layer — whatever boundary fits the system).\n\nMultiple actors can share the same action: actor1, actor2 do: action needs: X yields: Y. Two separate statements with the same action, needs, yields, and location are automatically merged into one shared action.\n\nSix tools answer six questions from concurrency theory. Each answer includes who (actors) and where (locations) alongside the structural findings.\n\n1. structure — what is this system?\n2. invariant — what's always true?\n3. live — can it deadlock? can entities overflow?\n4. reachable — can X reach Y?\n5. equivalent — are two systems the same?\n6. compose — how do parts combine?\n\nEvery tool output contains node names, values, and structural properties that can be fed directly into other tools. Read the output. Find the surprising node, the unexpected value, the structural anomaly. Then pick the tool that investigates THAT specific finding.\n\nDo not stop at one tool call. The first call reveals the structure — the real insight comes from the second, third, fourth call that digs into what the first one found.\n\nSpeak in the user's domain, not in graph theory. Only call render when the user explicitly asks to visualize.",
+  "instructions": "EN Diagram is a structural verification engine for concurrent systems. No AI inside.\n\n## Language syntax\n\nOne statement per line:\n  actor do: action needs: input1, input2 yields: output1, output2 at: context\n\nEvery statement requires: actor, do:, needs:, and yields:. at: scopes the action to a context (service, team, region, domain, layer — whatever boundary fits the system).\n\n**Names can contain spaces.** Unquoted identifiers can span multiple words, so `duo initiator do: create DuoSession needs: session factory yields: active session` is valid. Commas separate list items; whitespace inside a name is preserved. Wrap a name in double quotes only when it must contain a comma, colon, or `#` character.\n\n**Shared names create connections.** When one action's `yields:` name matches another action's `needs:` name, the two actions connect automatically. No explicit wiring — string equality is the link.\n\n**Multiple actors on one action.** Comma-separate subjects to express that several actors perform the same action together:\n  actor1, actor2 do: action needs: X yields: Y\nThis is a single action performed jointly, not two separate actions. Two independent statements with the same action name, needs, yields, AND at: location are automatically merged into one shared action.\n\n**Comments.** Lines starting with `#` are ignored. Blank lines are ignored.\n\n## Tools\n\nSix tools answer six questions from concurrency theory. Each answer includes who (actors) and where (locations) alongside the structural findings.\n\n1. structure — what is this system?\n2. invariant — what's always true?\n3. live — can it deadlock? can entities overflow?\n4. reachable — can X reach Y?\n5. equivalent — are two systems the same?\n6. compose — how do parts combine?\n\nEvery tool output contains node names, values, and structural properties that can be fed directly into other tools. Read the output. Find the surprising node, the unexpected value, the structural anomaly. Then pick the tool that investigates THAT specific finding.\n\nDo not stop at one tool call. The first call reveals the structure — the real insight comes from the second, third, fourth call that digs into what the first one found.\n\nSpeak in the user's domain, not in graph theory. Only call render when the user explicitly asks to visualize.",
   "tools": [
     {
       "name": "structure",
-      "description": "What is this system? Complete structural overview: shape (topology), stages with roles, bridge nodes, cycles, parallelism, critical path, dominator tree, min-cuts, subsystems, interface nodes. Includes actors (who does what, workload entropy) and locations (where work happens, boundary crossings). Optional: pass node for per-node centrality, detect_findings for structural pattern detection.",
+      "description": "What is this system? Complete structural overview: shape (topology), stages with roles, bridge nodes, cycles, parallelism, critical path, dominator tree, min-cuts, subsystems, interface nodes. Includes actors (who does what, workload entropy) and locations (where work happens, boundary crossings). Optional: pass node for per-node centrality, detect_findings for structural pattern detection. See the server instructions for EN language syntax (spaces in names, # comments, shared actions).",
       "parameters": [
         {"name": "source", "type": "string", "description": "EN source code, or path to .en/.txt file", "required": true},
         {"name": "node", "type": "string", "description": "Node name for centrality query", "required": false},
@@ -12,7 +12,7 @@
     },
     {
       "name": "invariant",
-      "description": "What's always true? conservationLaws are weighted entity sums constant across all executions. sustainableCycles are action sequences that return the system to its starting state (T-invariants). depletableSets are entity groups where simultaneous depletion is irreversible. behavioral.deficiency 0 means structure fully determines dynamics. behavioral.isReversible and behavioral.hasUniqueEquilibrium describe convergence properties.",
+      "description": "What's always true? conservationLaws are weighted entity sums constant across all executions. sustainableCycles are action sequences that return the system to its starting state (T-invariants). depletableSets are entity groups where simultaneous depletion is irreversible. behavioral.deficiency 0 means structure fully determines dynamics. behavioral.isReversible and behavioral.hasUniqueEquilibrium describe convergence properties. See the server instructions for EN language syntax.",
       "parameters": [
         {"name": "source", "type": "string", "description": "EN source code, or path to .en/.txt file", "required": true},
         {"name": "rules", "type": "string", "description": "Structural rules to check, one per line", "required": false}
@@ -20,14 +20,14 @@
     },
     {
       "name": "live",
-      "description": "Can it deadlock? Can entities overflow? isStructurallyLive means every siphon contains a trap — no structural deadlock possible. uncoveredSiphons are entity groups that can drain permanently, with the actors and locations affected. isStructurallyBounded means no entity can accumulate without limit. unboundedCycles are action sequences that could cause overflow.",
+      "description": "Can it deadlock? Can entities overflow? isStructurallyLive means every siphon contains a trap — no structural deadlock possible. uncoveredSiphons are entity groups that can drain permanently, with the actors and locations affected. isStructurallyBounded means no entity can accumulate without limit. unboundedCycles are action sequences that could cause overflow. See the server instructions for EN language syntax.",
       "parameters": [
         {"name": "source", "type": "string", "description": "EN source code, or path to .en/.txt file", "required": true}
       ]
     },
     {
       "name": "reachable",
-      "description": "Can X reach Y? Follows directed data flow first; falls back to undirected. Path shows each step with actor and location. locationCrossings counts boundary transitions. defense_nodes checks if guards cover all paths. coverage.fullCoverage false means unguarded routes exist.",
+      "description": "Can X reach Y? Follows directed data flow first; falls back to undirected. Path shows each step with actor and location. locationCrossings counts boundary transitions. defense_nodes checks if guards cover all paths. coverage.fullCoverage false means unguarded routes exist. See the server instructions for EN language syntax.",
       "parameters": [
         {"name": "source", "type": "string", "description": "EN source code", "required": true},
         {"name": "from", "type": "string", "description": "Starting node name", "required": true},
@@ -37,7 +37,7 @@
     },
     {
       "name": "equivalent",
-      "description": "Are two systems the same? Compare mode (source_a + source_b): shows structural differences, edit distance, and spectral equivalence — isCospectral true means identical structure despite different names. Evolve mode (source + patch): dry-run a change, shows diff plus new/lost bridge nodes. Prefix action name with - in patch to remove it.",
+      "description": "Are two systems the same? Compare mode (source_a + source_b): shows structural differences, edit distance, and spectral equivalence — isCospectral true means identical structure despite different names. Evolve mode (source + patch): dry-run a change, shows diff plus new/lost bridge nodes. Prefix action name with - in patch to remove it. See the server instructions for EN language syntax.",
       "parameters": [
         {"name": "source_a", "type": "string", "description": "EN source code or path to .en/.txt file for the first system", "required": false},
         {"name": "source_b", "type": "string", "description": "EN source code or path to .en/.txt file for the second system", "required": false},
@@ -47,7 +47,7 @@
     },
     {
       "name": "compose",
-      "description": "How do parts combine? Merge mode (source_a + source_b + links): merge two systems by linking shared entities. Extract mode (source + subsystem): extract a subsystem as standalone EN with boundary inputs/outputs, actors, and locations.",
+      "description": "How do parts combine? Merge mode (source_a + source_b + links): merge two systems by linking shared entities. Extract mode (source + subsystem): extract a subsystem as standalone EN with boundary inputs/outputs, actors, and locations. See the server instructions for EN language syntax.",
       "parameters": [
         {"name": "source_a", "type": "string", "description": "EN source code or path to .en/.txt file for the first system", "required": false},
         {"name": "source_b", "type": "string", "description": "EN source code or path to .en/.txt file for the second system", "required": false},
@@ -58,15 +58,18 @@
     },
     {
       "name": "render",
-      "description": "SVG diagram. Only call when user explicitly asks to visualize.",
+      "description": "SVG or PNG diagram. Only call when user explicitly asks to visualize. The rendered image is delivered to the user, not injected into the model's context. See the server instructions for EN language syntax.",
       "parameters": [
         {"name": "source", "type": "string", "description": "EN source code, or path to .en/.txt file", "required": true},
-        {"name": "theme", "type": "string", "description": "Color theme: dark or light", "required": false},
+        {"name": "theme", "type": "string", "description": "Color theme: named preset (Blueprint, Swiss, etc.) or dark/light", "required": false},
+        {"name": "isDark", "type": "string", "description": "true or false. Selects the dark or light variant of a named preset. If omitted, defaults to dark unless theme=light.", "required": false},
+        {"name": "type", "type": "string", "description": "Output format: svg (default) or png. PNG is rasterized server-side via Batik.", "required": false},
         {"name": "quality", "type": "string", "description": "Output quality: small, mid, or max", "required": false},
         {"name": "view", "type": "string", "description": "Group by: actors (partition by actor) or locations (partition by location). Default auto-detects topology.", "required": false},
-        {"name": "structure_layers", "type": "string", "description": "Bitmask for structure overlays. Bits: 1=subsystems, 2=pipelines, 4=cycles, 8=forks, 16=joins, 32=hubs. Default 63 (all on). Pass 0 to hide all.", "required": false},
+        {"name": "structure_layers", "type": "string", "description": "Bitmask for structure overlays. Bits: 1=subsystems, 2=pipelines, 4=cycles, 8=forks, 16=joins, 32=hubs, 64=deadlock, 128=overflow. Default 255 (all on). Pass 0 to hide all.", "required": false},
         {"name": "color", "type": "string", "description": "Seed color hex (#RRGGBB) to generate a custom theme. Overrides theme parameter. One color generates the entire palette.", "required": false},
-        {"name": "output", "type": "string", "description": "File path to save the SVG", "required": false}
+        {"name": "direction", "type": "string", "description": "Layout direction: LR (left-to-right) or TB (top-to-bottom). Default auto-detects from condensation DAG aspect ratio.", "required": false},
+        {"name": "output", "type": "string", "description": "File path to save the rendered image", "required": false}
       ]
     }
   ]