@endiagram/mcp 0.1.16 → 0.2.0

package/README.md

@@ -1,8 +1,6 @@
 # @endiagram/mcp
 
-MCP server for [EN Diagram](https://endiagram.com) — structural analysis powered by deterministic graph algorithms.
-
-Write your system in plain text. Get back structural facts: bottlenecks, blast radius, flow landmarks, concurrency groups, and more. No AI inside the computation — every result is deterministic.
+MCP server for [EN Diagram](https://endiagram.com) — deterministic structural analysis powered by graph theory. Every result is backed by a named mathematical theorem. No AI inside the computation.
 
 ## Installation
 
@@ -80,25 +78,34 @@ smithery mcp add dushyant30suthar/endiagram
 
 | Tool | Description |
 |------|-------------|
-| `analyze_system` | Structural signal — computes topology, roles, antipatterns from EN source |
-| `render` | Render a dependency graph as publication-quality SVG |
-| `detail` | Deep structural analysis — concurrency, flow landmarks, resilience, dominator tree, min-cuts |
-| `distance` | Shortest path between two nodes with subsystem crossing annotations |
-| `diff` | Structural diff between two systems — topology, role, and subsystem changes |
-| `trace` | Follow directed flow from node A to node B with role and subsystem annotations |
-| `extract` | Extract a named subsystem as standalone EN source code |
-| `impact` | Blast radius — remove a node and see what disconnects |
-| `evolve` | Dry-run architectural changes — apply a patch and see the structural delta |
-| `between` | Betweenness centrality — what fraction of all shortest paths flow through a node |
+| `analyze` | System overview: shape, node roles, single points of failure, failure threshold, flow hotspots |
+| `detail` | Concurrency, critical path, flow landmarks, resilience, dependency chains, dominator tree |
 | `categorize` | Auto-discover subsystem boundaries from dependency structure |
-| `compose` | Merge two EN graphs into one with entity linking |
+| `distance` | Structural distance between two nodes with the path between them |
+| `diff` | Compare two systems — what changed structurally |
+| `trace` | Follow directed flow from A to B, optional defense node coverage check |
+| `between` | How much of the system flows through a specific node |
+| `extract` | Extract a subsystem as standalone EN source |
+| `impact` | What changes if a node is removed, includes propagation |
+| `evolve` | Dry-run a structural change before making it |
+| `compose` | Merge two systems into one by linking shared entities |
+| `conserve` | Structural invariants, deadlock analysis, complexity, resilience |
+| `render` | SVG diagram |
 
 ## EN Syntax
 
+One statement per line:
+
 ```
-Customer do: place order needs: menu yields: order
-Kitchen do: prepare food needs: order yields: meal
-Waiter do: deliver needs: meal yields: served customer
+actor do: action needs: input1, input2 yields: output1, output2
+```
+
+Shared names between yields and needs create connections automatically:
+
+```
+customer do: place order needs: menu yields: order
+kitchen do: prepare food needs: order yields: meal
+waiter do: deliver needs: meal yields: served customer
 ```
 
 Learn more at [endiagram.com](https://endiagram.com).
@@ -106,4 +113,3 @@ Learn more at [endiagram.com](https://endiagram.com).
 ## License
 
 MIT
-

package/dist/index.js

@@ -27,13 +27,22 @@ async function callApi(toolName, args) {
         };
     }
 }
-const PLAIN_LANG = " When presenting findings to the user, use plain everyday language. Never use jargon like 'betweenness centrality', 'min-cut', 'bridge node', 'dominator tree', 'vertex-disjoint paths', or 'topology classification'. Instead say 'bottleneck', 'single point of failure', 'no backup path', 'what controls what'. The raw data helps your analysis -- give the user clear, simple insights.";
+const EN_INSTRUCTIONS = `EN Diagram is a deterministic structural analysis engine. No AI inside — all results are backed by named mathematical theorems.
+
+To describe a system, write one statement per line:
+  actor do: action needs: input1, input2 yields: output1, output2
+
+Shared names between yields and needs create connections automatically. Multi-word names work fine. Use commas to separate multiple inputs or outputs.
+
+The engine computes structural truth from the description — the tool outputs are raw mathematical findings. Translate them into clear, practical insights relevant to what the user is trying to achieve.
+
+How to use these tools effectively: model the system first, then explore. The first tool call reveals the structure — but the real insights come from following up. A node labeled HUB that should be simple? Dig into it with between or impact. A surprising subsystem boundary? Extract it and analyze deeper. An unexpected dependency chain? Trace it. A proposed change? Evolve it and diff. The tools are designed to chain — each finding opens a question that another tool can answer. Don't stop at one call. Explore, tinker, compare, and let the math surface what no one expected.`;
 const server = new McpServer({
     name: "endiagram",
-    version: "0.1.0",
+    version: "0.2.0",
 });
-// --- analyze_system ---
-server.tool("analyze_system", "Structural signal. You describe the system, the tool computes structural facts. All computation is deterministic -- no AI inside. EN syntax: subject do: action needs: inputs yields: outputs. Returns topology classification (Pipeline, Tree, Fork-Join, Series-Parallel, State Machine, Disconnected, or Unknown), node roles (SOURCE, SINK, FORK, JOIN, HUB, PIPELINE, CYCLE), and bridges (single points of failure). A node labeled HUB that you expected to be PIPELINE is a real finding." + PLAIN_LANG, {
+// --- analyze ---
+server.tool("analyze", EN_INSTRUCTIONS + " This tool gives the system overview: shape, node roles, single points of failure, failure threshold, flow hotspots.", {
     source: z.string().describe("EN source code describing the system"),
     invariants: z
         .string()
@@ -55,7 +64,7 @@ server.tool("analyze_system", "Structural signal. You describe the system, the t
     };
 });
 // --- detail ---
-server.tool("detail", "The depth layer. Run after analyze_system to get the full picture Returns: concurrency metrics (max parallelism, critical path length, parallel paths per depth level), flow landmarks (exact depths where the graph diverges/converges -- these are your bottleneck boundaries), full resilience analysis (bridge implications with which subsystems disconnect if each bridge fails), and structural dependency chains (what feeds what, what must complete first). analyze_system tells you WHERE to look. detail tells you WHY it matters. Use categorize -> extract to isolate a subsystem first, then detail on the extracted source for focused depth.", {
+server.tool("detail", "Concurrency, critical path, flow landmarks, resilience, dependency chains, dominator tree.", {
     source: z.string().describe("EN source code describing the system"),
 }, async ({ source }) => {
     const result = await callApi("detail", { source });
@@ -65,7 +74,7 @@ server.tool("detail", "The depth layer. Run after analyze_system to get the full
     };
 });
 // --- categorize ---
-server.tool("categorize", "Auto-organize a flat list into named groups. You give it ungrouped actions with inputs and outputs -- the tool discovers subsystem boundaries from the dependency structure and names them. 25 nodes become 5-6 named subsystems. You don't define the groups. The structure does. When the discovered boundaries differ from your module structure, that difference is a finding. Use after analyze_system to see how the system organizes itself. Then feed subsystem names into extract for fractal zoom.", {
+server.tool("categorize", "Auto-discover subsystem boundaries from dependency structure.", {
     source: z.string().describe("EN source code describing the system"),
 }, async ({ source }) => {
     const result = await callApi("categorize", { source });
@@ -75,7 +84,7 @@ server.tool("categorize", "Auto-organize a flat list into named groups. You give
     };
 });
 // --- distance ---
-server.tool("distance", "Structural ruler. Computes shortest path between any two nodes (actions or entities) with annotations at every step. Returns: edge count, subsystem boundary crossings (how many module boundaries the path crosses), bridge edges on path (fragile links), and the full path with subsystem labels. Use to answer: 'how coupled are these two things?' If distance is 1-2 edges, they're tightly coupled. If it crosses 2+ subsystem boundaries, a change to one will ripple far.", {
+server.tool("distance", "Structural distance between two nodes with the path between them.", {
     source: z.string().describe("EN source code describing the system"),
     from: z.string().describe("Starting node name"),
     to: z.string().describe("Target node name"),
@@ -87,7 +96,7 @@ server.tool("distance", "Structural ruler. Computes shortest path between any tw
     };
 });
 // --- diff ---
-server.tool("diff", "Structural diff between two systems. Computes both graphs independently, then reports the delta: nodes/entities present in one but not the other, role changes (a node that was PIPELINE in A became HUB in B -- that's a coupling regression), subsystem membership changes (node migrated between clusters), topology classification changes, and stage count differences. Use for: spec vs implementation (does the code match the design?), version 1 vs version 2 (did the refactor improve or worsen structure?), intended vs actual (model what you think exists, model what does exist, diff them).", {
+server.tool("diff", "Compare two systems. What changed structurally.", {
     source_a: z.string().describe("EN source code for the first system"),
     source_b: z.string().describe("EN source code for the second system"),
 }, async ({ source_a, source_b }) => {
@@ -98,7 +107,7 @@ server.tool("diff", "Structural diff between two systems. Computes both graphs i
     };
 });
 // --- trace ---
-server.tool("trace", "Follow the flow -- data, materials, authority, money, risk. Computes directed shortest path from node A to node B, respecting the yields->needs flow direction. Every node on the path is annotated with its structural role and subsystem membership, so you can see role transitions along the flow (e.g., SOURCE -> PIPELINE -> HUB -> SINK). If no directed path exists, falls back to undirected and flags which edges are traversed backwards -- reverse edges often indicate missing abstractions or circular dependencies. Optional defense_nodes parameter checks whether specified nodes cover all source-to-sink paths.", {
+server.tool("trace", "Follow directed flow from A to B. Optional: check if defense nodes cover all paths.", {
     source: z.string().describe("EN source code describing the system"),
     from: z.string().describe("Starting node name"),
     to: z.string().describe("Target node name"),
@@ -119,9 +128,9 @@ server.tool("trace", "Follow the flow -- data, materials, authority, money, risk
     };
 });
 // --- between ---
-server.tool("between", "Quantify coupling. Computes betweenness centrality for a node: what fraction of all shortest paths in the system flow through it. Returns normalized score [0-1], absolute shortest-paths-through count, and total paths. A score of 0.25 means one quarter of all communication in the system passes through this node -- it's a coupling hotspot. Use on nodes flagged as HUB or FORK by analyze_system to get a precise number. Compare centrality scores across nodes to find the true bottleneck vs nodes that just look important.", {
+server.tool("between", "How much of the system flows through a specific node.", {
     source: z.string().describe("EN source code describing the system"),
-    node: z.string().describe("Node to compute betweenness centrality for"),
+    node: z.string().describe("Node name"),
 }, async ({ source, node }) => {
     const result = await callApi("between", { source, node });
     return {
@@ -130,7 +139,7 @@ server.tool("between", "Quantify coupling. Computes betweenness centrality for a
     };
 });
 // --- extract ---
-server.tool("extract", "Fractal zoom. Extract a named subsystem as standalone EN source code you can feed back into analyze_system for a deeper look. Reports boundary inputs (dependencies from outside the subsystem), boundary outputs (consumed by other subsystems), and internal entities. This is how you go from surface findings to root causes: categorize gives you subsystem names -> extract gives you the subsystem as its own graph -> analyze_system on that graph reveals internal structure invisible at the top level.", {
+server.tool("extract", "Extract a subsystem as standalone EN source. Feed back into other tools.", {
     source: z.string().describe("EN source code describing the system"),
     subsystem: z.string().describe("Name of the subsystem to extract"),
 }, async ({ source, subsystem }) => {
@@ -141,9 +150,9 @@ server.tool("extract", "Fractal zoom. Extract a named subsystem as standalone EN
     };
 });
 // --- impact ---
-server.tool("impact", "Blast radius calculator. Remove a node and see what breaks. Returns which nodes become disconnected (unreachable), whether the overall topology classification changes, and connected component count before vs after. Use to answer: 'what breaks if this node goes down?' If removing a node disconnects 0 others, it's safely removable. If it splits the graph into multiple components, it's load-bearing. Run this on every bridge node from analyze_system to Works for any domain -- remove a team from an org, a control from a compliance flow, a step from a clinical pathway. Same math.", {
+server.tool("impact", "What changes if a node is removed. Includes how far the effect propagates.", {
     source: z.string().describe("EN source code describing the system"),
-    node: z.string().describe("Node to remove for impact analysis"),
+    node: z.string().describe("Node to remove"),
 }, async ({ source, node }) => {
     const result = await callApi("impact", { source, node });
     return {
@@ -152,7 +161,7 @@ server.tool("impact", "Blast radius calculator. Remove a node and see what break
     };
 });
 // --- evolve ---
-server.tool("evolve", "Dry-run for architectural changes. Apply a patch to a system and see the structural delta before writing any code. Patch nodes with the same name replace originals; new names are additions. Returns the full diff (topology change, role changes, subsystem shifts) plus new bridge nodes created and bridge nodes eliminated. Use to test: 'What happens if I add a validation step here?' 'Does adding a cache layer create a new single point of failure?' 'Will splitting this service improve or worsen coupling?' Answer these questions in seconds, not hours.", {
+server.tool("evolve", "Dry-run a structural change before making it.", {
     source: z.string().describe("EN source code describing the current system"),
     patch: z.string().describe("EN source code patch to apply"),
 }, async ({ source, patch }) => {
@@ -163,7 +172,7 @@ server.tool("evolve", "Dry-run for architectural changes. Apply a patch to a sys
     };
 });
 // --- compose ---
-server.tool("compose", "Merge two EN graphs into one. Takes two separate system descriptions and a list of entity links that connect them. Linked entities are merged under source A's name. Unlinked entities that share a name are automatically disambiguated. Returns combined EN source that you feed into any other tool -- analyze_system sees cross-graph bridges, impact shows blast radius across both graphs, distance measures paths crossing graph boundaries. Use when modeling two interacting systems (client/server, producer/consumer, spec/implementation) that share specific data points.", {
+server.tool("compose", "Merge two systems into one by linking shared entities.", {
     source_a: z.string().describe("EN source code for the first system"),
     source_b: z.string().describe("EN source code for the second system"),
     links: z
@@ -176,17 +185,27 @@ server.tool("compose", "Merge two EN graphs into one. Takes two separate system
         isError: result.isError,
     };
 });
-// --- render (last — only use when user explicitly asks to visualize) ---
-server.tool("render", "Render an EN dependency graph as a publication-quality SVG image. Only call this when the user explicitly asks to visualize or render. Nodes are colored by structural role (source, sink, hub, etc.) and grouped by auto-detected subsystem. The visual reveals patterns (clusters, isolated subgraphs, fan-out imbalance) that text output alone misses.", {
+// --- conserve ---
+server.tool("conserve", "Structural invariants, deadlock analysis, complexity, and resilience.", {
+    source: z.string().describe("EN source code describing the system"),
+}, async ({ source }) => {
+    const result = await callApi("conserve", { source });
+    return {
+        content: [{ type: "text", text: result.text }],
+        isError: result.isError,
+    };
+});
+// --- render ---
+server.tool("render", "SVG diagram. Only when user asks to visualize.", {
     source: z.string().describe("EN source code describing the system"),
     theme: z
         .enum(["dark", "light"])
         .optional()
-        .describe("Color theme for the rendered image"),
+        .describe("Color theme"),
     quality: z
         .enum(["small", "mid", "max"])
         .optional()
-        .describe("Output quality / resolution"),
+        .describe("Output quality"),
 }, async ({ source, theme, quality }) => {
     const result = await callApi("render", { source, theme, quality });
     return {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@endiagram/mcp",
-  "version": "0.1.16",
-  "description": "MCP server for EN Diagram — structural analysis for any system",
+  "version": "0.2.0",
+  "description": "MCP server for EN Diagram — deterministic structural analysis backed by named theorems",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -22,8 +22,8 @@
     "zod": "^3.23.0"
   },
   "devDependencies": {
-    "typescript": "^5.5.0",
-    "@types/node": "^20.0.0"
+    "@types/node": "^20.0.0",
+    "typescript": "^5.9.3"
   },
   "publishConfig": {
     "access": "public"