@probelabs/maid

Maid

Fast, accurate Mermaid diagram validator with clear, actionable diagnostics. Built for the AI age where Mermaid has become essential—but validation shouldn't require a browser.

Why Maid?

• Built for AI: Designed for AI agents and LLMs that generate Mermaid diagrams
• Render Guarantee: When Maid says it's valid, your diagram will render
• Lightning Fast: Validates in milliseconds without launching a browser
• Human-Friendly: Clear error messages with line numbers, carets, and actionable hints
• Lightweight: ~5MB vs. mermaid-cli's 1.7GB (Puppeteer + Chrome)
• Auto-Fix: Automatically corrects common AI-generated mistakes

Quick Start

# One‑off (npx)
npx -y @probelabs/maid diagram.mmd

# Or install locally (dev dependency)
npm install -D @probelabs/maid
npx maid diagram.mmd   # uses local bin from @probelabs/maid

# From stdin
cat diagram.mmd | npx -y @probelabs/maid -

# Markdown with multiple diagrams
npx -y @probelabs/maid README.md

Lint an entire docs directory (recursively)

npx -y @probelabs/maid docs/

### SDK Quick Example

Use Maid programmatically (ESM). See docs/SDK.md for more.

import { validate, fixText } from '@probelabs/maid';

const src = 'flowchart TD\nA-B'; const { errors } = validate(src); if (errors.length) { const { fixed } = fixText(src, { level: 'safe' }); console.log(fixed); }

Exit codes
- 0: no errors (including when no Mermaid diagrams are found)
- 1: at least one error (warnings do not fail)

## MCP Server for AI Assistants

Maid includes a Model Context Protocol (MCP) server that allows AI assistants like Claude Code to validate and fix Mermaid diagrams directly in conversations.

### Quick Setup for Claude Code

Add Maid MCP server using the CLI:

claude mcp add -- npx -y @probelabs/maid mcp

Or configure manually in ~/.claude.json:

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

After configuration, restart Claude Code. The assistant will now be able to validate and fix Mermaid diagrams when you ask.

MCP Tool: validatemermaid

Inputs: