archon-mcp

MCP server for generating AND iteratively editing C4 architecture diagrams via AI agents. Works with Cursor AI, Claude Desktop, Windsurf, and any MCP-compatible client. v5 ships an additional browser-worker build used by the Archon Forge plugin to drive the same toolset directly from the browser.

Generates JSON files loadable in the Archon visual architecture tool.

What's new in v5

• Full CRUD tool surface (update_*, delete_*, move_elements, clear_deploy_metadata, get_elements, get_project_meta).
• load_project (stdio) — counterpart to save_project. Lets agents edit existing architecture.json files iteratively (load → mutate → save).
• Browser-worker build at dist-browser/worker.js exposing the same tools (minus setup_* / load_project / save_project) plus load_project_state and get_operations for in-browser plugins.
• Operation log — every state-mutating tool emits a typed McpOperation that the Forge plugin replays on the host's Redux project (additive, undo-able).
• Agent Skill bundle at skill/archon-mcp/ shipped on npm install — SKILL.md, REFERENCE.md (auto-generated), COOKBOOK.md, WORKFLOWS.md, PROMPTS.md, ARCHITECTURE.md, schemas/, examples/. Install into a project with the new MCP tool setup_archon_skill (or npx archon-mcp --setup-skill).
• See COOKBOOK.md for the 8 canonical user-prompt → tool-call sequences.

Features

• 19 tools — create projects, add systems, containers, users, relationships, groups, integration layers, business scenarios, ports, deploy metadata, auto-layout, and auto-install Cursor rules
• Stateful — project accumulates across tool calls within a session
• Smart Visibility — parent systems are automatically included in integration layers if their containers are visible
• Custom Anchor Points (Ports) — add specific connection points to elements for cleaner diagrams with many relationships
• Auto Layout — automatic positioning of all elements with relationship routing and overlap prevention
• Deploy Metadata — per-version ops metadata (Admin/Monitor/Logs/Config/Infra) for systems, version-independent for containers
• Markdown Support — descriptions and deploy metadata fields accept Markdown formatting
• Name-based references — all element references use names (auto-resolved to UUIDs)
• Full C4 model — systems, containers (App/DB/Bus), users, relationships with technologies and endpoints
• Integration layers — multiple diagram views showing different subsets of the architecture
• Business scenarios — step-by-step data flow narratives with per-step annotations
• Visual groups — infrastructure boundaries (Kubernetes, VPC, DMZ)
• Built-in quality rules — tool descriptions guide AI agents to produce comprehensive architectures
• One-command Cursor Rule setup — setup_cursor_rule installs quality requirements into any project

Quick Start

Cursor AI

Add to your Cursor MCP settings (Cursor Settings → MCP → Add New MCP Server):

• Name: archon-mcp
• Type: command
• Command: npx -y archon-mcp

Or add a .cursor/mcp.json file to your project root:

{
  "mcpServers": {
    "archon-mcp": {
      "command": "npx",
      "args": ["-y", "archon-mcp"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "archon-mcp": {
      "command": "npx",
      "args": ["-y", "archon-mcp"]
    }
  }
}

Windsurf / Other MCP Clients

Same pattern — configure the MCP server with command npx and args ["-y", "archon-mcp"].

Setting Up Quality Rules (Recommended)

After configuring the MCP server, ask your AI agent:

"Run setup_cursor_rule to install the Archon quality rules"

This creates .cursor/rules/archon.mdc in your project with:

• Minimum element counts (6-12 systems, 40+ relationships, 3-5 business scenarios)
• Thinking checklist (databases, messaging, security, observability, edge)
• Tool workflow order
• Color scheme and detail requirements

Without this rule, agents may produce minimal architectures. With it, they generate production-grade diagrams.

Usage

Once configured, just ask your AI agent:

"Create an architecture diagram for an e-commerce platform"

"Design a banking infrastructure with microservices"

"Draw a C4 diagram for a real-time messaging system"

The agent will call the tools in sequence and produce a JSON file you can load in Archon.

Tools

| Tool | Description | |------|-------------| | setup_cursor_rule | Install Archon quality rules into .cursor/rules/ | | create_project | Initialize a new architecture project | | add_systems | Add systems (bounded contexts) | | add_containers | Add containers: App, DB, or Bus | | add_users | Add actors/personas | | add_relationships | Add connections between elements | | add_groups | Add visual boundaries (K8s, VPC, DMZ) | | set_deploy_metadata | Set ops metadata (Admin/Monitor/Logs/Config/Infra) on systems & containers | | add_layer_groups | Add folders for organizing layers | | add_integration_layers | Add diagram views with element visibility | | add_scenario_groups | Add folders for organizing scenarios | | add_business_scenarios | Add step-by-step data flow narratives | | add_scenario_steps | Append steps to existing business scenarios | | update_scenario_step_elements | Modify include/exclude for a specific scenario step | | add_scenario_step_comments | Add per-step element and relationship comments | | add_ports | Add custom anchor points (ports) to elements | | get_project_info | Get project summary and element counts | | auto_layout | Compute optimal positions, prevent overlaps, route relationships | | save_project | Save project to JSON file |

Workflow

 1. create_project("My Architecture")
 2. add_systems([...])                   — 6-12 systems
 3. add_containers([...])                — 3-6 per system (App/DB/Bus)
 4. add_users([...])                     — 3-5 actors
 5. add_relationships([...])             — 40+ connections
 6. add_groups([...])                    — infrastructure boundaries
 7. set_deploy_metadata([...])           — ops metadata on systems & containers
 8. add_layer_groups([...])              — layer folders
 9. add_integration_layers([...])        — 3-5 views (one isDefault:true)
10. add_scenario_groups([...])           — scenario folders
11. add_business_scenarios([...])        — 3-5 step-by-step flows
12. add_scenario_steps([...])            — (optional) append steps
13. update_scenario_step_elements([...]) — (optional) fine-tune steps
14. add_scenario_step_comments([...])    — (optional) per-step annotations
15. add_ports([...])                     — anchor points (optional)
16. auto_layout()                        — REQUIRED before save
17. save_project("architecture.json")

Markdown Support

All description fields on Systems, Containers, Users, Groups, Relationships, and Business Scenarios support Markdown formatting.

All deploy metadata fields (administration, monitoring, logging, configuration, infrastructure) also support Markdown.

Deploy Metadata (Admin / Monitor / Logs / Config / Infra)

Operational metadata has different storage depending on element type:

| Element | Storage | Version behavior | |---------|---------|-----------------| | System | versionData[version] | VERSION-SPECIFIC — each system version has its own ops links | | Container / DB / Bus | deployMetadata | VERSION-INDEPENDENT — stored directly on the element |

Use set_deploy_metadata to set these in bulk:

set_deploy_metadata({ items: [
  // System — specify version (defaults to activeVersion or "latest")
  { name: "User Service", version: "2.0.0",
    administration: "[Admin Panel](https://admin.example.com)",
    monitoring: "Grafana dashboard: `user-service-prod`",
    infrastructure: "K8s namespace: `user-svc`, 4 CPU, 8GB RAM" },

  // Container — no version needed (version-independent)
  { name: "API Server",
    monitoring: "Datadog APM: `api-server`",
    logging: "ELK: `api-server-*` index pattern" }
]})

Auto Layout

The auto_layout tool must be called after all elements are added and before save_project. It:

1. Arranges containers in a grid within each system (sorted: App → DB → Bus)
2. Orders systems using relationship topology (BFS from source systems)
3. Keeps grouped systems clustered within their group boundary
4. Places users at the top of the diagram
5. Calculates system and group bounds from child elements
6. Reassigns relationship port sides based on final positions
7. Adds control points to relationships to reduce line crossings

Optional parameters:

• maxColumnsPerSystem (default: 3) — container columns per system
• routeRelationships (default: true) — whether to add crossing-avoidance control points

Anchor Points (Ports)

Use add_ports when an element has many connections to avoid overlapping lines.

• left / right ports: work from TOP to BOTTOM (y-axis)
• top / bottom ports: work from LEFT to RIGHT (x-axis)
• In add_relationships, use fromSide, toSide, fromPortId, toPortId to connect to specific ports.

Container Types

| Type | Description | Default Color | |------|-------------|---------------| | App | Application, microservice, API, worker | #6366f1 | | DB | Database (PostgreSQL, Redis, MongoDB...) | #10b981 | | Bus | Event bus / Message queue (Kafka, RabbitMQ...) | #a855f7 |

Example

User: "Create a simple web app architecture"

Agent calls:
  create_project({ name: "Web App" })
  add_systems({ items: [
    { name: "Frontend", description: "React SPA" },
    { name: "Backend", description: "API services" },
    { name: "Data", description: "Storage layer" }
  ]})
  add_containers({ items: [
    { name: "React App", systemName: "Frontend", type: "App", technologies: ["React", "TypeScript"] },
    { name: "API Server", systemName: "Backend", type: "App", technologies: ["Node.js", "Express"] },
    { name: "PostgreSQL", systemName: "Data", type: "DB", schemas: ["users", "posts"] },
    { name: "Redis Cache", systemName: "Data", type: "DB", technologies: ["Redis"] }
  ]})
  add_users({ items: [{ name: "User", description: "End user" }] })
  add_relationships({ items: [
    { from: "User", to: "React App", description: "Uses", technology: "HTTPS" },
    { from: "React App", to: "API Server", description: "API calls", technology: "REST" },
    { from: "API Server", to: "PostgreSQL", description: "Queries", technology: "SQL" },
    { from: "API Server", to: "Redis Cache", description: "Caching", technology: "Redis Protocol" }
  ]})
  set_deploy_metadata({ items: [
    { name: "API Server", monitoring: "Datadog APM", logging: "ELK stack" },
    { name: "PostgreSQL", infrastructure: "RDS `db.r6g.xlarge`, Multi-AZ" }
  ]})
  add_integration_layers({ items: [{ name: "Full View", isDefault: true }] })
  auto_layout()
  save_project({ fileName: "web-app.json" })

Loading in Archon

1. Run the Archon app
2. Click Load Project in the toolbar
3. Select the generated .json file
4. Explore the architecture with layers, scenarios, and element details

Manual Cursor Rule Setup

If you prefer to set up the rule manually instead of using setup_cursor_rule, create .cursor/rules/archon.mdc:

---
description: Archon C4 architecture generation via MCP tools
alwaysApply: true
---

# Archon MCP — Architecture Generation Rules

When asked to create architecture diagrams, use archon-mcp tools.

## Requirements
- 6-12 systems, 3-6 containers per system, 3-5 users, 40+ relationships
- 3-5 integration layers (one isDefault:true), 3-5 business scenarios
- Container types: ONLY "App", "DB", "Bus"
- Every relationship: fill description AND technology
- Every DB: fill schemas. Every Bus: fill topics
- Use set_deploy_metadata on every system (per version) and container/DB/Bus
- All descriptions and deploy metadata fields support Markdown
- Think about: security, observability, messaging, edge, data storage

## Deploy Metadata
- Systems: VERSION-SPECIFIC → stored in versionData[version]
- Containers/DB/Bus: VERSION-INDEPENDENT → stored in deployMetadata

## Ports (Anchor Points)
Use `add_ports` when an element has many connections.
- `left` / `right` ports: TOP to BOTTOM
- `top` / `bottom` ports: LEFT to RIGHT
- Use `fromSide`, `toSide`, `fromPortId`, `toPortId` in `add_relationships`.

Development

git clone https://github.com/alexfromgithub/archon-mcp.git
cd archon-mcp
npm install
npm run build # Includes obfuscation and minification
npm start

License

MIT