obsidian-mermaid-mcp

Renderizado local de Mermaid sin tokens y sin pérdidas, y sincronización reversible de notas para bóvedas de Obsidian en todos los agentes de IA.

🌟 Características principales

• ✍️ Experiencia de escritura para agentes sin prompts Los agentes de IA (Codex, Claude Code, Antigravity, Cursor, Windsurf, Cline, etc.) pueden escribir Markdown estándar con bloques de código ```mermaid de forma natural. El observador en segundo plano los convierte automáticamente en SVG incrustados en ~2 segundos sin necesidad de prompts especiales.

• 🔒 100% local y privado Se renderiza localmente mediante Chrome/Puppeteer sin interfaz gráfica. Sin APIs de renderizado en la nube, sin costes de tokens y sin fugas de red.

• 🔄 Sin pérdidas y totalmente reversible El código Mermaid original se conserva de forma segura tanto en archivos laterales .mmd como en el <metadata> del SVG. Revierta al bloque de código Mermaid original en cualquier momento con un clic.

• 🧠 Adaptación inteligente a la bóveda Detecta automáticamente .obsidian/app.json (admite assets/${filename} relativo a la carpeta, attachments en la raíz de la bóveda y configuraciones en la misma carpeta) sin configuración.

• ⚡ Dos modos de funcionamiento

  1. Modo observador automático (observador de archivos en segundo plano para una escritura fluida)

  2. Modo herramienta MCP (4 herramientas MCP estándar de stdio para invocación directa por parte del agente)

• 💻 Soporte universal de plataformas macOS, Linux, Windows, WSL y Docker.

🚀 Inicio rápido

Requisitos

• Node.js: >= 20.0.0

• Chrome / Chromium / Edge / Brave / Arc: instalado en una ubicación estándar, o especifíquelo mediante PUPPETEER_EXECUTABLE_PATH.

Instalación y compilación (Node.js local)

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

Instalación y compilación (alternativa con Docker)

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

👉 Guía detallada de Docker (servidor MCP y Docker Compose): docs/docker-guide.md

🛠️ Modo de uso 1: Observador automático (recomendado)

Ejecute el observador en segundo plano para convertir automáticamente cualquier bloque Mermaid recién escrito o editado en sus notas de Obsidian.

Prueba en primer plano

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

Nota: --apply es necesario para escribir realmente en los archivos. Sin --apply, el observador funciona solo en modo de vista previa.

Configuración del demonio en segundo plano

Proporcionamos plantillas de servicios en segundo plano listas para usar para todas las plataformas principales:

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

• Linux (servicio de usuario systemd): consulte examples/daemons/obsidian-mermaid-watch.service

• Windows (Programador de tareas / PowerShell): consulte examples/daemons/register-task-windows.bat

👉 Guía detallada de configuración del demonio: docs/daemon-setup.md

🔌 Modo de uso 2: Modo herramienta MCP

Configure obsidian-mermaid-mcp como un servidor MCP estándar en su host de IA favorito.

Ejemplo de configuración 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"
      }
    }
  }
}

👉 Guía de configuración completa para más de 10 hosts de IA (Codex, Claude Code, Cursor, Windsurf, Cline, Roo Code, Goose, Zed, etc.): Consulte docs/host-configs.md.

Herramientas MCP disponibles

📁 Cómo funciona: Transformación de la bóveda

Antes de la conversión (Markdown estándar)

# Architecture Overview

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

Después de la conversión (SVG incrustado limpio + archivo lateral)

# Architecture Overview

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

Estructura de archivos generada

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

⚙️ Referencia de configuración

Puede personalizar el comportamiento mediante un archivo de configuración JSON (--config /ruta/a/config.json) o variables de entorno.

Ejemplo de 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
  }
}

Marcadores de posición de plantilla

• {note_dir}: subdirectorio de la nota relativo a la raíz de la bóveda (p. ej., SEM_AI/chapter1 o vacío para notas raíz).

• {note_name}: nombre de archivo seguro de la nota sin la extensión .md.

• {asset_root}: raíz de activos configurada (por defecto: assets).

• {index}: índice de 3 dígitos del diagrama dentro de la nota (001, 002, etc.).

• {hash}: huella digital SHA-256 de 16 caracteres del código fuente Mermaid.

• {ext}: extensión de archivo (svg o mmd).

🔍 Solución de problemas y preguntas frecuentes

1. No se encuentra el navegador

Por defecto, el servidor busca en los directorios estándar de macOS, Linux y Windows Google Chrome, Chromium, Microsoft Edge, Brave o Arc. Si está instalado en una ubicación personalizada, establezca:

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

O especifique "renderer.executablePath" en su config.json.

2. Soporte de tema oscuro

Establezca "theme": "dark" en config.json o pase "theme": "dark" en las llamadas a las herramientas MCP. También puede usar "theme": "auto" con "themeContext": "dark".

3. Cómo editar un diagrama ya convertido

• Opción A: ejecute restore_note (mediante MCP o CLI) para restaurar la nota a los bloques de código ```mermaid, edítela y deje que se vuelva a sincronizar.

• Opción B: edite directamente el archivo lateral .mmd generado en la carpeta assets/. El observador / motor de sincronización detectará automáticamente el cambio en el archivo lateral y regenerará el SVG.

📄 Licencia

Licencia MIT. Consulte LICENSE para más detalles.