Agentic Mermaid

io.github.adewale由 GitHub 账号 adewale 发布v0.5.6更新于 Nov 3, 2026

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

发布方自己的服务:agentic.no

已验证Streamable HTTP可网页运行开发者工具媒体与设计

概览

AI 生成的概览

渲染、校验、描述并安全编辑 Mermaid 图表,为助手输出 SVG、PNG、ASCII 或 JSON 布局。

可以做什么
  • 将 Mermaid 源码渲染为可换主题的 SVG、PNG(base64)或带宽度限制的 ASCII/Unicode 文本。
  • 校验并描述图表:解析检查、识别图表类型、警告、布局边界、无障碍树与语义事实行。
  • 用结构化操作编辑现有图表,或从空白开始按操作列表构建指定类型的新图表。
  • 在隔离沙箱中运行同步 JavaScript 调用类型化 mermaid SDK,处理声明式操作无法表达的编辑。
  • 按图表类型查询与版本匹配的变更操作模式及已解析场景几何信息。
适用场景
适合编码助手起草、换风格、审阅或增量修改流程图、时序图、类图、ER 图、状态图、时间线、架构图等图表,并导出用于文档或终端审阅。
运行要求
可使用托管端点或本地进程。本地 npm 包需 Node.js 22 或更高版本(或 Bun 1.4.0 或更高),仅支持 ESM,用 npx 启动。未声明账号、密钥或请求头。托管输入上限 64KB;更大的图表、文件或 URL 形式的 PNG 输出以及私密内容需使用本地服务器。
安装前请注意
托管调用会把图表源码或执行的代码发送到第三方服务器,机密图表不宜使用。托管端点为公开且无身份验证。execute 工具在禁用网络的沙箱中运行 JavaScript,不支持异步。托管生成的 PNG 字节可能与本地渲染不同,不在确定性保证范围内。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Agentic Mermaid,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Web executable,通过 Streamable HTTP。 远程服务在工作区中配置后即可从网页运行时运行。

交给智能体安装

把这段提示词粘贴到 Claude Code、Codex、Cursor 等智能体,或 SourceWeft 对话中。智能体会读取该服务器的安装指南,先向你展示发布者、端点和登录方式,经你同意后再把它添加到你的客户端。密钥不会写进任何命令。

阅读 https://sourceweft.com/mcp/io.github.adewale%2Fagentic-mermaid/install.md,并按其中说明把这个 MCP 服务器接入我的客户端。修改任何配置之前,先告诉我它的发布者、端点和登录方式,等我确认。不要把 API 密钥写进命令或我会提交的文件;问我密钥应从哪里获取。

查看智能体所依据的安装指南

其他 MCP 客户端

把它添加到你客户端的 mcpServers 配置中。

{
  "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.

来源:README.md,提交 6f11d6d

工具

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

输入参数code必填timeoutMs

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.

输入参数detailfamilycapability

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.

输入参数source必填options

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.

输入参数source必填optionsuseAsciitargetWidth

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.

输入参数fitToscalesource必填optionsbackgroundminLabelPx

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.

输入参数source必填

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()).

输入参数formatsource必填

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.

输入参数ops必填modesource必填

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.

输入参数ops必填family必填

版本历史

5
  1. v0.5.6最新Nov 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

评分

已满足适用检查项的 100%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通必需25 分
  • 已声明认证方式必需10 分
  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分

其他 Agentic 集成