Obsidian MCP Server

MCP (Model Context Protocol) サーバーによるObsidian Vaultの管理と検索を可能にするRAG対応システム

🚀 主な改善点

1. Chroma DBによる永続化

• メモリベースのベクターストアからChroma DBに移行
• Embeddingの永続化により、再起動時の再計算を回避
• 分散環境での利用が可能

2. 差分更新システム

• ファイルごとのコンテンツハッシュによる変更検出
• 更新日時とハッシュの二重チェックで確実な差分検出
• 変更されたファイルのみEmbedding再作成

3. キャッシュシステム

• .embedding-cache.jsonによる状態管理
• ファイルごとのメタデータ（更新日時、ハッシュ、Document ID）を保存
• 起動時に前回の状態から差分のみ更新

4. 重複防止とID管理

• 決定的なDocument ID生成により重複を防止
• ファイルパスとチャンクインデックスから一意のIDを生成
• 同じコンテンツは常に同じIDを持つ

5. 初期化の最適化

• キャッシュ存在時は変更ファイルのみ読み込み
• 初回起動とそれ以降で異なる処理パス
• メモリ使用量を削減

📊 パフォーマンス改善

Before（問題点）

• 起動時に全ファイルのEmbedding再作成
• ファイル変更時に全Vector Store再構築
• OpenAI APIの大量呼び出しによるコスト増大
• 同じチャンクが重複して追加される問題

After（改善後）

• 起動時は変更ファイルのみEmbedding作成
• ファイル変更時は該当ファイルのみ更新
• APIコールを最小限に削減（最大90%削減）
• 決定的なID生成により重複を完全に防止
• 2回目以降の起動時間を大幅に短縮（数秒以内）

🛠 セットアップ

1. Chroma DBのセットアップ

# Dockerでの起動（推奨）
docker run -d -p 8000:8000 chromadb/chroma

# または、ローカルインストール
pip install chromadb
chroma run --host localhost --port 8000

2. 環境変数の設定

# 必須
OPENAI_API_KEY=your-openai-api-key
OBSIDIAN_VAULT_PATH=/path/to/your/vault

# オプション（デフォルト: http://localhost:8000）
CHROMA_URL=http://localhost:8000

3. インストール

npm install
npm run build

4. MCPクライアントの設定

Claude Desktop の場合 (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp-server/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault",
        "OPENAI_API_KEY": "sk-your-openai-api-key",
        "CHROMA_URL": "http://localhost:8000"
      }
    }
  }
}

📝 機能

1. search_vault - セマンティック検索

{
  "query": "プロジェクト管理",
  "max_results": 5
}

• RAG対応でコンテキストを考慮した検索
• 類似度スコア付きの結果返却

2. add_note - ノート追加

{
  "title": "2024年プロジェクト計画",
  "content": "## 概要\n\n今日の会話で決定した内容...",
  "tags": ["project", "2024", "planning"]
}

• 自動的にfrontmatterとタグを付与
• 重複ファイル名の自動処理

3. list_recent_notes - 最近のノート一覧

{
  "limit": 10
}

• 最近更新されたノートの一覧表示

4. reset_database - データベースリセット

{
  "confirm": true
}

• ベクターデータベースの完全リセット
• キャッシュのクリアと全ファイルの再インデックス
• 不整合が発生した場合の復旧用

🔧 技術スタック

• TypeScript: 型安全な実装
• Chroma DB: ベクターデータベース（永続化対応）
• LangChain: Embedding・ベクター検索フレームワーク
• OpenAI Embeddings: text-embedding-3-small
• MCP SDK: Model Context Protocol実装
• Chokidar: ファイル監視

📂 ディレクトリ構造

obsidian-mcp-server/
├── src/
│   └── index.ts         # メインサーバー実装
├── dist/                # ビルド出力
├── package.json
├── tsconfig.json
└── README.md

🔍 技術仕様

ベクターストア

• 埋め込みモデル: OpenAI text-embedding-3-small
• チャンクサイズ: 1000文字
• オーバーラップ: 200文字
• 永続化: Chroma DB

キャッシュシステム

• キャッシュファイル: .embedding-cache.json
• 保存場所: Vaultディレクトリ内
• 内容: ファイルハッシュ、更新日時、Document ID
• 更新タイミング: ファイル変更検出時に自動更新

Document ID管理

• ID生成方式: MD5ハッシュ（ファイルパス + チャンクインデックス）
• 重複防止: 決定的なID生成により同一チャンクの重複を防止
• 一貫性: 同じファイルの同じチャンクは常に同じIDを持つ

ファイル監視

• .obsidianなどの隠しディレクトリは除外
• マークダウンファイル（.md）のみを対象
• リアルタイムでファイルの変更を検知

🚨 注意事項

• Chroma DBが起動していることを確認してください
• 初回起動時は全ファイルのEmbedding作成のため時間がかかります
• .embedding-cache.jsonはVaultディレクトリに自動生成されます
• 大規模なVault（1000ファイル以上）の場合、初回起動に数分かかる場合があります
• 2回目以降の起動は差分のみ処理するため高速です（通常数秒以内）
• データベースの不整合が発生した場合はreset_databaseツールを使用してください

🐛 トラブルシューティング

Chroma DBに接続できない

# Dockerが起動しているか確認
docker ps | grep chroma

# 起動していない場合
docker run -d -p 8000:8000 chromadb/chroma

ベクターストアが初期化されない

• OpenAI APIキーが正しく設定されているか確認
• Vault内にマークダウンファイルが存在するか確認

キャッシュが効かない

• .embedding-cache.jsonの権限を確認
• ディスク容量が十分にあるか確認

重複エントリが発生する場合

// reset_databaseツールを使用してリセット
{
  "tool": "reset_database",
  "confirm": true
}

• データベースとキャッシュを完全にリセットして再構築
• 全ファイルの再インデックスが実行される

パフォーマンスの問題

• 初回起動が遅い: 全ファイルのEmbedding作成のため正常な動作です
• 2回目以降も遅い: キャッシュが正しく動作していない可能性
  • .embedding-cache.jsonが存在するか確認
  • ファイルの読み書き権限を確認

📄 ライセンス

MIT