@endiagram/mcp 0.2.10 → 0.2.12

package/dist/index.js

@@ -2,8 +2,11 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { writeFileSync, mkdirSync, existsSync } from "node:fs";
-import { join } from "node:path";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const toolsConfig = JSON.parse(readFileSync(join(__dirname, "../tools.json"), "utf-8"));
 const EN_API_URL = process.env.EN_API_URL ?? "https://api.endiagram.com";
 async function callApi(toolName, args) {
     try {
@@ -52,205 +55,48 @@ async function callApi(toolName, args) {
         };
     }
 }
-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.
-
-Go deep, not wide. When a finding catches your attention — a surprising hub, an unexpected bottleneck, a structural anomaly — lock onto it. Use one tool to surface it, then chain the next tool to explain it, then the next to stress-test it. Keep narrowing until you reach the root. One thread, followed to the end, beats ten shallow observations. Only call render when the user explicitly asks to visualize.`;
+const EN_INSTRUCTIONS = toolsConfig.instructions;
 const server = new McpServer({
     name: "endiagram",
     version: "0.2.0",
 });
-// --- 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()
-        .optional()
-        .describe("Invariants to check against the structure"),
-    detect_antipatterns: z
-        .string()
-        .optional()
-        .describe("Set to 'true' to detect structural antipatterns"),
-}, async ({ source, invariants, detect_antipatterns }) => {
-    const result = await callApi("analyze", {
-        source,
-        invariants,
-        detect_antipatterns,
-    });
-    return {
-        content: [{ type: "text", text: result.text }],
-        isError: result.isError,
-    };
-});
-// --- detail ---
-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 });
-    return {
-        content: [{ type: "text", text: result.text }],
-        isError: result.isError,
-    };
-});
-// --- categorize ---
-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 });
-    return {
-        content: [{ type: "text", text: result.text }],
-        isError: result.isError,
-    };
-});
-// --- distance ---
-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"),
-}, async ({ source, from, to }) => {
-    const result = await callApi("distance", { source, from, to });
-    return {
-        content: [{ type: "text", text: result.text }],
-        isError: result.isError,
-    };
-});
-// --- diff ---
-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 }) => {
-    const result = await callApi("diff", { source_a, source_b });
-    return {
-        content: [{ type: "text", text: result.text }],
-        isError: result.isError,
-    };
-});
-// --- trace ---
-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"),
-    defense_nodes: z
-        .string()
-        .optional()
-        .describe("Comma-separated list of defense nodes to check coverage"),
-}, async ({ source, from, to, defense_nodes }) => {
-    const result = await callApi("trace", {
-        source,
-        from,
-        to,
-        defense_nodes,
-    });
-    return {
-        content: [{ type: "text", text: result.text }],
-        isError: result.isError,
-    };
-});
-// --- between ---
-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 name"),
-}, async ({ source, node }) => {
-    const result = await callApi("between", { source, node });
-    return {
-        content: [{ type: "text", text: result.text }],
-        isError: result.isError,
-    };
-});
-// --- extract ---
-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 }) => {
-    const result = await callApi("extract", { source, subsystem });
-    return {
-        content: [{ type: "text", text: result.text }],
-        isError: result.isError,
-    };
-});
-// --- impact ---
-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"),
-}, async ({ source, node }) => {
-    const result = await callApi("impact", { source, node });
-    return {
-        content: [{ type: "text", text: result.text }],
-        isError: result.isError,
-    };
-});
-// --- evolve ---
-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 }) => {
-    const result = await callApi("evolve", { source, patch });
-    return {
-        content: [{ type: "text", text: result.text }],
-        isError: result.isError,
-    };
-});
-// --- compose ---
-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
-        .string()
-        .describe("Entity links between the two systems (e.g. 'a.node1=b.node2, a.node3=b.node4')"),
-}, async ({ source_a, source_b, links }) => {
-    const result = await callApi("compose", { source_a, source_b, links });
-    return {
-        content: [{ type: "text", text: result.text }],
-        isError: result.isError,
-    };
-});
-// --- 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 call when user explicitly asks to visualize. Saves SVG to a local file — no SVG content enters the conversation.", {
-    source: z.string().describe("EN source code describing the system"),
-    theme: z
-        .enum(["dark", "light"])
-        .optional()
-        .describe("Color theme"),
-    quality: z
-        .enum(["small", "mid", "max"])
-        .optional()
-        .describe("Output quality"),
-}, async ({ source, theme, quality }) => {
-    const result = await callApi("render", { source, theme, quality });
-    if (result.isError || !result.svg) {
+for (const tool of toolsConfig.tools) {
+    const schemaProps = {};
+    for (const param of tool.parameters) {
+        schemaProps[param.name] = param.required
+            ? z.string().describe(param.description)
+            : z.string().optional().describe(param.description);
+    }
+    server.tool(tool.name, tool.description, schemaProps, async (args) => {
+        // Special handling for render (save SVG to file)
+        if (tool.name === "render") {
+            const result = await callApi("render", args);
+            if (result.isError || !result.svg) {
+                return {
+                    content: [{ type: "text", text: result.text }],
+                    isError: result.isError,
+                };
+            }
+            const outDir = join(process.cwd(), ".endiagram");
+            if (!existsSync(outDir))
+                mkdirSync(outDir, { recursive: true });
+            const filePath = join(outDir, `en-${Date.now()}.svg`);
+            writeFileSync(filePath, result.svg);
+            return {
+                content: [
+                    { type: "text", text: `SVG saved: ${filePath}` },
+                ],
+                isError: false,
+            };
+        }
+        // All other tools
+        const result = await callApi(tool.name, args);
         return {
             content: [{ type: "text", text: result.text }],
             isError: result.isError,
         };
-    }
-    const outDir = join(process.cwd(), ".endiagram");
-    if (!existsSync(outDir))
-        mkdirSync(outDir, { recursive: true });
-    const filePath = join(outDir, `en-${Date.now()}.svg`);
-    writeFileSync(filePath, result.svg);
-    return {
-        content: [{ type: "text", text: `SVG saved: ${filePath}` }],
-        isError: false,
-    };
-});
+    });
+}
 // --- start server ---
 async function main() {
     const transport = new StdioServerTransport();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@endiagram/mcp",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "MCP server for EN Diagram — deterministic structural analysis backed by named theorems",
   "type": "module",
   "main": "dist/index.js",
@@ -9,6 +9,7 @@
   },
   "files": [
     "dist",
+    "tools.json",
     "README.md",
     "LICENSE"
   ],

package/tools.json

@@ -0,0 +1,113 @@
+{
+  "instructions": "EN Diagram is a deterministic structural analysis engine. No AI inside.\n\nTo describe a system, write one statement per line:\n  actor do: action needs: input1, input2 yields: output1, output2\n\nShared names between yields and needs create connections automatically. Multi-word names work fine. Use commas to separate multiple inputs or outputs.\n\nThe engine computes structural truth from the description — the tool outputs are raw mathematical findings. Translate them into the language of the system being analyzed. If analyzing a payment flow, say 'the payment gateway is structurally isolated' not 'node X has high centrality'. Speak in the user's domain, not in graph theory.\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. One tool surfaces a fact. The next tool explains it. The next stress-tests it. Keep narrowing until you reach the root cause. One thread followed to completion beats ten shallow observations.\n\nDo not stop at one tool call. Do not summarize after one result. 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\nIMPORTANT: Load ALL tool descriptions before starting analysis. Each tool's description explains how to read its output — without that context, results are uninterpretable. The 13 tools are: analyze, detail, categorize, distance, diff, trace, between, extract, impact, evolve, compose, conserve, render. Speak in the user's domain, not in graph theory. Only call render when the user explicitly asks to visualize.",
+  "tools": [
+    {
+      "name": "analyze",
+      "description": "System overview. Output: shape is the proven topology — known shapes are Pipeline, Tree, Star, Fork-Join, Mesh, State-Machine, Disconnected; Unknown means the system is too complex for any named category. bridgeNodes are nodes whose removal disconnects the graph. nodeRemovalThreshold is the fraction of random node removals before the system fragments. steadyStateShare is where flow naturally accumulates — share of time spent at each node if you follow connections randomly. unmatchedEntities are entities that cannot be simultaneously served by unique actions — a high count relative to entityCount means the system has more demand than capacity. structuralFindings are observed structural patterns (set detect_antipatterns to true).",
+      "parameters": [
+        {"name": "source", "type": "string", "description": "EN source code describing the system", "required": true},
+        {"name": "invariants", "type": "string", "description": "Structural rules to check, one per line", "required": false},
+        {"name": "detect_findings", "type": "string", "description": "Set to 'true' to detect structural findings", "required": false}
+      ]
+    },
+    {
+      "name": "detail",
+      "description": "Deep structural metrics. Output: landmarks are flow points where the graph diverges or converges, with stage names. entropy is normalized structural disorder (0-1, higher = more complex, irregular structure). nodeRemovalThreshold is the fraction of random node removals before the system fragments. dominator shows which nodes control downstream flow — every path from root to a dominated node must pass through the dominator. minCuts are minimum vertex cuts across source-sink pairs (cutSize = nodes to remove to disconnect that pair).",
+      "parameters": [
+        {"name": "source", "type": "string", "description": "EN source code describing the system", "required": true}
+      ]
+    },
+    {
+      "name": "categorize",
+      "description": "Auto-discover subsystem boundaries from dependency structure. Output: interfaceNodes have subsystemOverlap 0-1 measuring how much a node spans multiple subsystems (0 = fully within one subsystem, 1 = equally shared across all).",
+      "parameters": [
+        {"name": "source", "type": "string", "description": "EN source code describing the system", "required": true}
+      ]
+    },
+    {
+      "name": "distance",
+      "description": "Shortest path between two nodes. Output: dominators are nodes on the path where every alternative route must also pass through. pathRedundancy measures how many alternative paths exist between the two nodes — lower means more redundancy (null if nodes are in different components). bridgeEdgesOnPath counts edges whose removal would disconnect the graph.",
+      "parameters": [
+        {"name": "source", "type": "string", "description": "EN source code", "required": true},
+        {"name": "from", "type": "string", "description": "Starting node name", "required": true},
+        {"name": "to", "type": "string", "description": "Target node name", "required": true}
+      ]
+    },
+    {
+      "name": "diff",
+      "description": "Compare two systems structurally. Output shows nodes, entities, roles, and subsystems that differ. editDistance is the total graph edit cost (sum of node insertions + deletions + edge insertions + deletions).",
+      "parameters": [
+        {"name": "source_a", "type": "string", "description": "EN source code for the first system", "required": true},
+        {"name": "source_b", "type": "string", "description": "EN source code for the second system", "required": true}
+      ]
+    },
+    {
+      "name": "trace",
+      "description": "Follow directed data flow from A to B. Tries directed path first (needs to action to yields); falls back to undirected if no directed path exists (usesReverseEdges=true). Optional: defense_nodes checks if at least one guard node sits on every source-to-sink path.",
+      "parameters": [
+        {"name": "source", "type": "string", "description": "EN source code", "required": true},
+        {"name": "from", "type": "string", "description": "Starting node name", "required": true},
+        {"name": "to", "type": "string", "description": "Target node name", "required": true},
+        {"name": "defense_nodes", "type": "string", "description": "Comma-separated list of defense nodes to check coverage", "required": false}
+      ]
+    },
+    {
+      "name": "between",
+      "description": "How much of the system's flow passes through one node. Output: centrality is 0-1 normalized — fraction of all shortest paths in the graph that cross this node. Values above 0.3 indicate a structural coupling point; above 0.5 is a major hub. pathsThrough is the absolute count, totalPaths is the denominator.",
+      "parameters": [
+        {"name": "source", "type": "string", "description": "EN source code", "required": true},
+        {"name": "node", "type": "string", "description": "Node name", "required": true}
+      ]
+    },
+    {
+      "name": "extract",
+      "description": "Extract a subsystem as standalone EN source. boundaryInputs are entities consumed but not produced within the subsystem. boundaryOutputs are entities produced but not consumed within. Feed the extracted EN back into other tools for deeper analysis.",
+      "parameters": [
+        {"name": "source", "type": "string", "description": "EN source code", "required": true},
+        {"name": "subsystem", "type": "string", "description": "Name of the subsystem to extract", "required": true}
+      ]
+    },
+    {
+      "name": "impact",
+      "description": "Remove a node and measure structural effect. Output: disconnectedNodes are actions that lose their sole input source. propagation shows how disruption spreads through the graph — higher diffusion means more structural proximity to the removed node.",
+      "parameters": [
+        {"name": "source", "type": "string", "description": "EN source code", "required": true},
+        {"name": "node", "type": "string", "description": "Node to remove", "required": true}
+      ]
+    },
+    {
+      "name": "evolve",
+      "description": "Dry-run a structural change. Patch adds new actions; prefix action name with - to remove. Output includes the full diff plus newBridgeNodes and lostBridgeNodes showing how bridge structure changed.",
+      "parameters": [
+        {"name": "source", "type": "string", "description": "EN source code for the current system", "required": true},
+        {"name": "patch", "type": "string", "description": "EN source code patch to apply", "required": true}
+      ]
+    },
+    {
+      "name": "compose",
+      "description": "Merge two systems into one by linking shared entities. Use links to specify which entities from system A map to entities in system B. Output enSource is the merged EN ready for other tools.",
+      "parameters": [
+        {"name": "source_a", "type": "string", "description": "EN source code for the first system", "required": true},
+        {"name": "source_b", "type": "string", "description": "EN source code for the second system", "required": true},
+        {"name": "links", "type": "string", "description": "Entity links e.g. 'a.node1=b.node2, a.node3=b.node4'", "required": true}
+      ]
+    },
+    {
+      "name": "conserve",
+      "description": "Structural invariants, deadlock analysis, complexity, and resilience. Output: invariants are weighted entity sums that stay constant across all executions — positive coefficient means produced, negative means consumed in that ratio. depletableSets are entity groups where simultaneous depletion is irreversible. entropy is normalized structural disorder 0-1. nodeRemovalThreshold is the fraction of random node removals before fragmentation. behavioral.deficiency 0 means structure fully determines execution dynamics. behavioral.isReversible means every reachable state can return to any prior state. behavioral.hasUniqueEquilibrium means convergence to one steady state regardless of initial conditions.",
+      "parameters": [
+        {"name": "source", "type": "string", "description": "EN source code describing the system", "required": true}
+      ]
+    },
+    {
+      "name": "render",
+      "description": "SVG diagram. Only call when user explicitly asks to visualize.",
+      "parameters": [
+        {"name": "source", "type": "string", "description": "EN source code describing the system", "required": true},
+        {"name": "theme", "type": "string", "description": "Color theme: dark or light", "required": false},
+        {"name": "quality", "type": "string", "description": "Output quality: small, mid, or max", "required": false}
+      ]
+    }
+  ]
+}
+