obsidian-mermaid-mcp

ローカル・ゼロトークン・ロスレスで、Obsidian ボールトの Mermaid レンダリングと可逆的なノート同期を、すべての AI エージェント向けに実現します。

🌟 主な特長

• ✍️ プロンプト不要のエージェント執筆体験 AI エージェント（Codex、Claude Code、Antigravity、Cursor、Windsurf、Cline など）は、```mermaid コードブロックを含む標準的な Markdown を自然に記述できます。バックグラウンドの Watcher が、特別なプロンプトを必要とせず、約 2 秒以内にそれらを埋め込み SVG に自動変換します。

• 🔒 100% ローカル＆プライベート ヘッドレス Chrome/Puppeteer 経由でローカルレンダリングします。クラウドレンダリング API なし、トークンコストなし、ネットワーク漏洩ゼロ。

• 🔄 ロスレス＆完全リバーシブル 元の Mermaid コードは .mmd サイドカーファイルと SVG <metadata> の両方に安全に保持されます。ワンクリックでいつでも元の Mermaid コードブロックに戻せます。

• 🧠 スマートなボールト適応 .obsidian/app.json を自動検出し（フォルダ相対の assets/${filename}、ボールトルートの attachments、同一フォルダ構成に対応）、設定は一切不要です。

• ⚡ デュアル動作モード

  1. 自動 Watcher モード（シームレスな作成のためのバックグラウンドファイルウォッチャー）

  2. MCP ツールモード（エージェントが直接呼び出せる 4 つの標準 stdio MCP ツール）

• 💻 ユニバーサルプラットフォーム対応 macOS、Linux、Windows、WSL、Docker。

🚀 クイックスタート

必要条件

• Node.js: >= 20.0.0

• Chrome / Chromium / Edge / Brave / Arc: 標準的な場所にインストールされているか、PUPPETEER_EXECUTABLE_PATH で指定します。

インストールとビルド（ローカル Node.js）

git clone https://github.com/IPromise-23/obsidian-mermaid-mcp.git
cd obsidian-mermaid-mcp
npm ci
npm run build
npm test

インストールとビルド（Docker 代替）

git clone https://github.com/IPromise-23/obsidian-mermaid-mcp.git
cd obsidian-mermaid-mcp
docker build -t obsidian-mermaid-mcp:latest .

👉 Docker 詳細ガイド（MCP サーバー＆Docker Compose）: docs/docker-guide.md

🛠️ 使用方法 1: 自動 Watcher（推奨）

Watcher をバックグラウンドで実行すると、Obsidian ノートに新規作成または編集された Mermaid ブロックを自動変換します。

フォアグラウンドテスト

node packages/watcher/dist/index.js watch \
  --vault-root /path/to/your/obsidian/vault \
  --apply \
  --debounce-ms 3000

注記: 実際のファイル書き込みには --apply が必要です。--apply なしの場合、Watcher はプレビューのみのモードで動作します。

バックグラウンドデーモン設定

主要なすべてのプラットフォーム向けに、すぐ使えるバックグラウンドサービス用テンプレートを提供しています。

• macOS（LaunchAgent）: examples/daemons/com.obsidian-mermaid.watch.plist を参照

• Linux（systemd ユーザーサービス）: examples/daemons/obsidian-mermaid-watch.service を参照

• Windows（タスクスケジューラ / PowerShell）: examples/daemons/register-task-windows.bat を参照

👉 デーモン設定の詳細ガイド: docs/daemon-setup.md

🔌 使用方法 2: MCP ツールモード

obsidian-mermaid-mcp を、お好みの AI ホストで標準の MCP サーバーとして設定します。

MCP 設定例

{
  "mcpServers": {
    "obsidian-mermaid": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-mermaid-mcp/packages/mcp-server/dist/index.js"],
      "env": {
        "OBSIDIAN_MERMAID_VAULT_ROOT": "/absolute/path/to/your/vault"
      }
    }
  }
}

👉 10 以上の AI ホスト（Codex、Claude Code、Cursor、Windsurf、Cline、Roo Code、Goose、Zed など）向けの完全な設定ガイド: docs/host-configs.md を参照してください。

利用可能な MCP ツール

📁 仕組み: ボールトの変換

変換前（標準 Markdown）

# Architecture Overview

```mermaid
flowchart LR
    Client --> Server
    Server --> Database
```

変換後（クリーンな埋め込み SVG ＋ サイドカー）

# Architecture Overview

![[assets/Architecture/mermaid-001-f97437d9e714d8ee.svg|600]]

生成されるファイル構造

MyVault/
├── Architecture.md
└── assets/
    └── Architecture/
        ├── mermaid-001-f974.svg   # Sanitized, high-resolution SVG
        └── mermaid-001-f974.mmd   # Exact Mermaid source backup

⚙️ 設定リファレンス

JSON 設定ファイル（--config /path/to/config.json）または環境変数で動作をカスタマイズできます。

config.json の例:

{
  "configVersion": 1,
  "vaultRoot": "/path/to/vault",
  "assetRoot": "assets",
  "attachmentPattern": "{note_dir}/assets/{note_name}/mermaid-{index}-{hash}.svg",
  "sourcePattern": "{note_dir}/assets/{note_name}/mermaid-{index}-{hash}.mmd",
  "embedWidth": 600,
  "theme": "default",
  "background": "transparent",
  "sourceStorage": "both",
  "failurePolicy": "partial",
  "renderer": {
    "timeoutMs": 30000,
    "browserIdleTimeoutMs": 300000,
    "maxConcurrentRenders": 1,
    "htmlLabels": false,
    "securityLevel": "strict",
    "executablePath": ""
  },
  "watcher": {
    "enabled": true,
    "debounceMs": 3000,
    "apply": true
  }
}

テンプレートプレースホルダー

• {note_dir}: ボールトルートからのノートのサブディレクトリ（例: SEM_AI/chapter1、ルートノートの場合は空）。

• {note_name}: .md 拡張子を除いたノートの安全なファイル名。

• {asset_root}: 設定されたアセットルート（デフォルト: assets）。

• {index}: ノート内の図の 3 桁のインデックス（001、002 など）。

• {hash}: Mermaid ソースの 16 文字の SHA-256 フィンガープリント。

• {ext}: ファイル拡張子（svg または mmd）。

🔍 トラブルシューティング＆FAQ

1. ブラウザが見つからない

デフォルトでは、サーバーは標準の macOS、Linux、Windows ディレクトリで Google Chrome、Chromium、Microsoft Edge、Brave、または Arc を検索します。カスタムの場所にインストールされている場合は、以下を設定します:

export PUPPETEER_EXECUTABLE_PATH="/custom/path/to/chrome"

または、config.json で "renderer.executablePath" を指定します。

2. ダークテーマのサポート

config.json で "theme": "dark" を設定するか、MCP ツール呼び出しで "theme": "dark" を渡します。"theme": "auto" と "themeContext": "dark" を組み合わせて使用することもできます。

3. 変換済みの図を編集する方法

• オプション A: restore_note（MCP または CLI 経由）を実行してノートを ```mermaid コードブロックに戻し、編集して再同期させます。

• オプション B: assets/ フォルダ内の生成された .mmd サイドカーファイルを直接編集します。Watcher / Sync エンジンがサイドカーの変更を自動検出し、SVG を再生成します。

📄 ライセンス

MIT ライセンス。詳細は LICENSE を参照してください。