When generating technical documentation or working with AI coding agents (LLMs), Mermaid syntax errors frequently cause broken diagram rendering. probelabs/maid is a lightweight, millisecond-speed Mermaid linter and validator built to detect and automatically repair broken Mermaid syntax.
The Problem With Traditional Tools#
Traditionally, verifying Mermaid diagrams in CI/CD or local environments required @mermaid-js/mermaid-cli.
| Metric | Traditional mermaid-cli | probelabs/maid |
|---|---|---|
| Footprint | ~1.7 GB (bundles Chromium / Puppeteer) | ~5 MB (Zero heavy browser) |
| Speed | 2-5s startup latency | Milliseconds (In-memory AST parsing) |
| Auto-Fix | No (only renders or fails) | Yes (Fixes common LLM syntax slips) |
| AI Integration | None | Native Model Context Protocol (MCP) Server |
Common Errors Automatically Fixed by Maid#
LLMs often make subtle syntax mistakes such as unquoted parentheses in node labels or invalid arrow syntax:
Installation & Usage#
1. Run Instantly via npx#
No global installation required. You can scan any Markdown file directly:
# Check a single file
npx -y @probelabs/maid README.md
# Recursively lint a documentation folder
npx -y @probelabs/maid docs/bash2. Auto-Fix Mode (—fix)#
Let Maid automatically apply syntax fixes in-place:
npx -y @probelabs/maid --fix src/content/blog/bash3. Integrate into Project CI/CD#
Add it as a dev dependency:
bun add -d @probelabs/maid
# or
npm install -D @probelabs/maidbashAdd helper scripts to your package.json:
{
"scripts": {
"lint:mermaid": "maid docs/ src/",
"lint:mermaid:fix": "maid --fix docs/ src/"
}
}jsonMCP Server Integration for AI Coding Assistants#
probelabs/maid includes a native Model Context Protocol (MCP) server. This allows AI assistants (like Claude Code, Antigravity, or Cursor) to validate and repair diagrams during conversation before writing to disk.
Configure the MCP server (mcp_config.json):
{
"mcpServers": {
"maid": {
"command": "npx",
"args": ["-y", "@probelabs/maid", "--mcp"]
}
}
}jsonProgrammatic Usage (Node.js SDK)#
You can also use Maid programmatically in your own build pipelines or applications:
import { lint, fix } from '@probelabs/maid';
const rawMermaid = `
flowchart LR
A[User (Client)] --> B
`;
// 1. Lint and validate
const diagnostics = await lint(rawMermaid);
if (!diagnostics.valid) {
console.error('Errors found:', diagnostics.errors);
// 2. Auto-fix syntax
const fixed = await fix(rawMermaid);
console.log('Fixed Mermaid syntax:\n', fixed.code);
}typescriptConclusion#
probelabs/maid is an essential tool for developer documentation and AI workflows:
- Lightweight & Fast: Eliminates the ~1.7GB Chromium overhead.
- Fixes AI Glitches: Ensures your documentation never suffers from broken diagram renders.
- Agent Ready: First-class MCP server support for autonomous coding agents.