What is Agentic Mermaid?

Agentic Mermaid is an open-source Mermaid runtime for agents. It parses, verifies, mutates, serializes, and renders diagrams without a browser.

How should an agent use Agentic Mermaid?

Use the local library, CLI, or MCP server. Parse source first, narrow to the diagram family, apply structured mutations when available, verify, then serialize or render.

Where is the hosted MCP endpoint?

The hosted stateless Streamable HTTP MCP endpoint is https://agentic-mermaid.dev/mcp, with a standard discovery alias at https://agentic-mermaid.dev/.well-known/mcp.

About Agentic Mermaid

A diagram should be ready when the agent returns it

Ask for an architecture map, a launch timeline, or a product flow and the agent should return source you can keep editing plus an artifact you can use. Agentic Mermaid gives that agent the diagram language, style controls, renderer, and verification step in one workflow: SVG or PNG for pages and decks, ASCII or Unicode for text review, and layout JSON when a tool needs coordinates.

The same source can wear your brand

Styles are data: a named style, a palette-only style, a JSON record, or a stack of those pieces. Text, nodes, edges, groups, fills, strokes, and typography can follow your house style without touching the diagram's meaning. Render twice and the geometry is byte-identical; change the palette and the boxes stay put.

am render diagram.mmd --format svg > a.svg
am render diagram.mmd --format svg > b.svg
diff a.svg b.svg        # no output: identical bytes, every run, no browser

Verify before you serialize

verifyMermaid reads a parsed diagram and sorts its warnings into three tiers. Structural warnings mean the diagram is wrong: an edge anchored to nothing (EDGE_MISANCHORED), a node off the canvas (OFF_CANVAS), content that escaped its group (GROUP_BREACH). Geometric warnings mean it reads but the routing is poor: overlapping nodes (NODE_OVERLAP), a path that crosses itself (ROUTE_SELF_CROSS). Lint warnings cover cleanliness and round-trip loss. Every warning carries a stable code and a severity — errors block, warnings come back with ok: true for you to judge — so an agent runs verify the way it runs a test: check, read the code, fix, check again. The editor shows the same three tiers as you type, am verify prints them, and the MCP server returns them.

const verify = verifyMermaid(parsed.value)
if (!verify.ok) throw new Error(JSON.stringify(verify.warnings, null, 2))
// every warning: a code (EDGE_MISANCHORED), a tier (structural | geometric | lint),
// and a severity, so the fix is mechanical

Edits go through a typed tree

To add an edge with a string-based tool, you append a line and hope it parses. Agentic Mermaid parses the source into a typed tree, narrows it to a family with asFlowchart, applies one operation, and serializes back. The operation matches a known shape or returns an error, so it cannot half-apply and leave the source corrupt. Syntax the library cannot narrow is preserved verbatim, and a lossy change asks first.

const flow = asFlowchart(parseRegisteredMermaid(source).value)   // narrow to flowchart
const r = mutate(flow, { kind: 'add_edge', from: 'API', to: 'Cache' })
if (!verifyMermaid(r.value).ok) throw new Error('mutation left it broken')
const next = serializeMermaid(r.value)                 // typed tree back to text

One source, human artifacts, and tool coordinates

The same parsed diagram serializes to SVG for a web page, PNG for a deck or document, and ASCII or Unicode for a terminal. The CLI and library can also emit layout JSON — node boxes, edge points, groups, bounds, and optional route certificates — when a test, agent, or integration needs geometry instead of a picture. The text forms are the ones agents actually use: an agent reading a pull request or a CI log sees the diagram as box-drawing characters it can parse, where an image tag would be a dead link. The editor renders the visual and text tabs from the same source in the box on the left.

am render flow.mmd --format svg    > flow.svg
am render flow.mmd --format png    > flow.png
am render flow.mmd --format ascii          # box-drawing, into the terminal

The loop

These are one loop. An agent writes or parses the source, narrows it when an edit is typed, applies the requested change, verifies the result, and renders with the chosen style. Because verification runs before rendering, you can ask for a branded diagram without accepting a silent source rewrite.

The loop itself, drawn by Agentic Mermaid at build time from six lines of Mermaid.

Where it comes from

Mermaid is the text syntax these diagrams are written in; its own renderer draws them in a browser. Drawing that text without a browser has been tried before — mermaid-ascii renders Mermaid graphs as ASCII straight in a terminal. Beautiful Mermaid, from the team at Craft, is a zero-dependency TypeScript renderer that outputs both SVG and ASCII, with its ASCII engine ported from mermaid-ascii's Go. Agentic Mermaid forks Beautiful Mermaid and adds the typed editing and deterministic verification above it, so an agent can change a diagram and check it, where the renderers before it could only draw one.

Frequently asked questions

What is Agentic Mermaid?: Agentic Mermaid is an open-source Mermaid runtime for agents. It parses, verifies, mutates, serializes, and renders diagrams without a browser.
How should an agent use Agentic Mermaid?: Use the local library, CLI, or MCP server. Parse source first, narrow to the diagram family, apply structured mutations when available, verify, then serialize or render.
Where is the hosted MCP endpoint?: The hosted stateless Streamable HTTP MCP endpoint is https://agentic-mermaid.dev/mcp, with a standard discovery alias at /.well-known/mcp.