blog.dopana

戻る

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

出力結果probelabs/maid エンジン (~5MB)Mermaid 図の入力ソース"一般的な構文ミスを自動修正""修復不可能な場合エラーを報告"AI / LLM エージェントによる生成開発者による Docs / Markdown執筆Mermaid AST & 構文バリデータルールベースの自動修正エンジン100% 正しい Mermaid 図行番号付きの詳細なエラー診断

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

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

probelabs/maid従来の mermaid-cliNode + Puppeteer + HeadlessChromium をインストールダウンロードサイズ: 約 1.7 GBブラウザの起動に数秒の遅延スタンドアロンの Parser &Linter超軽量サイズ: 約 5 MB即時実行: 50ms 未満
比較項目従来の mermaid-cliprobelabs/maid
パッケージ容量約 1.7 GB(Chromium / Puppeteer 依存)約 5 MB(ブラウザ不要)
実行速度起動に 2〜5 秒数ミリ秒(インメモリ AST 解析)
自動修正(Auto-Fix)なし(レンダリングまたはエラーのみ)あり(LLM 特有のミスを自動修正)
AI 連携(MCP)非対応Model Context Protocol(MCP)Server 完備

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

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

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

インストールと使い方#

1. npx で即座に実行#

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

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

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

2. 自動修正モード(—fix)#

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

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

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

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

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

package.json のスクリプト例:

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

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

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

[構文が正常な場合]alt[構文エラーを検出した場合]12345678"システム構成図を作成して"Mermaid コードを生成ツール呼び出し: validate_mermaid(content){"valid": false, "fixed": "...", "errors": [...]}自動修正された Mermaid コードを採用{"valid": true}正しい Mermaid 図をファイルに書き込み"正常にレンダリング可能な図を作成しました"開発者AI コーディングアシスタントMaid MCP ServerMarkdown ファイル開発者AI コーディングアシスタントMaid MCP ServerMarkdown ファイル

MCP 設定例(mcp_config.json):

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

プログラマブルな利用(Node.js SDK)#

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

生の Mermaid 文字列Maid SDK: lint() / fix()診断結果オブジェクト&{ valid: boolean, errors: [],fixedCode: string &}

まとめ#

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

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

参考文献#