@endiagram/mcp 0.1.7 → 0.1.9

package/dist/index.js

@@ -27,12 +27,13 @@ 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 server = new McpServer({
     name: "en-diagram",
     version: "0.1.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.", {
+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, {
     source: z.string().describe("EN source code describing the system"),
     invariants: z
         .string()
@@ -53,29 +54,21 @@ server.tool("analyze_system", "Structural signal. You describe the system, the t
         isError: result.isError,
     };
 });
-// --- render ---
-server.tool("render", "Render an EN dependency graph as a publication-quality SVG image. Nodes are colored by structural role (source, sink, hub, etc.) and grouped by auto-detected subsystem. Use when the user wants to SEE the structure -- the visual often reveals patterns (clusters, isolated subgraphs, fan-out imbalance) that text output alone misses.", {
+// --- 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.", {
     source: z.string().describe("EN source code describing the system"),
-    theme: z
-        .enum(["dark", "light"])
-        .optional()
-        .describe("Color theme for the rendered image"),
-    quality: z
-        .enum(["small", "mid", "max"])
-        .optional()
-        .describe("Output quality / resolution"),
-}, async ({ source, theme, quality }) => {
-    const result = await callApi("render", { source, theme, quality });
+}, async ({ source }) => {
+    const result = await callApi("detail", { source });
     return {
         content: [{ type: "text", text: result.text }],
         isError: result.isError,
     };
 });
-// --- 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.", {
+// --- 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.", {
     source: z.string().describe("EN source code describing the system"),
 }, async ({ source }) => {
-    const result = await callApi("detail", { source });
+    const result = await callApi("categorize", { source });
     return {
         content: [{ type: "text", text: result.text }],
         isError: result.isError,
@@ -125,6 +118,17 @@ server.tool("trace", "Follow the flow -- data, materials, authority, money, risk
         isError: result.isError,
     };
 });
+// --- 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.", {
+    source: z.string().describe("EN source code describing the system"),
+    node: z.string().describe("Node to compute betweenness centrality for"),
+}, async ({ source, node }) => {
+    const result = await callApi("between", { source, node });
+    return {
+        content: [{ type: "text", text: result.text }],
+        isError: result.isError,
+    };
+});
 // --- 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.", {
     source: z.string().describe("EN source code describing the system"),
@@ -158,27 +162,6 @@ server.tool("evolve", "Dry-run for architectural changes. Apply a patch to a sys
         isError: result.isError,
     };
 });
-// --- 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.", {
-    source: z.string().describe("EN source code describing the system"),
-    node: z.string().describe("Node to compute betweenness centrality for"),
-}, async ({ source, node }) => {
-    const result = await callApi("between", { source, node });
-    return {
-        content: [{ type: "text", text: result.text }],
-        isError: result.isError,
-    };
-});
-// --- 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.", {
-    source: z.string().describe("EN source code describing the system"),
-}, async ({ source }) => {
-    const result = await callApi("categorize", { source });
-    return {
-        content: [{ type: "text", text: result.text }],
-        isError: result.isError,
-    };
-});
 // --- 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.", {
     source_a: z.string().describe("EN source code for the first system"),
@@ -193,6 +176,24 @@ 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.", {
+    source: z.string().describe("EN source code describing the system"),
+    theme: z
+        .enum(["dark", "light"])
+        .optional()
+        .describe("Color theme for the rendered image"),
+    quality: z
+        .enum(["small", "mid", "max"])
+        .optional()
+        .describe("Output quality / resolution"),
+}, async ({ source, theme, quality }) => {
+    const result = await callApi("render", { source, theme, quality });
+    return {
+        content: [{ type: "text", text: result.text }],
+        isError: result.isError,
+    };
+});
 // --- start server ---
 async function main() {
     const transport = new StdioServerTransport();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@endiagram/mcp",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "MCP server for EN Diagram — structural analysis for any system",
   "type": "module",
   "main": "dist/index.js",