mermaid-mender

A tiny CLI and MCP-like server that validates and self-heals broken Mermaid diagrams generated by AI agents.

🎯 Why?

AI coding agents increasingly emit Mermaid diagrams into docs, README files, and agent workflows, but they often produce invalid arrows, missing diagram types, or unbalanced labels. Existing Mermaid renderers fail late and give little actionable repair feedback, and newer layout tools like Line9 are not open-source agent utilities. A small local validator/repair layer fits directly into agent loops, CI, and MCP toolchains.

Target audience: Developers using AI coding agents, MCP clients, documentation pipelines, and CI checks that need reliable Mermaid diagrams without manually debugging syntax.

Related MCP server: Fast Mermaid Validator MCP

✨ Features

• ✨ validate_mermaid: reports empty input, missing diagram type, nonstandard arrows, unbalanced quotes, and unbalanced brackets

• ✨ repair_mermaid: normalizes arrows, closes odd quotes, and prepends flowchart TD when a flowchart is detected but missing

• ✨ MCP-like stdio JSON-RPC server exposing validate and repair tools to agents

🚀 Quick Start

# Install
pip install mermaid-mender

# Run
mermaid-mender --help

📦 Installation

From Source

git clone https://github.com/YOUR_USERNAME/mermaid-mender.git
cd mermaid-mender

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest -v

🎬 Demo

The GIF above was recorded using Charm VHS:

vhs < demo.tape

📖 Usage

# Show help
mermaid-mender --help

# Common usage examples
mermaid-mender --example

🏗️ Architecture

graph LR
    A[Input] --> B[Core Engine]
    B --> C[Output]
    B --> D[Plugins]
    D --> E[Extensions]

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repo

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

📄 License

MIT © 2026 — See LICENSE for details.

If this project helped you, please ⭐ star it!

Made with ❤️ and AI