blog.dopana

Back

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.

Resultprobelabs/maid Engine (~5MB)Mermaid Diagram Source"Auto-correct common mistakes""Report error if unresolvable"AI / LLM Agent GeneratedDeveloper Writing Docs /MarkdownMermaid AST & SyntaxValidatorRule-based Auto-Fix Engine100% Valid DiagramClear Diagnostic & Line Number

The Problem With Traditional Tools#

Traditionally, verifying Mermaid diagrams in CI/CD or local environments required @mermaid-js/mermaid-cli.

probelabs/maidTraditional mermaid-cliInstalls Node + Puppeteer +Headless ChromiumDownload footprint: ~1.7 GBBrowser startup takes severalsecondsStandalone Parser & LinterUltra-lightweight: ~5 MBInstant execution: < 50ms
MetricTraditional mermaid-cliprobelabs/maid
Footprint~1.7 GB (bundles Chromium / Puppeteer)~5 MB (Zero heavy browser)
Speed2-5s startup latencyMilliseconds (In-memory AST parsing)
Auto-FixNo (only renders or fails)Yes (Fixes common LLM syntax slips)
AI IntegrationNoneNative 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:

1. Unescaped parenthesis inlabelnode[Label (Extra Info)]Fixed to: node['Label (ExtraInfo)']2. Broken arrow label syntaxA -- text --> BFixed to: A -->|text| B3. Malformed subgraph / classdefinitionsStandardized AST output

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/
bash

2. Auto-Fix Mode (—fix)#

Let Maid automatically apply syntax fixes in-place:

npx -y @probelabs/maid --fix src/content/blog/
bash

3. Integrate into Project CI/CD#

Add it as a dev dependency:

bun add -d @probelabs/maid
# or
npm install -D @probelabs/maid
bash

Add helper scripts to your package.json:

{
  "scripts": {
    "lint:mermaid": "maid docs/ src/",
    "lint:mermaid:fix": "maid --fix docs/ src/"
  }
}
json

MCP 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.

[Valid Syntax]alt[Syntax Error Detected]12345678"Create a system architecture diagram"Generate raw Mermaid codeTool call: validate_mermaid(content){"valid": false, "fixed": "...", "errors": [...]}Adopt auto-fixed Mermaid code{"valid": true}Write clean Mermaid diagram to file"Diagram created and verified 100% valid"DeveloperAI Coding AssistantMaid MCP ServerMarkdown FileDeveloperAI Coding AssistantMaid MCP ServerMarkdown File

Configure the MCP server (mcp_config.json):

{
  "mcpServers": {
    "maid": {
      "command": "npx",
      "args": ["-y", "@probelabs/maid", "--mcp"]
    }
  }
}
json

Programmatic Usage (Node.js SDK)#

You can also use Maid programmatically in your own build pipelines or applications:

Raw Mermaid StringMaid SDK: lint() / fix()Diagnostics Object&{ valid: boolean, errors: [],fixedCode: string &}

Conclusion#

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.

References#