arc-diagram-mcp

An MCP server that creates polished, interactive architecture-diagram applications instead of returning a diagram string.

Example: Netflix streaming architecture

The complete Netflix example generates three connected views: system context, application architecture, and the numbered runtime journey from pressing play to Open Connect delivery. It is an illustrative reconstruction from public material—not a claim to reproduce Netflix's full internal design—grounded in the Open Connect overview, appliance and software architecture, and AWS case study.

npm run build
node dist/index.js create examples/netflix-project.json /absolute/path/to/netflix-architecture

Give an MCP-capable agent a system description, repository, or design document. The agent distils the source into the arc-diagram contract; this server validates it and scaffolds a complete React Flow application with:

• system-context, application, runtime, lifecycle, pyramid, and reference-model dialects;

• drag, resize, lasso, keyboard nudge, text sizing, and per-element styling;

• light and dark themes;

• chrome-free ?embed=<diagramId> views;

• cropped 2× PNG exports and a self-contained offline HTML build;

• structural validation, canvas-text linting, geometric probes, UX probes, and visual baselines.

The shape is inspired by phxdev1/archy-mcp, but the output is different: Archy produces Mermaid; this project produces an editable multi-view React Flow application.

Related MCP server: Flowchart MCP

MCP tools

The MCP server deliberately has no second AI-provider dependency. The host model already understands the source; the server concentrates on a stable data contract, deterministic scaffolding, and verification.

Install from source

git clone https://github.com/ArchiJones-AI/arc-diagram-mcp.git
cd arc-diagram-mcp
npm install
npm run build

Add the built server to any MCP client that accepts a stdio server:

{
  "mcpServers": {
    "arc-diagram": {
      "command": "node",
      "args": ["/absolute/path/to/arc-diagram-mcp/dist/index.js"]
    }
  }
}

Restart the client after changing its MCP configuration.

CLI

The same engine is usable without an MCP client:

npm run build
node dist/index.js validate examples/minimal-project.json
node dist/index.js create examples/minimal-project.json /absolute/path/to/output

The second command creates the application; it does not install its dependencies or run browsers. Continue inside the generated directory:

npm install
npm run dev

Authoring flow

1. Inspect the source and choose each view's dialect from its structure or visual metaphor.

2. Call get_arc_diagram_contract and author DiagramDef objects with evidence in citations.

3. Call validate_arc_diagram_set until it returns valid: true.

4. Call create_arc_diagram_project with an absolute, empty destination.

5. Build and run the generated project's light/dark probes before taking its first visual baseline.

See the authoring contract, the minimal contract example, and the Netflix showcase.

Development

npm install
npm test

npm test compiles the server and exercises validation and deterministic project creation. The embedded template is independently typechecked during the repository smoke test.

Safety

• Creation requires an absolute output path.

• A non-empty destination is refused unless overwrite: true is explicit.

• Overwrite mode replaces scaffold-managed files but preserves unrelated files.

• Repository analysis and claim grounding remain the responsibility of the calling agent; validation proves structural consistency, not architectural truth.

License

Apache-2.0.