Mermaid Validator

MCP サーバー：Mermaid バリデーター

Mermaid の図を検証し、レンダリングする Model Context Protocol サーバーです。このサーバーを使うと、LLM で Mermaid の図を検証し、レンダリングできます。

使用方法

クイックスタート

MCP サーバーの設定ファイルに Mermaid Validator を追加することで、MCP クライアントを設定できます。

{
  "mcpServers": {
    "mermaid-validator": {
      "command": "npx",
      "args": [
        "-y",
        "@rtuin/mcp-mermaid-validator@latest"
      ]
    }
  }
}

アーキテクチャ

全体アーキテクチャ

このプロジェクトは、次の機能を備えたシンプルな TypeScript Node.js アプリケーションとして構成されています。

1. メインアプリケーション：Mermaid の図を検証し、レンダリングされた PNG を返す Node.js サービス
2. MCP 連携：Model Context Protocol SDK を使用して、MCP 対応クライアントに機能を公開します
3. Mermaid CLI 連携：Mermaid CLI ツールを利用して、図の検証とレンダリングを行います

コード構成

mcp-mermaid-validator/
├── dist/                   # Compiled JavaScript output
│   └── main.js             # Compiled main application
├── src/                    # TypeScript source code
│   └── main.ts             # Main application entry point
├── node_modules/           # Dependencies
├── package.json            # Project dependencies and scripts
├── package-lock.json       # Dependency lock file
├── tsconfig.json           # TypeScript configuration
├── eslint.config.js        # ESLint configuration
├── .prettierrc             # Prettier configuration
└── README.md               # Project documentation

コンポーネントの機能

MCP サーバー（メインコンポーネント）

コア機能は src/main.ts に実装されています。このコンポーネントは次の処理を行います。

1. MCP サーバーのインスタンスを作成します
2. Mermaid の図の構文を受け取る validateMermaid ツールを登録します
3. Mermaid CLI を使用して図を検証し、レンダリングします
4. 検証結果と、検証に成功した場合はレンダリングされた PNG を返します
5. 適切なエラーメッセージでエラーケースを処理します

データフロー

1. 入力：文字列形式の Mermaid 図の構文
2. 処理：
   • 図を標準入力経由で Mermaid CLI に渡します
   • CLI が構文を検証し、有効な場合は PNG をレンダリングします
   • 標準出力／標準エラー出力から出力とエラーを取得します
3. 出力：
   • 成功：テキストによる確認メッセージと、Base64 エンコードされた画像としてのレンダリング済み PNG
   • 失敗：検証失敗の詳細を含むエラーメッセージ

依存関係

外部ライブラリ

• @modelcontextprotocol/sdk：Model Context Protocol を実装するための SDK
• @mermaid-js/mermaid-cli：Mermaid の図を検証およびレンダリングする CLI ツール
• zod：TypeScript 用のスキーマ検証ライブラリ

開発用依存関係

• typescript：TypeScript コンパイラー
• eslint：リンティングツール
• prettier：コードフォーマットツール

API 仕様

validateMermaid ツール

目的：Mermaid の図を検証し、有効な場合はレンダリングされた PNG を返します

パラメーター：

• diagram（string）：検証する Mermaid 図の構文

戻り値：

• 成功：

  {
    content: [
      { 
        type: "text", 
        text: "Mermaid diagram is valid" 
      },
      {
        type: "image", 
        data: string, // Base64-encoded PNG
        mimeType: "image/png"
      }
    ]
  }
  

• 失敗：

  {
    content: [
      { 
        type: "text", 
        text: "Mermaid diagram is invalid" 
      },
      {
        type: "text",
        text: string // Error message
      },
      {
        type: "text",
        text: string // Detailed error output (if available)
      }
    ]
  }
  

技術的な判断

1. MCP 連携：このプロジェクトでは Model Context Protocol を使用して AI ツールのインターフェースを標準化し、対応クライアントとシームレスに連携できるようにしています。

2. PNG 出力形式：ほとんどの MCP クライアントとの互換性を高めるため、デフォルトの出力形式として PNG を使用しています。特に、SVG に対応していない Cursor との互換性を確保できます。

3. 子プロセスの使用：Mermaid CLI との通信には Node.js の子プロセスを使用しています。これにより、次のことが可能になります。

   • メインアプリケーションとレンダリングプロセスの分離
   • 詳細なエラー情報の取得
   • レンダリングパイプラインの適切な処理

4. エラー処理方針：ネストされた try-catch 構造を使用し、次のことを実現しています。

   • 検証エラー（無効な図の構文）とシステムエラーを区別します
   • 図の修正に役立つ詳細なエラー情報をユーザーに提供します
   • 無効な入力を処理する場合でも、サービスの安定性を保ちます

5. シンプルなプロジェクト構成：わかりやすい TypeScript プロジェクト構成を採用し、次のことを実現しています。

   • メンテナンスと理解が容易になります
   • 依存関係を直接管理できます
   • ビルドプロセスを簡略化できます

ビルドと実行

npm スクリプトを使用して、アプリケーションをビルドして実行できます。

# Install dependencies
npm install

# Build the application
npm run build

# Run locally (for development)
npx @modelcontextprotocol/inspector node dist/main.js

# Format code
npm run format

# Lint code
npm run lint

# Watch for changes (development)
npm run watch

アプリケーションは標準入出力で通信する MCP サーバーとして動作するため、MCP 対応クライアントとの連携に適しています。

リリース

新しいバージョンをリリースするには、次の手順を順番に実行します。

• npm run build
• npm run bump
• npm run changelog
• npm publish --access public

トラブルシューティング

• WSL/Windows の stdin：以前のバージョンでは Mermaid CLI の起動時に /dev/stdin を使用していましたが、WSL では ENXIO エラーが発生する場合があります。このサーバーでは、Linux/macOS/WSL/Windows 間で移植性を確保するため、stdin/stdout に -（-i - / -o -）を使用するようになりました。
• Inspector の作業ディレクトリ：MCP Inspector 経由で起動するときは、サーバーのパスが解決できることを確認してください（例：npx @modelcontextprotocol/inspector npx -y @rtuin/mcp-mermaid-validator@latest を使用するか、dist/main.js の絶対パスを指定してください）。