@endiagram/mcp 0.3.0 → 0.3.2

package/dist/index.js

@@ -146,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;
-            return { text, isError, svg, data: undefined };
+            const pngBase64 = renderContent?.type === "image" && renderContent?.mimeType === "image/png"
+                ? renderContent.data
+                : undefined;
+            return { text, isError, svg, pngBase64, data: undefined };
         }
         catch {
             return { text: body, isError: false };
@@ -188,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.3.0",
+  "version": "0.3.2",
   "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 — structural verification for concurrent systems. Pure math, no AI.\n\n## Syntax\nOne statement per line:\n  actor do: action needs: input1, input2 yields: output1, output2 at: context\n\n- All five parts required.\n- Names span words; whitespace preserved. Quote only if name contains `,`, `:`, or `#`.\n- Shared names = connections: one action's `yields:` matching another's `needs:` wires them automatically. String equality is the link.\n- Multi-actor: `a, b do: action needs: X yields: Y` = one joint action. Identical statements merge.\n- `#` starts a comment.\n\n## Tools (six questions)\n1. structure — what is this system?\n2. invariant — what's always true?\n3. live — can it deadlock or overflow?\n4. reachable — can X reach Y?\n5. equivalent — are two systems the same?\n6. compose — how do parts combine?\n\n## How to use them\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: png (default) or svg. 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}
       ]
     }
   ]