@endiagram/mcp

MCP server for EN Diagram — deterministic structural analysis powered by graph theory. Every result is backed by a named mathematical theorem. No AI inside the computation.

Installation

Run directly:

npx @endiagram/mcp

Or install globally:

npm install -g @endiagram/mcp

Connect

Claude Code

claude mcp add endiagram npx @endiagram/mcp

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "endiagram": {
      "command": "npx",
      "args": ["@endiagram/mcp"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "endiagram": {
      "command": "npx",
      "args": ["@endiagram/mcp"]
    }
  }
}

HTTP (zero install)

Any MCP client that supports HTTP transport:

https://api.endiagram.com/mcp

Smithery

smithery mcp add dushyant30suthar/endiagram

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | EN_API_URL | https://api.endiagram.com | API endpoint for the EN Diagram service |

Tools

Six questions about any system, plus a render tool. Every tool takes source (EN code or .en/.txt file path). Tool names are shorthand, not specs — read each description before calling; compose and equivalent are mode-based, not general analyzers.

| Tool | What it answers | Levers | |------|-----------------|--------| | structure | What is this system? Shape, stages, bridges, cycles, critical path, dominator tree, min-cuts, subsystems, actors, locations. | detect_findings=true flags risks (unguarded-sink, single-cut-path, multi-cut-path); node=X returns per-node centrality (betweenness, closeness, eigenvector). | | invariant | What's always true? Conservation laws, T-invariants (sustainable cycles), depletable sets, deficiency, reversibility. | rules (one per line) checks custom claims. Four supported shapes: no bridge that is also hub · every path from X to Y passes through at least one of [A,B,C] (precedence) · no node with centrality above N · removing any single node disconnects at most N others. | | live | Can it deadlock? Can entities overflow? Siphons, traps, unbounded cycles, structural liveness and boundedness. | — | | reachable | Can X reach Y? Path, distance, boundary crossings. from/to accept entity or action names. | defense_nodes=a,b,c checks whether guards cover every path. | | equivalent | Are two systems the same, or what changes if I change this one? | Compare mode (source_a+source_b): edit distance + spectral cospectrality. Evolve mode (source+patch): plain EN adds; - name removes; same-name replaces. | | compose | How do parts combine (merge) or how does a part stand alone (extract)? | Merge: source_a+source_b+links (a.entity=b.entity per line). Extract: source+subsystem (names come from structure.subsystems). | | render | SVG or PNG diagram. Only call when the user asks to visualize. | Themes: Editorial, Primer, Carbon (each ± isDark) or seed-derived from color=#RRGGBB. structure_layers bitmask (1=subsystems, 2=pipelines, 4=cycles, 8=forks, 16=joins, 32=hubs, 64=deadlock, 128=overflow). |

EN Syntax

One statement per line:

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

Modeling

Same name = same thing. Put all required inputs in one needs: list (AND). Give two actions the same yield-name to offer alternatives (OR). Sequence = one action consuming another's yield. Re-yield stateful resources to keep them persistent; one-shot data stays consumed. Model at the real atomic granularity — split only when the pieces could be accessed independently.

Learn more at endiagram.com.

Telemetry

@endiagram/mcp generates a random install ID on first run, stored at ~/.endiagram/install-id (mode 0600). It is sent with every request as the X-Endiagram-Install-Id HTTP header so we can correlate requests from the same install for debugging issues that the per-IP signal alone cannot track (mobile networks, VPNs, CGNAT all collapse or churn IPs).

No source code, no file paths, no environment variables, and no PII are sent. The install ID is a random opaque UUIDv4 generated locally.

A first-run notice prints to stderr (never stdout — stdout is the MCP JSON-RPC channel) with the disclosure and the opt-out instructions. The notice fires once per install and never again.

Opting out

Any of these three methods disables the install ID:

1. Set ENDIAGRAM_TELEMETRY=off as an environment variable (also accepts 0, false, no).
2. Create a file at ~/.endiagram/telemetry containing the word off.
3. Delete ~/.endiagram/install-id. (A new one is generated on next run unless option 1 or 2 is also set.)

When any of these is active, the X-Endiagram-Install-Id header is not sent at all — the server falls back to its per-IP HMAC cid for correlation, which works fine for short-term per-session tracing.

Full privacy policy: endiagram.com/privacy

License

MIT