<div align="center">

# `mermaid-mender`

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

![License](https://img.shields.io/badge/license-MIT-blue.svg) ![Language](https://img.shields.io/badge/language-python-green.svg) ![Status](https://img.shields.io/badge/status-active-success.svg) [![PyPI version](https://img.shields.io/pypi/v/mermaid-mender)](https://pypi.org/project/mermaid-mender/) [![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/) [![MCP-like](https://img.shields.io/badge/MCP-like-orange)](https://modelcontextprotocol.io/)

<img src="demo.gif" alt="Demo" width="700" />

</div>

---

## 🎯 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.

## ✨ 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

```bash
# Install
pip install mermaid-mender

# Run
mermaid-mender --help
```

## 📦 Installation

### From Source

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

```bash
# 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](https://github.com/charmbracelet/vhs):

```bash
vhs < demo.tape
```

## 📖 Usage

```bash
# Show help
mermaid-mender --help

# Common usage examples
mermaid-mender --example
```

## 🏗️ Architecture

```mermaid
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](LICENSE) for details.

---

<div align="center">

**If this project helped you, please ⭐ star it!**

[Made with ❤️ and AI](https://github.com)

</div>