An MCP server for architecture diagrams

Runs the real arch-lab parser and reports the line, column and offending source line, so a failure can be fixed directly. On success, reports what the model contains (diagrams, levels, counts) rather than echoing it back, plus any C4 review notes — missing technologies, unlabelled or vague relationships, bidirectional lines — which do not affect validity but are what a reviewer will raise. Use this after writing or editing any .alab file: it is the fastest way to confirm the result is both loadable and worth reviewing. Hand it text of another notation and it does not fail: it says which of the 10 notations the text is, names the tool that reads it, and asks the human which picture they meant — so do not "fix" line 1 of a document whose header names another kind. The header names the notation the rest of the document is written in; changing it converts nothing. A VALID model can also come back with a notation question appended, when the relationships read as numbered steps rather than as structure; the verdict and the counts still travel with it, and nothing about the document is wrong.

Reports when the input was already canonical, so a no-op write can be skipped. Refuses Mermaid, which has no canonical form here. Text of another notation is not a failure here: it comes back as a question naming the tool that reads it, and asks your human which picture they meant — so do not "fix" line 1 of a document whose header names another kind. The header names the notation the rest of the document is written in; changing it converts nothing.

Reads `.alab` sequence documents (first line `archlab 1.0 sequence`) and pasted Mermaid `sequenceDiagram` code, reporting the line, column and offending source line on failure. On success it summarises what the flow contains — participants, messages split by line style (solid/dotted) and by head style (none, arrowhead, cross, open, bidirectional), self-messages, how many messages carry a `desc` detail, fragments and their nesting depth, notes, and a FIT report — the rendered pixel size plus any labels too wide for their own arrow, which is the one defect a parse cannot see and a caller cannot look at — rather than echoing the document back. Use this for message flows over time; use `validate_model` for C4 structure diagrams. Passing a C4 document here says so and points you at the right tool. If the request could reasonably be any of those, ask the human which picture they want before writing; `list_example_models` shows one real document per notation to show them.

Also the way to turn a pasted Mermaid `sequenceDiagram` into an `.alab` sequence document. ALL TEN of Mermaid's arrow types survive that trip in both directions (`->` `->>` `-x` `-)` `<<->>` and their dotted twins) — an arrow is two axes here too, a line style and a head style, so nothing is approximated. The import is still lossy in other ways and the response names what was dropped. Worth a call after writing a message `desc`, which is a JSON string and therefore the one place hand-escaping goes wrong: this reports the bad escape with a line and column, and returns the canonical single-line form when it is right.

Reads `.alab` flowchart documents (first line `archlab 1.0 flowchart`) and pasted Mermaid `flowchart` / `graph` code, reporting the line, column and offending source line on failure. On success it summarises the graph — nodes by shape, how many arrows carry a guard, how many loop back, groups, the rendered pixel size — and audits the three defects a parse cannot see: decisions whose branches are unguarded (a diamond that asks a question and will not say which exit is which), nodes no arrow reaches, and nodes no arrow leaves that are not an `end`. Use this for step-by-step processes; use `validate_model` for C4 structure and `validate_sequence` for message flows over time. If the request could reasonably be any of those, ask the human which picture they want before writing; `list_example_models` shows one real document per notation to show them.

Also the way to turn pasted Mermaid `flowchart` / `graph` code into an `.alab` flowchart document, which is a one-way lossy import: the response names what was dropped, including the direction (`LR` and friends are layout, not model) and any node shape with no arch-lab counterpart.

Reads `.alab` use-case documents (first line `archlab 1.0 usecase`) and pasted Mermaid written in the actor/use-case convention, reporting the line, column and offending source line on failure. On success it summarises who can do what — actors, use cases, associations, «include»/«extend» dependencies, generalizations, each boundary's contents and the rendered pixel size — then audits the defects a parse cannot see: actors with no association at all, use cases nothing can reach, capabilities sitting outside every boundary, empty boundaries, and include/extend or generalization CYCLES, which UML forbids. Use this for who-may-do-what at a system's edge; use `validate_model` for C4 structure, `validate_sequence` for message flows and `validate_flowchart` for step-by-step processes. If the request could reasonably be any of those, ask the human which picture they want before writing; `list_example_models` shows one real document per notation to show them.

Also the way to turn pasted Mermaid into an `.alab` use-case document, which is a one-way lossy import: the response names what was dropped, including the arrowheads Mermaid draws on lines that are undirected associations in UML.

Then the audit a parse cannot do — foreign-key columns with no relationship line saying what they reference, tables with no primary key, tables joined to nothing, and self-joins. Reads `.alab` er documents (first line `archlab 1.0 er`) and pasted Mermaid `erDiagram` code. Use `validate_model` for C4 structure, `validate_sequence` for message flows, `validate_flowchart` for processes and `validate_usecase` for actors at a system's edge. If the request could reasonably be any of those, ask the human which picture they want before writing; `list_example_models` shows one real document per notation to show them.

Also the way to turn pasted Mermaid `erDiagram` code into an `.alab` document. UNLIKE the flowchart and use-case imports, this conversion is TWO-WAY AND TOTAL over the diagram: Mermaid has a real erDiagram, so both cardinalities, the solid/dashed line and every column with its type, key roles and comment all survive. Only metadata is dropped, and the response says which.

Then the coverage audit: fields with no meaning given (a name and a type and no description is a schema dump, not a dictionary), fields with no `source`, fields marked deprecated without saying what replaces them, and an enumeration of every field flagged `pii`. Reads `.alab` dict documents (first line `archlab 1.0 dict`). If the request could reasonably be any of those, ask the human which picture they want before writing; `list_example_models` shows one real document per notation to show them.

There is no Mermaid import for this kind: Mermaid has no dictionary notation.

Then the audit a parse cannot do: dependency CYCLES (a waits on b waits on a), which the parser deliberately does not look for and which make the schedule meaningless; `after` entries that constrain nothing because a sibling already waits for them; sections holding only milestones, so the band draws no bar at all; and, as information rather than a fault, items whose float exceeds their own duration. Reads `.alab` gantt documents (first line `archlab 1.0 gantt`) and pasted Mermaid `gantt` code, naming on success what that import normalised. How long each piece takes, and what can't start until it's done. Use `validate_flowchart` for the order of steps with no duration, and `validate_sequence` for messages over time. If the request could reasonably be any of those, ask the human which picture they want before writing; `list_example_models` shows one real document per notation to show them.

Also the way to turn pasted Mermaid `gantt` code into an `.alab` gantt. That import is LOSSY IN NAMED WAYS and the response lists them; this tool always answers in `.alab`, as every `format_*` tool here does. Mermaid's `crit` tag imports as the `at-risk` STATE — in Mermaid it is a decoration the author types, which is what `at-risk` is here — and NOT as a critical path: arch-lab computes that from durations and dependencies, so no tag declares it and `validate_gantt` is where the chain is reported. `crit` on a task already tagged `done` loses the `crit`, since a finished task is no longer at risk. Refused BY NAME rather than approximated, each because it would make the chart mean something else: `excludes`, `includes`, `weekend`, `weekdays`, `todayMarker`, `weekday`, `axisFormat`, `tickInterval`, `inclusiveEndDates` (a working week, an axis granularity or an end-date meaning arch-lab derives or fixes itself), `until` (an item here has a length, not an end tied to another task), sub-day durations (`ms`, `s`, `m`, `h`), and a `dateFormat` other than `YYYY-MM-DD`. Gantt charts travel as `.alab` text, as Mermaid (a plan needs a `starts` date to become one — Mermaid `gantt` has no relative axis), or as a share link.

Two of its findings exist nowhere else in arch-lab. PERIODS OUT OF ORDER: this notation never reads a period label as a date, so nothing else notices that `2024, 2019, 2025` is written out of sequence, and the diagram draws declaration order confidently. EVENTS CARRYING A DURATION OR A DEPENDENCY in their label ("three weeks", "after the freeze") — these parse perfectly and are the sign the document wants to be a gantt. Then: the same event label twice inside one period, labels that wrap past three lines when drawn, and — as information rather than a fault — periods holding a single event. Reads `.alab` timeline (first line `archlab 1.0 timeline`) and pasted Mermaid `timeline` code. What happened when, and which period it happened in. Use `validate_gantt` when the work has lengths and prerequisites, and `validate_sequence` for messages between participants over time. If the request could reasonably be any of those, ask the human which picture they want before writing; `list_example_models` shows one real document per notation to show them.

Also the way to turn pasted Mermaid `timeline` code into an `.alab` timeline. Mermaid holds everything a timeline says — a period is a label and an event is a label — so nothing about the diagram is approximated in either direction. Import normalises two spellings rather than losing them — a continuation row (a line beginning `:`) folds into the period above it, and `<br>` becomes a real newline — and refuses BY NAME `section` (Mermaid groups periods one level above the period; arch-lab has only the period itself, so flattening would either strand the period labels or merge bands you separated) and a period row listing no events. Export drops what `timeline` has nowhere to put: an event's `desc` and its `#tag`s. Timelines travel as `.alab` text, as Mermaid, or as a share link.

Every finding describes a document that parses and is still wrong. THE SUBJECT NEVER TERMINATES: nothing carries `ends`, so the document says the subject reaches the last state and stays there. UNREACHABLE STATES: `ends` means the subject stops, so anything declared after a final state is stranded — each line is valid alone and only the pair is wrong. BRANCHES NOBODY KNOWS HOW TO TAKE: an `exit` with no `when` draws a departure and refuses to say what causes it. STATES THAT READ AS STEPS: a state is a place the subject can BE ("Paid"), not something somebody does ("Take payment") — a document of imperatives is a flowchart written in this notation, and this is the only place that will say so. And, when there are no branches at all, that the document is a milestone timeline. Reads `.alab` lifecycle only. What one thing went through, and where it can end up. Use `validate_flowchart` when the picture is steps and decisions rather than one thing moving, and `validate_timeline` when nothing branches. If the request could reasonably be any of those, ask the human which picture they want before writing; `list_example_models` shows one real document per notation to show them.

ONE DIALECT IN AND ONE OUT: there is no Mermaid lifecycle to convert from or to, for the reason `validate_lifecycle` gives. What the grammar refuses BY NAME, each because accepting it would make this an arbitrary graph — which is the flowchart: an edge between two states (`to`, `next`, `then`, `goes`, `after` — the track IS the order the states are written in), a `rejoins` naming a state declared LATER (a forward shortcut along the track), an `exit` nested inside another (branch depth is one), and a second `subject`. Lifecycles travel as `.alab` text or as a share link.

.alab and JSON are lossless in both directions. Mermaid is a one-way, lossy export of a SINGLE diagram (geometry, tags, icons, drill-down links and traceability are dropped) — good for embedding a picture in a README, never as a source of truth. C4 models only: a sequence document has no Mermaid export here (Mermaid sequenceDiagram is import-only, via format_sequence) — sequence documents travel as .alab text. Text of another notation is not a failure here: it comes back as a question naming the tool that reads it, and asks your human which picture they meant — so do not "fix" line 1 of a document whose header names another kind. The header names the notation the rest of the document is written in; changing it converts nothing.

Use this to orient in an unfamiliar model, or to find which diagram a change belongs in, before fetching or editing anything. Text of another notation is not a failure here: it comes back as a question naming the tool that reads it, and asks your human which picture they meant — so do not "fix" line 1 of a document whose header names another kind. The header names the notation the rest of the document is written in; changing it converts nothing.

Read it BEFORE writing one of those by hand — significant indentation and order-free attributes are easy to guess wrong. It does NOT cover the other 5 notations (flowchart, usecase, er, dict, tree): for those, fetch a bundled document with list_example_models and get_example_model, which is the parser-verified reference for their grammar. Also available as the resource archlab://syntax.

Call this BEFORE writing an `@slug` on a node line, because a wrong slug is the one authoring mistake no validator will ever report: an unknown slug does not fail anywhere — the canvas silently falls back to the node type's generic icon — so a guessed `@postgres` quietly renders the wrong picture (searching "postgres" finds the real slug, `postgresql`). Icons this registry lacks can be supplied by the document itself with a `customicon <slug> "Name" "<svg>…"` header line — see the header section of the syntax reference. A query with several plausible matches and nothing actually CALLED that comes back as a question for you to ask your human, not a list: do not take the first. ("postgres" is a declared alias and resolves silently; "sql" names nothing and asks.)

THE TOOL TO CALL WHEN A REQUEST FITS MORE THAN ONE NOTATION: the grouping says what each kind is for and each entry is a real document, so it is what to show a human who has to choose — and what stops an agent that only knows arch-lab draws C4 from writing a plan, a schema or a lifecycle as boxes and lines. Ids are unique across every notation, so an id alone names a document.

On success, reports the shape — how many nodes, how many are leaves, how deep it runs — plus the defects a parse cannot see: a branch with one child, which is a rename rather than a breakdown; a leaf that fills none of the columns the document promised; depths left unnamed when others are named; and one branch far deeper than its siblings. What breaks down into what, all the way down.

Byte-identical on text that is already canonical, so it is safe to run on every save.

Returns the QUESTION each one answers, the fact that separates the pairs readers actually confuse (C4 against a tree, a gantt against a timeline, a flowchart against a lifecycle), the header line each document opens with, and the validator to check it with. Call this BEFORE writing any `.alab`, when a request could fit more than one kind. It deliberately does not rank: it has one sentence and you have the conversation behind it, so a confident wrong ranking would be worse than none. If two still fit, put both to your human.

The document is encoded into the URL fragment, which browsers never send to a server — nothing is uploaded or stored. Refuses documents too large to fit a link that would survive being pasted into chat or mail — and when a smaller, diagram-scoped link does fit, it offers those and asks your human which the reader actually needs rather than choosing for them. Can optionally expire after a number of days. The format argument applies to the C4 readings; every other kind is detected from its first line.