Mermaid MCP Server

Mermaid MCP サーバー

Mermaid 図を検証するための Model Context Protocol（MCP）サーバーです。

https://github.com/mermaid-js/mermaid-cli をラップした最小限の Python ラッパーを実装し、すぐに簡単に使えるようにしています。

概要

Mermaid 図の検証と、任意で PNG 画像へのレンダリングを行う Python MCP サーバーです。検証とレンダリングには Mermaid CLI ツールを使用します。

このサーバーは、次のような構造化された検証結果を LLM に提供します。

• ブール値による検証ステータス（is_valid: true/false）。Mermaid 図の構文が正しいかどうかを示します
• 詳細なエラーメッセージ。検証に失敗した場合に、具体的な問題（構文エラー、サポートされていない図の種類、不正な形式のノードなど）を説明します
• 任意の base64 エンコード済み PNG 画像。正常にレンダリングされた図を視覚的に確認できます

これにより、LLM は Mermaid 図の構文をプログラムから検証し、具体的なエラーを把握して適切な修正を提案できます。また、任意でレンダリング結果を視覚的に確認することもできます。

Gemini モデルを使用して MCP サーバーを呼び出し、テストを行うためのシンプルな Pydantic-AI MCP クライアントも提供します。

前提条件

重要：サーバーコンポーネントのみを使用する場合（クライアントを使用しない場合）でも、この MCP サーバーを使用するには、システムに Node.js がインストールされている必要があります。サーバーは内部で、図の検証とレンダリングを行うサブプロセスとして npx @mermaid-js/mermaid-cli を呼び出します。

必要な依存関係

• npm を含む Node.js（すべての使用方法で必要）
• Mermaid CLI：npm install -g @mermaid-js/mermaid-cli でインストールします
• uv を含む Python（MCP サーバーの実行に必要）

依存関係のクイックセットアップ

# Install Mermaid CLI globally
npm install -g @mermaid-js/mermaid-cli

# Verify installation
npx @mermaid-js/mermaid-cli --version

クイックスタート

MCP クライアント（Claude Desktop など）でこのサーバーを使用するには、MCP 設定に次の構成を追加します。

注：MCP サーバーを設定する前に、Node.js と Mermaid CLI がインストールされていることを確認してください（上記の前提条件を参照）。

設定形式

1. このリポジトリをクローンします

2. MCP クライアントの設定ファイル（例：claude_desktop_config.json）に次の内容を追加します。

{
  "mcpServers": {
    "mermaid-validator": {
      "command": "uv",
      "args": ["run", "/path/to/mermaid_mcp_server.py"],
    }
  }
}

設定オプション

• command：サーバーの実行に uv を使用します
• args：uv run でサーバースクリプトを実行します
• cwd：クローンしたリポジトリの絶対パスを設定します
• env：サーバーの環境変数
  • MCP_TRANSPORT：標準入力／出力による通信の場合は "stdio" に設定します

拡張設定の例

{
  "mcpServers": {
    "mermaid-validator": {
      "command": "uv", 
      "args": ["run", "/path/to/mermaid_mcp_server.py"],
      "env": {
        "MCP_TRANSPORT": "stdio",
      }
    }
  }
}

Mermaid-CLI の抽象化

Python ラッパーは、複雑なファイル処理やコマンドライン引数を抽象化することで、Mermaid CLI を大幅に簡単に使用できるようにします。

ラッパーなし（mermaid-cli を直接使用）：

# Create input file
echo "graph TD; A-->B" > diagram.mmd

# Create puppeteer config file
echo '{"args": ["--no-sandbox", "--disable-setuid-sandbox"]}' > puppeteer-config.json

# Run mermaid-cli with multiple arguments
npx @mermaid-js/mermaid-cli -i diagram.mmd -o output.png --puppeteerConfigFile puppeteer-config.json

# Handle output file and cleanup

Python ラッパーを使用：

# Simple function call with diagram text
result = await validate_mermaid_diagram("graph TD; A-->B")

# All file handling, configuration, and cleanup is automatic
# Returns structured result with validation status and base64-encoded image

主な抽象化：

1. 一時ファイルの管理：一時的な .mmd 入力ファイルを自動的に作成し、クリーンアップします
2. 出力ファイルの処理：一時的な .png 出力ファイルを管理し、base64 文字列に変換します
3. Puppeteer の設定：ヘッドレスブラウザーでのレンダリングに必要なサンドボックス設定を自動的に生成します
4. エラー処理：生の stderr 出力ではなく、構造化されたエラーメッセージを取得して返します
5. コマンドの構築：必要なフラグをすべて含む完全な npx @mermaid-js/mermaid-cli コマンドを構築します
6. リソースのクリーンアップ：処理後にすべての一時ファイルが適切に削除されるようにします

この抽象化により、ユーザーは基盤となるファイルシステム操作やコマンドラインの複雑さを扱うことなく、図の検証とレンダリングに集中できます。

ローカル開発

このリポジトリは単独で使用し、Mermaid MCP バリデーターの機能をプログラムからテストできます。

要件

必要な依存関係（Node.js、Mermaid CLI、uv を含む Python）については、上記の前提条件のセクションを参照してください。

クイックセットアップ（推奨）

付属の Makefile を使用すると、セットアップを簡単に行えます。

# Install all dependencies (Python + Node.js + Mermaid CLI)
make install

# Run validation tests
make test

手動セットアップ

手動でセットアップする場合：

1. このリポジトリをクローンします
2. 依存関係をインストールします：uv sync
3. Mermaid CLI をインストールします：npm install -g @mermaid-js/mermaid-cli
4. .env.example を .env にコピーし、API キーを入力します
5. サーバーを起動します：uv run mermaid_mcp_server.py

使用方法

サーバーは、Mermaid 図を検証するツールを公開します：

• validate_mermaid_diagram：Mermaid 図を検証し、検証結果を返します

ツールのパラメーター

• diagram_text（必須）：検証する Mermaid 図のテキスト
• return_image（任意、デフォルト：false）：base64 エンコードされた PNG 画像を返すかどうか

コンテキスト長の最適化

重要：デフォルトでは、LLM の会話で使用できるコンテキスト長を確保するため、ツールは base64 エンコードされた画像を返しません（return_image=false）。base64 エンコードされた画像は非常に長い文字列（多くの場合 10KB～100KB 以上）になることがあり、会話で使用できるコンテキストに大きな影響を与えます。

各設定の使い分け：

• return_image=false（デフォルト）：図の検証のみを行う場合に使用します。高速で、コンテキストを効率的に利用できます。
• return_image=true：レンダリングされた画像データが必要な場合にのみ使用します。警告：コンテキスト長を大幅に消費します。

使用例

# Validation only (recommended for most cases)
result = await validate_mermaid_diagram("graph TD; A-->B")
# Returns: MermaidValidationResult(is_valid=True, error_message=None, diagram_image=None)

# Validation with image (use sparingly)
result = await validate_mermaid_diagram("graph TD; A-->B", return_image=True)
# Returns: MermaidValidationResult(is_valid=True, error_message=None, diagram_image="iVBORw0KGgoAAAANSUhEUg...")

テスト

このプロジェクトには、便利なテストコマンドが用意されています：

# Run all tests
make test

# Or run the test script directly
uv run test_pydantic.py

テストスクリプトは、Pydantic AI と Gemini モデルを使用して MCP サーバーの機能を検証します。