it-architecture — MCP server for architecture drawings

An MCP server that turns a text description of an IT architecture into a standalone .svg drawing, in a choice of visual styles.

It is built to run entirely on your VDI:

• No dependencies. Pure Python standard library — nothing to pip install, no wheels to get through a proxy. Python 3.8+ is all you need.
• No network. No rendering service, no headless browser, no icon CDN, no telemetry. The layout engine, the ~60 component icons and the SVG writer are all in this repository.
• No surprises in the output. Every SVG is self-contained: no <script>, no external fonts, no embedded rasters. Safe to commit to git, paste into Confluence/SharePoint, or open in Inkscape or a browser.

customer [user]     "Customer"                 ┌──────────┐      ┌──────────┐
alb      [lb]       "Application LB"           │ Customer │─────▶│   ALB    │─ ─ ▶ …
api      [service]  "Payments API"             └──────────┘      └──────────┘
customer -> alb : "HTTPS"
alb -> api

---

1. Install

Nothing to build — the checkout is the install.

Windows (C:\Tools\MCP)

cd C:\Tools\MCP
git clone <this-repo> mcp-architecture
cd mcp-architecture
py -3 -m itarch.cli render examples\three-tier.arch --style cloud

That writes %USERPROFILE%\architecture-diagrams\three-tier.svg. If it does, the MCP server will work too.

Linux / macOS

git clone <this-repo> ~/tools/mcp-architecture
cd ~/tools/mcp-architecture
python3 -m itarch.cli render examples/three-tier.arch --style cloud

Optionally install it as a command (itarch, itarch-mcp) — still zero dependencies: python -m pip install --user -e .

2. Connect it to your local CLI / AI tool

The server speaks JSON-RPC 2.0 and negotiates MCP protocol 2025-06-18, 2025-03-26 or 2024-11-05, whichever the client asks for. Two transports are available; pick the one your client's config wants.

A. HTTP — for clients configured with a url (pi.dev and similar)

Start the server, then point the client at it.

Windows — double-click scripts\start-mcp-http.bat, or:

C:\Tools\MCP\mcp-architecture\scripts\start-mcp-http.bat

Linux / macOS:

python3 -m itarch --http                      # 127.0.0.1:8787/mcp
python3 -m itarch --http --port 9000          # somewhere else

Client config (this is mcp.example.json):

{
  "mcpServers": {
    "it-architecture": {
      "url": "http://127.0.0.1:8787/mcp",
      "lifecycle": "eager",
      "directTools": true
    }
  }
}

Check it is up at any time — curl.exe http://127.0.0.1:8787/ returns a one-line health page.

lifecycle: eager means the client connects at startup, so the server has to already be listening. To start it automatically at logon (per-user Scheduled Task, no admin rights):

cd C:\Tools\MCP\mcp-architecture
powershell -ExecutionPolicy Bypass -File .\scripts\install-autostart.ps1
Start-ScheduledTask -TaskName 'it-architecture MCP'      # start now, don't wait for logon

-Port 9000, -OutputDir D:\diagrams and -Uninstall are supported.

B. stdio — for clients that launch the server themselves

Nothing to start by hand; the client spawns it. See mcp.stdio.example.json:

{
  "mcpServers": {
    "it-architecture": {
      "command": "python",
      "args": ["-m", "itarch"],
      "env": { "PYTHONPATH": "C:\\Tools\\MCP\\mcp-architecture" }
    }
  }
}

Claude Code has a shorthand for the same thing:

claude mcp add it-architecture --env PYTHONPATH=$HOME/tools/mcp-architecture -- python3 -m itarch
claude mcp list        # should show: it-architecture: connected

C. No MCP client at all

The same engine has a plain CLI:

itarch render mydiagram.arch --style blueprint -o ./docs/img
itarch render mydiagram.arch --all-styles          # one file per style
itarch check  mydiagram.arch                       # validate, don't draw
itarch convert mydiagram.arch --to json
itarch styles | itarch types | itarch guide

(Without pip install, use python3 -m itarch.cli ….)

3. Where files go

ITARCH_OUTPUT_DIR, falling back to ~/architecture-diagrams (on Windows, C:\Users\<you>\architecture-diagrams). Every call can override it with output_dir. Alongside each SVG the server writes a .arch source file, so a diagram can be edited and re-rendered later instead of being described from scratch.

Because the HTTP transport hands back file paths, the server and the client have to see the same filesystem — which they do when both run on your machine. That is the intended deployment; the server is not built to be shared.

---

Tools exposed over MCP

Tool	What it does
get_authoring_guide	The full notation, styles and icon list. The agent should read this first.
render_architecture	Draw a diagram, save .svg (one or several styles at once). Also answers to draw_diagram_svg.
render_all_styles	Same diagram in every style, so a human can pick.
preview_architecture	Return the SVG markup inline instead of writing a file.
validate_architecture	Parse only; reports every error at once plus warnings.
convert_notation	DSL ⇄ JSON spec, normalised.
list_styles	The available looks and what each is good for.
list_node_types	Every component icon, its category and aliases.

Layout is fully automatic — layering, ordering, crossing reduction, edge routing and group boxes. Coordinates are never part of the input.

render_architecture is also advertised as draw_diagram_svg (identical behaviour). Some clients only expose tools through a keyword search over tool names; without a name containing "draw", "diagram" or "svg", a model asked to "draw this and export it as SVG" searches, finds nothing, and wrongly concludes the server cannot do it. The informational tools also end their output by naming the drawing tool, for the same reason.

Prompts — making it part of the workflow

Beyond tools, the server offers MCP prompts, which most clients surface as slash commands or a menu. Picking one and typing a description is the whole workflow; no tool call to spell out.

Prompt	Arguments	What it does
architecture_diagram	description*, style, direction	Plain English in, SVG out.
restyle_diagram	source*, style	Redraw an existing .arch/.json in another style, or in all of them.
review_architecture	source*	Validate, comment on what stands out, then draw.
diagram_notation	—	Load the authoring guide so the agent reaches for the tool from then on.

If your client does not support prompts, docs/agent-instructions.md has a short rule to paste into its system prompt / rules file instead. Note that a client with "lifecycle": "eager" caches the tool and prompt list at connect, so changes need a server restart and a fresh session.

The notation

title: Payments platform
subtitle: Target state, Q3
direction: LR                      # LR (default), RL, TB, BT

group vpc "Production VPC" [cloud] {
  group public "Public subnet" [zone] {
    alb [lb] "Application LB" : "TLS 1.3 termination"
  }
  group private "Private subnet" [zone] {
    api    [service]  "Payments API" : "Java 21" {badge: PCI}
    ledger [postgres] "Ledger" : "PostgreSQL 16" {shape: cylinder}
  }
}
customer [user] "Customer"

customer -> alb : "HTTPS"
alb -> api : "mTLS"
api -> ledger : "SQL" {style: dashed}
api <-> idp : "OIDC"

• Components: id [type] "Label" : "sublabel" {badge:…, shape:…, accent:…}
• Connections: -> <- <-> -- (no arrow) ..> (dotted) ==> (thick), chains (a -> b -> c), labels after :
• Groups nest freely; kinds are zone, cloud, region, cluster, onprem, external, plain. Declare a component inside its group, or declare it up front and list its bare id inside the group block — a bare id that names a known component moves it, it is not a redeclaration
• # and // start comments

Everything is equally expressible as JSON — see examples/microservices.json, or call convert_notation.

Styles

Style	Use it for
cloud (default)	Public-cloud reference look: white service cards, colour-coded icon tiles, dashed VPC/subnet zones.
azure	Cool corporate blue, square cards with an accent bar.
material	Light product-doc look, soft cards, curved connectors.
c4	C4 model: filled boxes with [type] stereotypes.
blueprint	Dark navy grid paper, monospaced, orthogonal — network and infra plans.
whiteboard	Hand-drawn workshop sketch. Signals "draft, let's discuss".
minimal	Monochrome line art for print, ADRs and PDFs.
neon	Dark presentation style with glowing accents.
slate	Understated enterprise deck style.

Aliases work too: aws→cloud, gcp→material, dark→neon, print/bw→minimal, sketch→whiteboard, infra→blueprint.

Component icons

About 60 glyphs across clients, compute, network, storage, data, integration, security and ops — server, service, function, container, k8s, database, nosql, cache, bucket, queue, topic, stream, gateway, lb, cdn, firewall, waf, auth, secret, monitor, logs, ci, user, browser, mobile, mainframe, thirdparty, …

Everyday names are aliased, so postgres, rds, lambda, eks, kafka, s3, sqs, redis, splunk all resolve to the right glyph. Unknown types degrade to a plain box rather than failing.

Examples

python3 -m itarch.cli render examples/three-tier.arch   --style cloud
python3 -m itarch.cli render examples/network-zones.arch --style blueprint
python3 -m itarch.cli render examples/c4-context.arch    --style c4
python3 -m itarch.cli render examples/event-driven.arch  --all-styles

Development

python3 -m unittest discover -s tests -v

105 tests, no fixtures to install. They cover the DSL, the spec validator, the layout invariants (no overlapping nodes, groups contain their members, nothing escapes its band, content fits the declared canvas), SVG well-formedness for every style, XML escaping of untrusted labels, the MCP protocol handling including malformed input and protocol downgrade, and the HTTP transport driven over a real socket.

Layout, briefly

itarch/layout.py is a compact Sugiyama pipeline: DFS cycle-breaking → longest-path layering → dummy nodes for long edges → barycenter crossing reduction → one reserved cross-axis band per group (siblings that never share a layer share the space) → exact isotonic (PAVA) 1-D placement inside each band → group boxes → edge routing. Everything is computed in layer/cross coordinates and mapped to screen space at the very end, which is why LR/RL/TB/BT all come out of the same code path.

Adding a style

Add one entry to STYLES in itarch/styles.py. The renderer, layout engine and icon set need no changes.

Adding an icon

Add a draw function and one ICONS entry in itarch/icons.py. Glyphs are authored in a 0..100 box using plain SVG primitives.

Security notes

• On stdio the server opens no socket at all. On --http it binds 127.0.0.1 only by default and validates the Origin header, so a web page you happen to have open cannot reach it by DNS rebinding. There is no authentication, so --host 0.0.0.0 is for trusted networks only — the server warns you when you do it.
• It never reads a file it was not given a path to; the only writes are the .svg/.arch files in the output directory, with filenames sanitised to a single path component.
• Labels are XML-escaped, so text coming from a ticket or a log cannot inject markup into the drawing.
• Output is deterministic: the same input always produces byte-identical SVG, which keeps diagrams reviewable in git.