{
"markdown": "\n\n# Agentic Mermaid\n\n**Beautiful diagrams, made with your agent.**\n\nAgentic Mermaid is an open-source Mermaid toolkit for people who want AI agents to create diagrams that look finished: SVG and PNG renders, ASCII and Unicode for review, deterministic layout, and Style + Palette controls for brand colors, typography, strokes, fills, and backdrops.\n\nIt is forked from [`lukilabs/beautiful-mermaid`](https://github.com/lukilabs/beautiful-mermaid). Published on npm as `agentic-mermaid`; the GitHub repository is `adewale/agentic-mermaid`; the canonical live site is [`agentic-mermaid.dev`](https://agentic-mermaid.dev/), a Cloudflare Workers deployment.\n\n\n\n[Live Demo & Samples](https://agentic-mermaid.dev/) · [Live Editor](https://agentic-mermaid.dev/editor)\n\nDocs: [docs index](./docs/) · [getting started](./docs/getting-started.md) · [agent guide](./Instructions_for_agents.md) · [agent API cookbook](./docs/agent-api-cookbook.md) · [design system](https://github.com/adewale/agentic-mermaid/blob/main/DESIGN.md) · [skills](./skills/) · [fork differences](./docs/fork-differences.md) · [vs Mermaid & Beautiful Mermaid](./docs/comparison.md) · [changelog](./CHANGELOG.md)\n\n
\n\n## Why Agentic Mermaid\n\nUse it when you want to describe a diagram in plain language and get back something you can publish without a design cleanup pass.\n\n| You want | Agentic Mermaid gives you |\n|---|---|\n| An agent to draft the diagram | Mermaid source plus a verified render path |\n| Beautiful defaults | Built-in looks such as `watercolor`, `blueprint`, `hand-drawn`, and `publication-figure` |\n| Brand fit | Style + Palette stacks and custom JSON palettes you can keep in your repo |\n| Safe edits later | `parseRegisteredMermaid` → family narrower → `mutate` → `verifyMermaid` → `serializeMermaid` |\n| Reviewable artifacts | SVG, PNG, ASCII, Unicode, and JSON layout from the same source |\n\nThe 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.\n\n## Highlights\n\n- **Descriptor-registered diagram families** — built-ins and namespaced extensions share one discovery and capability contract.\n- **SVG, PNG, ASCII, Unicode, JSON** — one resolved request with explicit graphical, terminal, and positioned-layout projections.\n- **Synchronous, zero-DOM SVG renderer** — no Puppeteer, no browser flash.\n- **Composable styles** — `{ style: ['hand-drawn', 'dracula'] }` stacks a look over a palette; discoverable full looks cover sketch, watercolor, blueprint, accessibility, print, operational, physical-media, architecture, and editorial/report use cases. Custom styles are plain JSON records any agent can author (`docs/style-authoring.md`). `seed` re-rolls the ink, never the layout.\n- **Discoverable palettes + Shiki compatibility** — a theme is a palette-only style: discover the canonical catalog at runtime, theme from two colors, or adapt a VS Code theme.\n- **Agent-native editing** — typed mutation for every registered renderable family; source-level round-trip only for opaque fallbacks containing unmodeled syntax.\n- **CLI + MCP + library** — `am`, `agentic-mermaid-mcp`, `agentic-mermaid`, `agentic-mermaid/agent`, and the browser/workerd-safe `agentic-mermaid/agent/core`. Audit reports and trusted host-resource helpers remain repository tooling instead of published runtime entry points.\n\n## Installation\n\n```bash\nnpm install agentic-mermaid # or: bun add agentic-mermaid / pnpm add agentic-mermaid\nnpx --no-install agentic-mermaid --help\nnpx --no-install agentic-mermaid mcp\n```\n\nFor repository development, install from source and run the Bun entrypoints:\n\n```bash\ngit clone https://github.com/adewale/agentic-mermaid\ncd agentic-mermaid\nbun install\nbun run build\nbun run bin/am.ts --help\nbun run bin/agentic-mermaid-mcp.ts # MCP stdio server\n```\n\n> **ESM-only.** `agentic-mermaid` ships ES modules (there is no CommonJS build);\n> `require()` consumers should use dynamic `import()` instead. Requires Node ≥ 22.\n>\n> The `am …` examples below name the published bin. After a project-local npm\n> install, invoke it from a shell as `npx --no-install agentic-mermaid …` (or\n> from an npm script as `am …`). From a source checkout, use\n> `bun run bin/am.ts …` instead.\n\n## Output quick starts\n\nUse `agentic-mermaid/agent` when you want one import path for styled renders, output formats, and the structured edit API.\n\n### SVG\n\n```ts\nimport { renderMermaidSVG } from 'agentic-mermaid/agent'\n\nconst svg = renderMermaidSVG(`flowchart TD\n Start --> Done`, { security: 'strict' })\n```\n\n### PNG\n\n```ts\nimport { writeFileSync } from 'node:fs'\nimport { renderMermaidPNG } from 'agentic-mermaid/agent'\n\nconst png = renderMermaidPNG(`flowchart TD\n Start --> Done`, {\n fitTo: { width: 1200 },\n background: '#fff',\n})\n\nwriteFileSync('diagram.png', png)\n```\n\nCLI equivalent:\n\n```bash\nam render diagram.mmd --format png --output diagram.png\n```\n\n### ASCII / Unicode\n\n```ts\nimport { renderMermaidASCII } from 'agentic-mermaid/agent'\n\nconst unicode = renderMermaidASCII(`flowchart LR\n A --> B`)\nconst ascii = renderMermaidASCII(`flowchart LR\n A --> B`, { useAscii: true })\n```\n\n## Agent quick start\n\nIf your coding agent can read repo files, point it at:\n\n- [`skills/agentic-mermaid-diagram-workflow/SKILL.md`](./skills/agentic-mermaid-diagram-workflow/SKILL.md) for diagram authoring/editing.\n- [`skills/agentic-mermaid-live-editor/SKILL.md`](./skills/agentic-mermaid-live-editor/SKILL.md) for editor changes.\n\nIf it only has shell access:\n\n```bash\nam --agent-instructions\nam capabilities --json\nam preview diagram.mmd --security strict --open\nam mutate diagram.mmd --op '{\"kind\":\"add_node\",\"id\":\"Cache\",\"label\":\"Cache\"}' --json\n```\n\nZero-install prompt for a coding agent: read `https://agentic-mermaid.dev/llms.txt` and follow the parse → narrow → mutate → verify → serialize workflow. 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.\n\nUse strict `preview` for human inspection and `mutate --op/--ops` for verified one-shot or batched edits.\n\nFor multi-step MCP edits, connect `agentic-mermaid-mcp` and use Code Mode `execute(code)` with the same `mermaid.*` SDK names. Stdio is the default transport; `agentic-mermaid-mcp --transport http` starts HTTP/SSE and managed PNG file/URL artifacts. See the [agent API cookbook](./docs/agent-api-cookbook.md) for copy-pasteable library, CLI, and MCP recipes.\n\n## MCP server\n\nAgentic Mermaid ships a Model Context Protocol server so MCP-capable agents can render and safely edit diagrams without shelling out.\n\n- **Self-hosted (default).** `agentic-mermaid-mcp` runs a stdio server exposing `execute` (Code Mode sandbox), `describe_sdk` (one family's mutation schema on demand), `render_png`, and `describe`. Package runners can use `npx -y agentic-mermaid mcp`; the `mcp` argument routes the package-name binary to the same stdio server. Add `--transport http` for HTTP/SSE with managed PNG file/URL artifacts. See [`docs/mcp-http-transport.md`](./docs/mcp-http-transport.md) and [`docs/mcp-code-mode-rationale.md`](./docs/mcp-code-mode-rationale.md).\n- **Hosted.** A stateless Streamable HTTP endpoint is available at `https://agentic-mermaid.dev/mcp` (tools: `execute`, `describe_sdk`, `render_svg`, `render_ascii`, `render_png`, `verify`, `describe`, `mutate`, `build`; 64 KB input caps). Call `describe_sdk` for compact signatures or exact fields before authoring unfamiliar ops. It is MCP JSON-RPC only, not a REST render API. Hosted `execute` runs the same `mermaid.*` facade in a Cloudflare Dynamic Worker isolate with no network; hosted PNG returns base64 only.\n\nLocal-first is the default posture: prefer the library, CLI, or a self-hosted MCP for anything sensitive, offline, larger than the hosted caps, or needing local PNG file/URL artifacts. The hosted endpoint is a public, unauthenticated convenience for zero-install render/verify/describe and bounded structured edits.\n\nDirectory maintainers can use the canonical [MCP listing record](./docs/MCP-DIRECTORY-LISTINGS.md). Hosted data handling is described in the [MCP privacy notice](./docs/MCP-PRIVACY.md).\n\n## Structured edit example\n\n```ts\nimport { parseRegisteredMermaid, asFlowchart, mutate, verifyMermaid, serializeMermaid } from 'agentic-mermaid/agent'\n\nconst parsed = parseRegisteredMermaid('flowchart TD\\n API --> DB')\nif (!parsed.ok) throw new Error('parse failed')\n\nconst flow = asFlowchart(parsed.value)\nif (!flow) throw new Error(`not a structured flowchart: ${parsed.value.kind}`)\n\nconst next = mutate(flow, { kind: 'add_node', id: 'Cache', label: 'Cache' })\nif (!next.ok) throw new Error(next.error.message)\n\nconst verify = verifyMermaid(next.value)\nif (!verify.ok) throw new Error(JSON.stringify(verify.warnings, null, 2))\n\nconst source = serializeMermaid(next.value)\n```\n\nRules:\n\n- Use the matching exported `as` narrower before mutating an existing structured diagram.\n- Mutation ops use `kind`, not `type`.\n- Run `verifyMermaid` before every commit point.\n- Do not call `mutate` on opaque fallback bodies; the narrower returns `null` for unmodeled syntax.\n\n## Supported diagram families\n\nFamily support and its executable evidence are projected from the\n`FamilyDescriptor` registry into the generated\n[Section A capability report](https://github.com/adewale/agentic-mermaid/blob/main/docs/project/section-a-capability-report.md).\nSee [diagram families](./docs/diagram-families.md) for syntax examples and\ncompatibility notes.\n\n## More documentation\n\n- [System architecture](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/system/README.md) — **start here** for the rendered resolved-request, family-descriptor, positioned-artifact, and output-security overview (dogfooded, drift-proof).\n- [API reference](./docs/api.md) — renderers, agent API, options, CLI/MCP pointers.\n- [Agent API cookbook](./docs/agent-api-cookbook.md) — practical recipes for agents.\n- [Theming](./docs/theming.md) — two-color themes, built-ins, Shiki compatibility.\n- [Custom style cookbook](./docs/custom-style-cookbook.md) — JSON style files, screenshots, schema usage, and CLI commands.\n- [Fonts in custom styles](./docs/custom-fonts.md) — font selection, SVG declarations, PNG directories, fallbacks, and browser usage.\n- [React integration](./docs/react.md) — zero-flash `useMemo` rendering.\n- [ASCII output](./docs/ascii.md) — terminal output, color modes, XY charts.\n- [Mermaid config](./docs/config.md) — frontmatter, init directives, runtime config.\n- [Features](./docs/features.md), [quality](./docs/quality.md), [security](./SECURITY.md), [fork differences](./docs/fork-differences.md).\n- [Adding diagram types](https://github.com/adewale/agentic-mermaid/blob/main/docs/contributing/adding-diagram-types.md) for contributors.\n\n## Live editor and examples\n\n- [Examples](https://agentic-mermaid.dev/examples/) — supported families, Style + Palette combinations, and the rich shared examples corpus.\n- [Live editor](https://agentic-mermaid.dev/editor) — SVG/PNG exports and URL sharing.\n- [`examples/agent-loop.ts`](https://github.com/adewale/agentic-mermaid/blob/main/examples/agent-loop.ts)\n- [`examples/mcp-vs-cli-complex-diagrams.ts`](https://github.com/adewale/agentic-mermaid/blob/main/examples/mcp-vs-cli-complex-diagrams.ts)\n- [`examples/agent-improve-auth-flow.ts`](https://github.com/adewale/agentic-mermaid/blob/main/examples/agent-improve-auth-flow.ts)\n\n## Attribution\n\nAgentic Mermaid is a fork of Beautiful Mermaid by [Luki Labs](https://github.com/lukilabs/beautiful-mermaid). The ASCII rendering engine is based on [`mermaid-ascii`](https://github.com/AlexanderGrooff/mermaid-ascii) by Alexander Grooff and extended for Agentic Mermaid.\n\n## License\n\nMIT\n",
"bytes": 12096,
"sha": "6d801e927117260a506ab34ea589d3850372c0bd24d078091bf844f1dbd49518",
"repo_slug": "adewale/agentic-mermaid",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_adewale_agentic_mermaid_8c43dc31/readme"
}