@endiagram/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 EN Diagram
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# @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.
+
+## Installation
+
+Run directly:
+
+```bash
+npx @endiagram/mcp
+```
+
+Or install globally:
+
+```bash
+npm install -g @endiagram/mcp
+```
+
+## Configuration
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "en-diagram": {
+      "command": "npx",
+      "args": ["@endiagram/mcp"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add en-diagram npx @endiagram/mcp
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `EN_API_URL` | `https://api.endiagram.com` | API endpoint for the EN Diagram service |
+
+## Tools
+
+| 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 |
+| `categorize` | Auto-discover subsystem boundaries from dependency structure |
+| `compose` | Merge two EN graphs into one with entity linking |
+
+## EN Syntax
+
+```
+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).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const EN_API_URL = process.env.EN_API_URL ?? "https://api.endiagram.com";
+async function callApi(toolName, args) {
+    try {
+        const response = await fetch(`${EN_API_URL}/api/tools/${toolName}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(args),
+        });
+        const text = await response.text();
+        if (!response.ok) {
+            return {
+                text: `API error (${response.status}): ${text}`,
+                isError: true,
+            };
+        }
+        return { text, isError: false };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+            text: `Failed to reach EN API at ${EN_API_URL}: ${message}`,
+            isError: true,
+        };
+    }
+}
+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.", {
+    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("Antipatterns to detect in the structure"),
+}, async ({ source, invariants, detect_antipatterns }) => {
+    const result = await callApi("analyze_system", {
+        source,
+        invariants,
+        detect_antipatterns,
+    });
+    return {
+        content: [{ type: "text", text: result.text }],
+        isError: result.isError,
+    };
+});
+// --- render ---
+server.tool("render", "Render an EN dependency graph as a publication-quality SVG image.", {
+    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,
+    };
+});
+// --- detail ---
+server.tool("detail", "Deep structural analysis — concurrency, flow landmarks, resilience, dominator tree, min-cuts.", {
+    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,
+    };
+});
+// --- distance ---
+server.tool("distance", "Shortest path between two nodes with subsystem crossing annotations.", {
+    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", "Structural diff between two systems — topology, role, and subsystem changes.", {
+    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 node A to node B with role and subsystem annotations.", {
+    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 annotate"),
+}, 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,
+    };
+});
+// --- extract ---
+server.tool("extract", "Extract a named subsystem as standalone EN source code.", {
+    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", "Blast radius — remove a node and see what disconnects.", {
+    source: z.string().describe("EN source code describing the system"),
+    node: z.string().describe("Node to remove for impact analysis"),
+}, 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 architectural changes — apply a patch and see the structural delta.", {
+    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,
+    };
+});
+// --- between ---
+server.tool("between", "Betweenness centrality for a node — what fraction of all shortest paths flow through it.", {
+    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-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,
+    };
+});
+// --- compose ---
+server.tool("compose", "Merge two EN graphs into one with entity linking.", {
+    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,
+    };
+});
+// --- start server ---
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("Failed to start EN Diagram MCP server:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@endiagram/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for EN Diagram — structural analysis for any system",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "endiagram-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "keywords": ["mcp", "en-diagram", "structural-analysis", "graph-theory", "dependency-graph"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dushyant30suthar/TheEmergentNarrative",
+    "directory": "mcp"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}