obsidian-mermaid-mcp

Lokale, tokenfreie, verlustfreie Mermaid-Darstellung und reversible Notiz-Synchronisierung für Obsidian-Vaults über alle KI-Agenten hinweg.

🌟 Hauptmerkmale

• ✍️ Prompt-freies Agent-Schreiberlebnis KI-Agenten (Codex, Claude Code, Antigravity, Cursor, Windsurf, Cline usw.) können ganz natürlich standardmäßiges Markdown mit ```mermaid-Codeblöcken schreiben. Der Hintergrund-Watcher konvertiert sie automatisch in eingebettete SVGs innerhalb von ~2 Sekunden, ohne dass spezielle Prompts erforderlich sind.

• 🔒 100% lokal & privat Rendert lokal über headless Chrome/Puppeteer. Keine Cloud-Rendering-APIs, keine Token-Kosten und keine Netzwerklecks.

• 🔄 Verlustfrei & vollständig reversibel Der ursprüngliche Mermaid-Code wird sicher in .mmd-Sidecar-Dateien und SVG-<metadata> aufbewahrt. Mit einem Klick jederzeit zurück in die ursprünglichen Mermaid-Codeblöcke umwandelbar.

• 🧠 Intelligente Vault-Anpassung Erkennt automatisch .obsidian/app.json (unterstützt ordnerrelative assets/${filename}, Vault-Wurzel-attachments und gleichordnerige Setups) ohne Konfiguration.

• ⚡ Zwei Betriebsmodi

  1. Automatischer Watcher-Modus (Hintergrund-Datei-Watcher für nahtloses Schreiben)

  2. MCP-Tool-Modus (4 standardmäßige stdio-MCP-Tools für direkte Agent-Aufrufe)

• 💻 Universelle Plattformunterstützung macOS, Linux, Windows, WSL und Docker.

🚀 Schnellstart

Voraussetzungen

• Node.js: >= 20.0.0

• Chrome / Chromium / Edge / Brave / Arc: An einem Standardort installiert oder über PUPPETEER_EXECUTABLE_PATH angegeben.

Installation & Build (Lokales Node.js)

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

Installation & Build (Docker-Alternative)

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

👉 Detaillierter Docker-Leitfaden (MCP-Server & Docker Compose): docs/docker-guide.md

🛠️ Verwendungsmodus 1: Automatischer Watcher (Empfohlen)

Führen Sie den Watcher im Hintergrund aus, um neu geschriebene oder bearbeitete Mermaid-Blöcke in Ihren Obsidian-Notizen automatisch zu konvertieren.

Vordergrund-Test

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

Hinweis: --apply ist für tatsächliche Dateischreibvorgänge erforderlich. Ohne --apply arbeitet der Watcher nur im Vorschau-Modus.

Hintergrund-Daemon-Einrichtung

Wir bieten gebrauchsfertige Hintergrunddienst-Vorlagen für alle gängigen Plattformen:

• macOS (LaunchAgent): Siehe examples/daemons/com.obsidian-mermaid.watch.plist

• Linux (systemd-Benutzerdienst): Siehe examples/daemons/obsidian-mermaid-watch.service

• Windows (Task Scheduler / PowerShell): Siehe examples/daemons/register-task-windows.bat

👉 Detaillierter Daemon-Einrichtungsleitfaden: docs/daemon-setup.md

🔌 Verwendungsmodus 2: MCP-Tool-Modus

Konfigurieren Sie obsidian-mermaid-mcp als standardmäßigen MCP-Server in Ihrem bevorzugten KI-Host.

MCP-Konfigurationsbeispiel

{
  "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"
      }
    }
  }
}

👉 Vollständiger Konfigurationsleitfaden für 10+ KI-Hosts (Codex, Claude Code, Cursor, Windsurf, Cline, Roo Code, Goose, Zed usw.): Siehe docs/host-configs.md.

Verfügbare MCP-Tools

📁 So funktioniert's: Vault-Transformation

Vor der Konvertierung (Standard-Markdown)

# Architecture Overview

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

Nach der Konvertierung (Sauberes eingebettetes SVG + Sidecar)

# Architecture Overview

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

Generierte Dateistruktur

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

⚙️ Konfigurationsreferenz

Sie können das Verhalten über eine JSON-Konfigurationsdatei (--config /pfad/zu/config.json) oder Umgebungsvariablen anpassen.

Beispiel 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
  }
}

Vorlagen-Platzhalter

• {note_dir}: Unterverzeichnis der Notiz relativ zur Vault-Wurzel (z. B. SEM_AI/chapter1 oder leer für Wurzelnotizen).

• {note_name}: Sicherer Dateiname der Notiz ohne .md-Erweiterung.

• {asset_root}: Konfiguriertes Asset-Root (Standard: assets).

• {index}: 3-stelliger Index des Diagramms innerhalb der Notiz (001, 002 usw.).

• {hash}: 16-stelliger SHA-256-Fingerabdruck der Mermaid-Quelle.

• {ext}: Dateierweiterung (svg oder mmd).

🔍 Fehlerbehebung & FAQ

1. Browser nicht gefunden

Standardmäßig durchsucht der Server standardmäßige macOS-, Linux- und Windows-Verzeichnisse nach Google Chrome, Chromium, Microsoft Edge, Brave oder Arc. Wenn an einem benutzerdefinierten Ort installiert, setzen Sie:

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

Oder geben Sie "renderer.executablePath" in Ihrer config.json an.

2. Dunkles Theme unterstützen

Setzen Sie "theme": "dark" in config.json oder übergeben Sie "theme": "dark" in MCP-Tool-Aufrufen. Sie können auch "theme": "auto" mit "themeContext": "dark" verwenden.

3. So bearbeiten Sie ein bereits konvertiertes Diagramm

• Option A: Führen Sie restore_note (über MCP oder CLI) aus, um die Notiz zurück in ```mermaid-Codeblöcke umzuwandeln, bearbeiten Sie sie und lassen Sie sie erneut synchronisieren.

• Option B: Bearbeiten Sie direkt die generierte .mmd-Sidecar-Datei im assets/-Ordner. Der Watcher / die Sync-Engine erkennt die Sidecar-Änderung automatisch und generiert das SVG neu!

📄 Lizenz

MIT-Lizenz. Siehe LICENSE für Details.