obsidian-mermaid-mcp

모든 AI 에이전트를 위한 Obsidian 볼트의 로컬, 제로 토큰, 무손실 Mermaid 렌더링 및 역방향 노트 동기화.

🌟 주요 특징

• ✍️ 프롬프트 없는 에이전트 작성 경험 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 도구 모드

선호하는 AI 호스트에서 obsidian-mermaid-mcp를 표준 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"를 전달하세요. "themeContext": "dark"와 함께 "theme": "auto"를 사용할 수도 있습니다.

3. 이미 변환된 다이어그램을 편집하는 방법

• 옵션 A: restore_note를 실행(MCP 또는 CLI 통해)하여 노트를 mermaid 코드 블록으로 복원한 후 편집하고 다시 동기화하세요.

• 옵션 B: assets/ 폴더에서 생성된 .mmd 사이드카 파일을 직접 편집하세요. Watcher/동기화 엔진이 사이드카 변경을 자동으로 감지하여 SVG를 재생성합니다!

📄 라이선스

MIT 라이선스. 자세한 내용은 LICENSE를 참조하세요.