技術ドキュメントの作成や AI コーディングエージェント(LLM)による図の生成時、Mermaid の構文ミスによってレンダリングが壊れてしまう問題は頻繁に発生します。probelabs/maid は、ミリ秒単位で動作する超軽量な Mermaid リンター&バリデータであり、構文エラーの検知と自動修正を提供します。
従来ツールが抱える課題#
これまで CI/CD やローカル環境で Mermaid 図を検証する場合、公式の mermaid-cli(@mermaid-js/mermaid-cli)を利用するのが一般的でした。
| 比較項目 | 従来の mermaid-cli | probelabs/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. npx で即座に実行#
グローバルインストールを行わずに、指定したファイルを直接チェックできます:
# 単一ファイルを検証
npx -y @probelabs/maid README.md
# docs フォルダ配下を再帰的にチェック
npx -y @probelabs/maid docs/bash2. 自動修正モード(—fix)#
検出された構文エラーをファイルに直接自動修正して適用します:
npx -y @probelabs/maid --fix src/content/blog/bash3. プロジェクトへの導入#
開発依存関係としてインストールし、CI パイプラインに組み込みます:
bun add -d @probelabs/maid
# または
npm install -D @probelabs/maidbashpackage.json のスクリプト例:
{
"scripts": {
"lint:mermaid": "maid docs/ src/",
"lint:mermaid:fix": "maid --fix docs/ src/"
}
}jsonAI コーディング支援向け MCP Server 連携#
probelabs/maid は Model Context Protocol (MCP) サーバー機能を標準装備しています。Claude Code、Antigravity、Cursor などの AI エージェントが、ファイル書き込み前に Mermaid 図の構文を検証・自動修正できます。
MCP 設定例(mcp_config.json):
{
"mcpServers": {
"maid": {
"command": "npx",
"args": ["-y", "@probelabs/maid", "--mcp"]
}
}
}jsonプログラマブルな利用(Node.js SDK)#
Node.js アプリケーション内から直接 SDK をインポートして図の検証を行うことも可能です:
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);
}typescriptまとめ#
probelabs/maid は、Mermaid 図を活用する現代の開発チームや AI ワークフローにとって不可欠なツールです:
- 軽量&高速: Chromium 依存の 1.7GB を排除し、わずか 5MB でミリ秒動作。
- AI エラーの自動修正: 不正な構文によるレンダリング崩れを防止。
- Agent ファースト: MCP サーバーにより AI 自律エージェントとの連携が容易。