# Agentic Mermaid

> Agent-native Mermaid runtime: parse, verify, mutate, and render diagrams through a TypeScript library, CLI, self-hosted MCP, or hosted Streamable HTTP MCP. The website is documentation plus a browser-local editor, not a REST render API.

Use Agentic Mermaid when an agent needs to create, edit, verify, describe, or render Mermaid diagrams without depending on a browser. It is strongest for deterministic CI checks, structured diagram edits, read-back of semantic facts, and SVG/PNG/ASCII output from the same source.

Do not use the hosted MCP for private diagrams that must stay local; use the library, CLI, or self-hosted stdio MCP instead. Do not call the website as a REST render API; /mcp speaks MCP JSON-RPC only.

Safe loop:
- Verify before serialize, render, commit, or return.
- For task-critical meaning, read back facts with am describe --format facts, hosted describe format="facts", or checkMermaid.
- Do not fabricate ValidDiagram objects. Parse first.
- Prefer the local library, CLI, or MCP. The hosted /mcp endpoint covers the same core tools with 64KB input caps.
- For straightforward edits, prefer mutate/build over execute. Reserve execute for logic the declarative ops do not express.

Hosted successful deterministic pure-tool results may be reused by a private server-side compute cache for up to 24 hours. The HTTP response itself is always `cache-control: no-store`; `x-agentic-mermaid-compute-cache` reports private reuse.

Styling: every render accepts style (a renderer treatment like hand-drawn, watercolor, or blueprint; a palette name; an inline JSON record; or a stack merged left-to-right) plus seed to re-roll styled ink. Layout never moves. A colors-only style is a palette.

## Start Here

- [Agent bootstrap](https://agentic-mermaid.dev/start.md): copy-and-follow workflow for one diagram task.
- [Hosted MCP endpoint](https://agentic-mermaid.dev/mcp): stateless Streamable HTTP JSON-RPC with execute, describe_sdk, render_svg, render_ascii, render_png, verify, describe, mutate, build.
- [MCP server card](https://agentic-mermaid.dev/.well-known/mcp/server-card.json): pre-connection metadata for the hosted MCP server.
- [MCP manifest](https://agentic-mermaid.dev/.well-known/mcp.json): compact tool manifest for agents and scanners.
- [AI catalog](https://agentic-mermaid.dev/.well-known/ai-catalog.json): discovery index for the agent-facing resources on this domain.
- [Agent instructions](https://agentic-mermaid.dev/agent-instructions.md): compact operating guide for agents.
- [Capabilities](https://agentic-mermaid.dev/capabilities.json): authoritative family, output, mutation, and warning-code contract.
- [Examples](https://agentic-mermaid.dev/examples/index.json): the same example IDs and sources loaded by the editor.
- [Workflow skill](https://agentic-mermaid.dev/skills/agentic-mermaid-diagram-workflow/SKILL.md): optional skill for skills-capable agents.

## Optional

- [Documentation](https://agentic-mermaid.dev/docs/): human-readable docs for install, CLI, MCP, diagram families, and styling.
- [Editor](https://agentic-mermaid.dev/editor/?empty=1): browser-local editor for interactive diagram authoring.
- [GitHub repository](https://github.com/adewale/agentic-mermaid): source code, issues, and release history.