ProbeLabs Maid — Lightweight Mermaid Linter & Auto-Fix

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.

flowchart LR
    subgraph Input["Mermaid Diagram Source"]
        AI["AI / LLM Agent Generated"]
        Human["Developer Writing Docs / Markdown"]
    end

    subgraph Maid["probelabs/maid Engine (~5MB)"]
        Parser["Mermaid AST & Syntax Validator"]
        Fixer["Rule-based Auto-Fix Engine"]
        Parser --> Fixer
    end

    subgraph Output["Result"]
        Clean["100% Valid Diagram"]
        Error["Clear Diagnostic & Line Number"]
    end

    Input --> Maid
    Fixer -->|"Auto-correct common mistakes"| Clean
    Fixer -->|"Report error if unresolvable"| Error

The Problem With Traditional Tools#

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

flowchart TB
    subgraph Traditional["Traditional mermaid-cli"]
        M1["Installs Node + Puppeteer + Headless Chromium"]
        M2["Download footprint: ~1.7 GB"]
        M3["Browser startup takes several seconds"]
    end

    subgraph MaidApproach["probelabs/maid"]
        P1["Standalone Parser & Linter"]
        P2["Ultra-lightweight: ~5 MB"]
        P3["Instant execution: < 50ms"]
    end

Common Errors Automatically Fixed by Maid#

LLMs often make subtle syntax mistakes such as unquoted parentheses in node labels or invalid arrow syntax:

flowchart TD
    Err1["1. Unescaped parenthesis in label<br/>node[Label (Extra Info)]"] --> Fix1["Fixed to: node['Label (Extra Info)']"]
    Err2["2. Broken arrow label syntax<br/>A -- text --> B"] --> Fix2["Fixed to: A -->|text| B"]
    Err3["3. Malformed subgraph / class definitions"] --> Fix3["Standardized 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/

2. Auto-Fix Mode (—fix)#

Let Maid automatically apply syntax fixes in-place:

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

3. Integrate into Project CI/CD#

Add it as a dev dependency:

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

Add helper scripts to your package.json:

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

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.

sequenceDiagram
    autonumber
    actor User as Developer
    participant Agent as AI Coding Assistant
    participant MCP as Maid MCP Server
    participant Doc as Markdown File

    User->>Agent: "Create a system architecture diagram"
    Agent->>Agent: Generate raw Mermaid code
    Agent->>MCP: Tool call: validate_mermaid(content)
    alt Syntax Error Detected
        MCP-->>Agent: {"valid": false, "fixed": "...", "errors": [...]}
        Agent->>Agent: Adopt auto-fixed Mermaid code
    else Valid Syntax
        MCP-->>Agent: {"valid": true}
    end
    Agent->>Doc: Write clean Mermaid diagram to file
    Agent-->>User: "Diagram created and verified 100% valid"

Configure the MCP server (mcp_config.json):

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

Programmatic Usage (Node.js SDK)#

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

flowchart LR
    Code["Raw Mermaid String"] --> SDK["Maid SDK: lint() / fix()"]
    SDK --> Result["Diagnostics Object<br/>&#123; valid: boolean, errors: [], fixedCode: string &#125;"]

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);
}

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#

• probelabs/maid GitHub Repository ↗
• Mermaid Official Documentation ↗
• Model Context Protocol (MCP) Specification ↗