# 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のセットアップ

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

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

### 2. 環境変数の設定

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

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

### 3. インストール

```bash
npm install
npm run build
```

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

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

```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** - セマンティック検索
```typescript
{
  "query": "プロジェクト管理",
  "max_results": 5
}
```
- RAG対応でコンテキストを考慮した検索
- 類似度スコア付きの結果返却

### 2. **add_note** - ノート追加
```typescript
{
  "title": "2024年プロジェクト計画",
  "content": "## 概要\n\n今日の会話で決定した内容...",
  "tags": ["project", "2024", "planning"]
}
```
- 自動的にfrontmatterとタグを付与
- 重複ファイル名の自動処理

### 3. **list_recent_notes** - 最近のノート一覧
```typescript
{
  "limit": 10
}
```
- 最近更新されたノートの一覧表示

### 4. **reset_database** - データベースリセット
```typescript
{
  "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に接続できない
```bash
# Dockerが起動しているか確認
docker ps | grep chroma

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

### ベクターストアが初期化されない
- OpenAI APIキーが正しく設定されているか確認
- Vault内にマークダウンファイルが存在するか確認

### キャッシュが効かない
- `.embedding-cache.json`の権限を確認
- ディスク容量が十分にあるか確認

### 重複エントリが発生する場合
```typescript
// reset_databaseツールを使用してリセット
{
  "tool": "reset_database",
  "confirm": true
}
```
- データベースとキャッシュを完全にリセットして再構築
- 全ファイルの再インデックスが実行される

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

## 📄 ライセンス

MIT