ProbeLabs Maid — 超軽量 Mermaid Linter & 自動修正

技術ドキュメントの作成や AI コーディングエージェント（LLM）による図の生成時、Mermaid の構文ミスによってレンダリングが壊れてしまう問題は頻繁に発生します。probelabs/maid は、ミリ秒単位で動作する超軽量な Mermaid リンター＆バリデータであり、構文エラーの検知と自動修正を提供します。

flowchart LR
    subgraph Input["Mermaid 図の入力ソース"]
        AI["AI / LLM エージェントによる生成"]
        Human["開発者による Docs / Markdown 執筆"]
    end

    subgraph Maid["probelabs/maid エンジン (~5MB)"]
        Parser["Mermaid AST & 構文バリデータ"]
        Fixer["ルールベースの自動修正エンジン"]
        Parser --> Fixer
    end

    subgraph Output["出力結果"]
        Clean["100% 正しい Mermaid 図"]
        Error["行番号付きの詳細なエラー診断"]
    end

    Input --> Maid
    Fixer -->|"一般的な構文ミスを自動修正"| Clean
    Fixer -->|"修復不可能な場合エラーを報告"| Error

従来ツールが抱える課題#

これまで CI/CD やローカル環境で Mermaid 図を検証する場合、公式の mermaid-cli（@mermaid-js/mermaid-cli）を利用するのが一般的でした。

flowchart TB
    subgraph Traditional["従来の mermaid-cli"]
        M1["Node + Puppeteer + Headless Chromium をインストール"]
        M2["ダウンロードサイズ: 約 1.7 GB"]
        M3["ブラウザの起動に数秒の遅延"]
    end

    subgraph MaidApproach["probelabs/maid"]
        P1["スタンドアロンの Parser & Linter"]
        P2["超軽量サイズ: 約 5 MB"]
        P3["即時実行: 50ms 未満"]
    end

Maid が自動修正する代表的な構文エラー#

LLM が出力する Mermaid コードでは、ノード名に含まれる括弧のエスケープ漏れや矢印ラベルの誤用が多発します：

flowchart TD
    Err1["1. ラベル内の丸括弧のエスケープ漏れ<br/>node[Label (詳細)]"] --> Fix1["修正後: node['Label (詳細)']"]
    Err2["2. 矢印テキスト構文の間違い<br/>A -- text --> B"] --> Fix2["修正後: A -->|text| B"]
    Err3["3. 不正な subgraph やクラス定義"] --> Fix3["AST レベルで標準化出力"]

インストールと使い方#

1. npx で即座に実行#

グローバルインストールを行わずに、指定したファイルを直接チェックできます：

# 単一ファイルを検証
npx -y @probelabs/maid README.md

# docs フォルダ配下を再帰的にチェック
npx -y @probelabs/maid docs/

2. 自動修正モード（—fix）#

検出された構文エラーをファイルに直接自動修正して適用します：

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

3. プロジェクトへの導入#

開発依存関係としてインストールし、CI パイプラインに組み込みます：

bun add -d @probelabs/maid
# または
npm install -D @probelabs/maid

package.json のスクリプト例：

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

AI コーディング支援向け MCP Server 連携#

probelabs/maid は Model Context Protocol (MCP) サーバー機能を標準装備しています。Claude Code、Antigravity、Cursor などの AI エージェントが、ファイル書き込み前に Mermaid 図の構文を検証・自動修正できます。

sequenceDiagram
    autonumber
    actor User as 開発者
    participant Agent as AI コーディングアシスタント
    participant MCP as Maid MCP Server
    participant Doc as Markdown ファイル

    User->>Agent: "システム構成図を作成して"
    Agent->>Agent: Mermaid コードを生成
    Agent->>MCP: ツール呼び出し: validate_mermaid(content)
    alt 構文エラーを検出した場合
        MCP-->>Agent: {"valid": false, "fixed": "...", "errors": [...]}
        Agent->>Agent: 自動修正された Mermaid コードを採用
    else 構文が正常な場合
        MCP-->>Agent: {"valid": true}
    end
    Agent->>Doc: 正しい Mermaid 図をファイルに書き込み
    Agent-->>User: "正常にレンダリング可能な図を作成しました"

MCP 設定例（mcp_config.json）：

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

プログラマブルな利用（Node.js SDK）#

Node.js アプリケーション内から直接 SDK をインポートして図の検証を行うことも可能です：

flowchart LR
    Code["生の Mermaid 文字列"] --> SDK["Maid SDK: lint() / fix()"]
    SDK --> Result["診断結果オブジェクト<br/>&#123; valid: boolean, errors: [], fixedCode: string &#125;"]

import { lint, fix } from '@probelabs/maid';

const rawMermaid = `
flowchart LR
  A[User (Client)] --> B
`;

// 1. 構文チェック
const diagnostics = await lint(rawMermaid);
if (!diagnostics.valid) {
  console.error('エラーを検出:', diagnostics.errors);
  
  // 2. 自動修正の実行
  const fixed = await fix(rawMermaid);
  console.log('修正後のコード:\n', fixed.code);
}

まとめ#

probelabs/maid は、Mermaid 図を活用する現代の開発チームや AI ワークフローにとって不可欠なツールです：

• 軽量＆高速: Chromium 依存の 1.7GB を排除し、わずか 5MB でミリ秒動作。
• AI エラーの自動修正: 不正な構文によるレンダリング崩れを防止。
• Agent ファースト: MCP サーバーにより AI 自律エージェントとの連携が容易。

参考文献#

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