# 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`)

```bat
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

```bash
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:

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

**Linux / macOS**:

```bash
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`):

```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):

```powershell
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`:

```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:

```bash
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:

```bash
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

```bash
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

```bash
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.