Agentic Mermaid

io.github.adewalePublished by GitHub account adewalev0.5.6Updated Nov 3, 2026

Render, verify, describe, and safely edit Mermaid diagrams through MCP.

The publisher's own server: agentic.no

VerifiedStreamable HTTPWeb executableDeveloper ToolsMedia & Design

Overview

AI-generated overview

Renders, verifies, describes and safely edits Mermaid diagrams, returning SVG, PNG, ASCII or JSON layout for an assistant.

What you can do
  • Render Mermaid source to themeable SVG, PNG (base64) or ASCII/Unicode text with a width bound.
  • Verify and describe diagrams: parse checks, detected family, warnings, layout bounds, accessibility tree and semantic fact lines.
  • Edit existing diagrams with typed mutation operations, or build a new diagram from blank by folding an op list over a chosen family.
  • Run synchronous JavaScript against a typed mermaid SDK in an isolated sandbox for edits the declarative ops cannot express.
  • Look up version-matched mutation schemas and resolved-scene geometry per diagram family.
When to use it
Useful when a coding agent needs to draft, restyle, review or incrementally edit diagrams such as flowcharts, sequence, class, ER, state, timeline or architecture charts, and export them for documents or terminal review.
Requirements
Either the hosted endpoint or a local process. The local npm package needs Node.js 22 or later (or Bun 1.4.0 or later) and is ESM-only; start it with npx. No accounts, keys or headers are declared. Hosted inputs are capped at 64KB; larger diagrams, file or URL PNG output and private work need the local server.
Before you install
Hosted calls send your diagram source or executed code to the third-party server, so avoid confidential diagrams there. The hosted endpoint is public and unauthenticated. The execute tool runs JavaScript in a sandbox with network access disabled and no async support. Hosted PNG bytes may differ from local rendering and are not covered by the determinism guarantee.

Installation

In SourceWeft

  1. Open Agentic Mermaid in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.adewale%2Fagentic-mermaid/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "agentic-mermaid": {
      "type": "http",
      "url": "https://agentic-mermaid.dev/mcp"
    }
  }
}

README

Agentic Mermaid

Beautiful diagrams, made with your agent.

Agentic Mermaid helps coding agents create styled diagrams from Mermaid source and edit existing diagrams through typed operations. Export SVG or PNG for documents, and ASCII or Unicode for terminal review.

It is forked from lukilabs/beautiful-mermaid. Published on npm as agentic-mermaid; the GitHub repository is adewale/agentic-mermaid; the live site is agentic-mermaid.dev.

[A login flow with credential validation, an MFA decision, two retry paths, session creation and a dashboard, rendered in the hand-drawn style]

A login flow with MFA, rendered directly by Agentic Mermaid. Mermaid source · Style and reproduction command

Live Demo & Samples · Live Editor

Ask your coding agent:

Read Instructions_for_agents.md in this repository, or https://agentic-mermaid.dev/llms.txt if you don't have a checkout. Draw Browser → API → Database using the hand-drawn style and nord-light palette. Verify it, then return the Mermaid source and an SVG.

Agent setup and skills · Try the same diagram in JavaScript

Docs: docs index · getting started · agent guide · agent API cookbook · design system · skills · fork differences · vs Mermaid & Beautiful Mermaid · changelog

Why Agentic Mermaid

Choose a built-in style, or keep your diagram's colors and fonts in a JSON style file. Inspect the rendered result before publishing.

You wantAgentic Mermaid gives you
An agent to draft the diagramMermaid source plus a verified render path
Beautiful defaultsBuilt-in looks such as watercolor, blueprint, hand-drawn, and publication-figure
Brand fitStyle + Palette stacks and custom JSON palettes you can keep in your repo
Safe edits laterparseRegisteredMermaid → family narrower → mutate → verifyMermaid → serializeMermaid
Reviewable artifactsSVG, PNG, ASCII, Unicode, and JSON layout from the same source

The agent workflow is the guardrail behind the polish: agents should not guess from pixels, concatenate strings, or regenerate whole diagrams when a structured edit is available.

Highlights

  • Discover supported diagrams and edits — am capabilities --summary indexes what the installed version supports, including registered extensions; am capabilities --family <id> gives one family's full edit schema.
  • SVG, PNG, ASCII, Unicode, JSON — export images, review diagrams in the terminal, or inspect positions as JSON layout.
  • Render SVG without a browser — the synchronous JavaScript API runs without a DOM or Puppeteer.
  • Composable styles — { style: ['hand-drawn', 'dracula'] } combines a look with a palette. Set colors, fonts, strokes, fills and backdrops in a JSON style. seed re-rolls the ink, never the layout.
  • Match your editor's colors — choose a built-in palette, theme from two colors, or adapt a VS Code theme with Shiki.
  • Agent-native editing — use typed operations for modeled syntax. Class and Timeline retain unmodeled statements alongside typed edits; source-preserving mode keeps every authored line an edit does not touch (comments, indentation, quoting) and covers selected opaque Class and Flowchart operations.
  • CLI + MCP + library — use am, connect agentic-mermaid-mcp, or import agentic-mermaid/agent for rendering and editing. See the API reference for the other library and browser entry points.

Installation

Requires Node.js 22 or later, or Bun 1.4.0 or later. The package is ESM-only; use import, or dynamic import() from CommonJS.

bash
npm install agentic-mermaid       # or: bun add agentic-mermaid / pnpm add agentic-mermaidnpx --no-install agentic-mermaid --help

The am … examples below name the published bin. After a project-local npm install, invoke it from a shell as npx --no-install agentic-mermaid … (or from an npm script as am …). From a source checkout, use bun run bin/am.ts … instead.

Output quick starts

Use agentic-mermaid/agent when you want one import path for styled renders, output formats, and the structured edit API.

SVG

Save this as diagram.mjs:

js
import { writeFileSync } from 'node:fs'import { renderMermaidSVG } from 'agentic-mermaid/agent'
const svg = renderMermaidSVG(`flowchart LR  Browser --> API --> Database`, {  style: ['hand-drawn', 'nord-light'],  security: 'strict',})
writeFileSync('diagram.svg', svg)
bash
node diagram.mjs

Open diagram.svg to see Browser → API → Database in the hand-drawn style with the nord-light palette.

PNG

ts
import { writeFileSync } from 'node:fs'import { renderMermaidPNG } from 'agentic-mermaid/agent'
const png = renderMermaidPNG(`flowchart TD  Start --> Done`, {  fitTo: { width: 1200 },  background: '#fff',})
writeFileSync('diagram.png', png)

CLI equivalent:

bash
am render diagram.mmd --format png --output diagram.png

ASCII / Unicode

ts
import { renderMermaidASCII } from 'agentic-mermaid/agent'
const unicode = renderMermaidASCII(`flowchart LR  A --> B`)const ascii = renderMermaidASCII(`flowchart LR  A --> B`, { useAscii: true })

Agent quick start

If your coding agent can read repo files, point it at:

If it only has shell access:

bash
am --agent-instructionsam capabilities --summary          # then: am capabilities --family <id>am preview diagram.mmd --security strict --openam mutate diagram.mmd --op '{"kind":"set_label","target":"API","label":"API gateway"}' --json

For an existing diagram, follow parse → narrow → mutate → verify → serialize. For a new diagram, author Mermaid source, then parse and verify it. To wire Agentic Mermaid into another repo, run npx agentic-mermaid init-agent (or bun run bin/am.ts init-agent from a source checkout); it writes a non-clobbering AGENTS.md section, root skills/ bundle, and .mcp.json sample.

Use strict preview for human inspection and mutate --op/--ops for verified one-shot or batched edits.

For multi-step MCP edits, use Code Mode execute(code) with the same mermaid.* SDK names. See the agent API cookbook for library, CLI and MCP recipes.

MCP server

Agentic Mermaid ships a Model Context Protocol server so MCP-capable agents can render and safely edit diagrams without shelling out.

After installation, start the local stdio server:

bash
npx --no-install agentic-mermaid mcp

Use the library, CLI or local MCP for private diagrams, offline work, larger inputs or local PNG files. The MCP transport guide covers HTTP/SSE and file/URL artifacts; agent setup shows how to generate a sample client configuration. The tool reference and Code Mode guide explains the available tools and multi-step edits.

An optional public, unauthenticated MCP endpoint runs at https://agentic-mermaid.dev/mcp. It accepts MCP JSON-RPC rather than REST render requests, caps inputs at 64 KB and returns PNG as base64. Hosted calls send your source or code to the server; see the privacy notice. Directory maintainers can use the MCP listing record.

Structured edit example

Change the API node's displayed label while keeping its connection to DB:

ts
import { parseRegisteredMermaid, asFlowchart, mutate, verifyMermaid, serializeMermaid } from 'agentic-mermaid/agent'
const parsed = parseRegisteredMermaid('flowchart TD\n  API --> DB')if (!parsed.ok) throw new Error('parse failed')
const flow = asFlowchart(parsed.value)if (!flow) throw new Error(`not a structured flowchart: ${parsed.value.kind}`)
const next = mutate(flow, { kind: 'set_label', target: 'API', label: 'API gateway' })if (!next.ok) throw new Error(next.error.message)
const verify = verifyMermaid(next.value)if (!verify.ok) throw new Error(JSON.stringify(verify.warnings, null, 2))
const source = serializeMermaid(next.value)console.log(source)

Output:

text
flowchart TD  API[API gateway] --> DB

The node ID is still API; its displayed label is now API gateway, and the API → DB connection remains. Verification checks for structural and geometry problems; review the rendered result and confirm it expresses your intent before saving.

Rules:

  • Use the matching exported as<Family> narrower before mutating an existing structured diagram.
  • Mutation ops use kind, not type.
  • Run verifyMermaid before every commit point.
  • Do not call mutate on opaque fallback bodies; the narrower returns null for unmodeled syntax.
  • To edit an existing file without reformatting it, use source-preserving edits: mutatePreservingSource, applyOps with mode: 'source-preserving', CLI --preserve-source, or the same MCP and editor-worker mode. Untouched lines stay byte-identical; preservation.method is canonical when an edit had to be re-serialized. For opaque Class/Flowchart inputs the mode supports Class add_member/remove_member and Flowchart set_label/rename_node; save exact source and inspect the retained portability diagnostics.

Supported diagram families

Run am capabilities --summary for the supported families and edit operations in your installed version, then am capabilities --family <id> for one family's full entry. See diagram families for syntax examples and compatibility notes.

More documentation

Live editor and examples

Contributing and reporting bugs

Report a bug with the Mermaid source, render options and the result you expected. For changes to the project, read the contributor instructions for implementation and testing rules.

To work from a source checkout, use Bun 1.4.0 or later:

bash
git clone https://github.com/adewale/agentic-mermaidcd agentic-mermaidbun installbun run buildbun run bin/am.ts --helpbun run bin/agentic-mermaid-mcp.ts   # MCP stdio server

Attribution

Agentic Mermaid is a fork of Beautiful Mermaid by Luki Labs. The ASCII rendering engine is based on mermaid-ascii by Alexander Grooff and extended for Agentic Mermaid.

License

MIT

Native Event Modeling and ZenUML authoring and rendering have documented capability and runtime contracts.

Source: README.md at commit 6f11d6d

Tools

9

execute

Execute Mermaid SDK code

Run JavaScript in an isolated sandbox; return a value. No promises, async/await, dynamic import, or type annotations. SVG/ASCII/layout enforce security:'strict', embedFontImport:false. SDK: type DiagramKind='flowchart'|'state'|'sequence'|'timeline'|'class'|'er'|'journey'|'architecture'|'xychart'|'pie'|'quadrant'|'gantt'|'mindmap'|'gitgraph'|'radar'|'sankey'|'c4'|'packet'|'kanban'|'requirement'|'treemap'|'ishikawa'|'block'|'eventmodeling'|'zenuml' type MutationOp={kind:string;[field:string]:unknown} type Result<T,E={code:string;message:string}>={ok:true;value:T}|{ok:false;error:E} type ExternalFamilyId=`family:${string}`;interface SourceLocation{readonly line:number;readonly col:number;}interface SourceMap{readonly nodes:ReadonlyMap<string,SourceLocation>;readonly edges:ReadonlyMap<string,SourceLocation>;readonly groups:ReadonlyMap<string,SourceLocation>;readonly labels:ReadonlyMap<string,SourceLocation>;readonly spans?:SourceMapSpans;}interface SourceMapSpans{readonly preserved:PreservedSourceSpans;readonly nodes:ReadonlyMap<string,SourceSpan>;readonly edges:ReadonlyMap<string,SourceSpan>;readonly groups:ReadonlyMap<string,SourceSpan>;readonly labels:ReadonlyMap<string,SourceSpan>;readonly metadata?:ReadonlyMap<string,ReadonlyMap<string,{readonly key:SourceSpan;readonly value:SourceSpan;}>>;}interface PreservedSourceSpans{readonly source:SourceSpan;readonly wrapper?:SourceSpan;readonly frontmatter?:SourceSpan;readonly initDirectives?:readonly SourceSpan[];readonly accessibilityDirectives?:readonly SourceSpan[];readonly header:SourceSpan;readonly body:SourceSpan;}interface SourceSpan{readonly start:SourceSpanPoint;readonly end:SourceSpanPoint;}interface SourceSpanPoint{readonly offset:number;readonly line:number;readonly col:number;}interface SourcePreservationReceipt{readonly version:1;readonly classification:'unsupported'|'inventory-only'|'unknown';readonly source:string;readonly header:string;readonly upstreamFamilyId?:string;readonly mermaidVersion:string;readon

ParameterscoderequiredtimeoutMs

describe_sdk

Describe Mermaid SDK operations

Return version-matched mutation operations for one diagram family, or use capability=resolved-scene for painted geometry, runtime limits and typed errors. Use detail=signatures for the compact op menu or detail=fields (default) for exact field types, required flags, enum values, defaults, and constraints. Call this before build, mutate, or execute when the family schema is not already known.

Parametersdetailfamilycapability

render_svg

Render Mermaid as SVG

Render a Mermaid source string to themeable SVG. Returns { ok, svg }. Layout is deterministic: identical input produces identical geometry. The hosted boundary forces security:'strict' and embedFontImport:false.

Parameterssourcerequiredoptions

render_ascii

Render Mermaid as text

Render a Mermaid source string to text. Returns { ok, text }. useAscii true → plain ASCII (+,-,|); false/absent → Unicode box drawing (┌,─,│). targetWidth sets a hard terminal display-cell bound; impossible bounds return a typed error.

ParameterssourcerequiredoptionsuseAsciitargetWidth

render_png

Render Mermaid as PNG

Rasterize a Mermaid source string to PNG. Returns { ok, png_base64 }. Hosted rendering uses resvg-wasm with bundled fonts; bytes may differ from the local napi renderer, so hosted PNG is a convenience surface, not part of the byte-determinism contract. For file/URL artifacts use the local stdio server.

ParametersfitToscalesourcerequiredoptionsbackgroundminLabelPx

verify

Verify Mermaid diagram

Parse and verify source, structure, and renderability. This runs the graphical pipeline. Returns { ok, family, summary, warnings, layout: { bounds, nodes, edges } } for valid diagrams and { ok: false, errors } for parse failures. `family` is the detected diagram family and `summary` a one-line description — check them: ok:true only means the diagram is structurally valid, not that it is the kind you intended. Warnings use the layout-rubric codes.

Parameterssourcerequired

describe

Describe Mermaid diagram

Describe a Mermaid diagram. format=text returns { ok, text } with one or two summary sentences; format=json returns { ok, tree } with the AX tree; format=facts returns { ok, facts } with deterministic semantic fact lines for machine checking (for example edge A -> B : label, member Duck +quack()).

Parametersformatsourcerequired

mutate

Edit Mermaid diagram

Apply a list of structured edit ops to an existing Mermaid `source` and return the edited diagram. This is the declarative counterpart to `execute`: plain JSON in, plain JSON out, no sandbox. Prefer it for straightforward edits; reserve `execute` for logic the ops don't express. Returns { ok, family, source, verify:{ ok, warnings } } on success, or { ok:false, family, opIndex, error } — where `error` names the offending field and lists the valid ones — when an op is malformed or cannot apply. Ops apply in order and are all-or-nothing: the first failing op stops the batch (its position is `opIndex`) and the input is left untouched. Each op is { "kind": <op>, …fields }. Call `describe_sdk` for the detected family before authoring unfamiliar ops; it returns compact signatures or exact field types, enum values, defaults, and constraints. Set mode to source-preserving for supported edits to opaque Class or Flowchart source. Exact edited bytes and portability warnings are retained; unsupported operations still fail atomically. This mode does not promise portable export.

Parametersopsrequiredmodesourcerequired

build

Build Mermaid diagram

Author a new Mermaid diagram from blank by folding a list of structured ops over an empty diagram of `family`. The declarative counterpart to hand-writing source. Returns the same envelope as `mutate`: { ok, family, source, verify } or { ok:false, family, opIndex, error }. Call `describe_sdk` for the family before authoring unfamiliar ops.

Parametersopsrequiredfamilyrequired

Version history

5
  1. v0.5.6LatestNov 3, 2026
  2. v0.5.5Oct 31, 2026
  3. v0.5.4Oct 30, 2026
  4. v0.5.3Oct 29, 2026
  5. v0.4.1Sep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

Other Agentic integrations