obsidian-mermaid-mcp

Локальный, без токенов, без потерь рендеринг Mermaid и обратимая синхронизация заметок для хранилищ Obsidian во всех AI-агентах.

🌟 Ключевые особенности

• ✍️ Опыт написания без промптов AI-агенты (Codex, Claude Code, Antigravity, Cursor, Windsurf, Cline и др.) могут естественно писать стандартный Markdown с блоками ```mermaid . Фоновый Watcher автоматически преобразует их во встроенные SVG в течение ~2 секунд без необходимости специальных промптов.

• 🔒 100% локально и приватно Рендерится локально через headless Chrome/Puppeteer. Никаких облачных API рендеринга, никаких затрат токенов и нулевых утечек в сеть.

• 🔄 Без потерь и полностью обратимо Исходный код Mermaid безопасно сохраняется как в боковых файлах .mmd, так и в <metadata> SVG. В любой момент можно одним кликом вернуться к исходным блокам кода 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 в фоновом режиме, чтобы автоматически преобразовывать любые новые или отредактированные блоки Mermaid в ваших заметках Obsidian.

Тест в переднем плане

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 как стандартный MCP-сервер в вашем любимом AI-хосте.

Пример конфигурации 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}: трёхзначный индекс диаграммы в заметке (001, 002 и т.д.).

• {hash}: 16-символьный отпечаток SHA-256 исходного кода Mermaid.

• {ext}: расширение файла (svg или mmd).

🔍 Устранение неполадок и FAQ

1. Браузер не найден

По умолчанию сервер ищет Google Chrome, Chromium, Microsoft Edge, Brave или Arc в стандартных каталогах macOS, Linux и Windows. Если он установлен в нестандартном месте, укажите:

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

Или укажите "renderer.executablePath" в вашем config.json.

2. Поддержка тёмной темы

Установите "theme": "dark" в config.json или передайте "theme": "dark" в вызовах MCP-инструментов. Также можно использовать "theme": "auto" с "themeContext": "dark".

3. Как отредактировать уже преобразованную диаграмму

• Вариант A: Запустите restore_note (через MCP или CLI), чтобы вернуть заметку к блокам ```mermaid, отредактируйте её и дайте ей повторно синхронизироваться.

• Вариант B: Напрямую отредактируйте сгенерированный боковой файл .mmd в папке assets/. Watcher / движок синхронизации автоматически обнаружит изменение бокового файла и перегенерирует SVG!

📄 Лицензия

Лицензия MIT. Подробности см. в LICENSE.