Obsidian Index Service

Obsidian Index Service

このサービスは、Obsidian の保管庫ディレクトリを監視し、Markdown ファイルのメタデータ と 全文を SQLite データベースにインデックス化します。私の mcp-server プロジェクトと連携するように作成しましたが、Obsidian のプラグイン API を使う実装に切り替えました。それでも、汎用的なノートインデクサーや同期ツールとして活用できると考えているため（「今後のステップ」の注記を参照）、ここに公開します。

機能

Obsidian の保管庫内のファイル変更（作成、変更、削除）を追跡し、すべての情報を SQLite に保存します。データベースには Docker ボリューム経由でアクセスできます。記録される情報は次のとおりです。

• パス：ファイルパス（一意の識別子）
• タイトル：ファイル名から取得
• 親フォルダー：保管庫のルートからの相対パス
• タグ：YAML フロントマターから取得
• 作成日：ファイルシステムのタイムスタンプ
• 更新日：ファイルシステムのタイムスタンプ
• コンテンツ：ノートの全文
• ステータス：処理結果（成功／エラー）
• エラーメッセージ：処理に失敗した場合の詳細

セットアップと使い方

前提条件

• Python 3.12 以降
• Docker と Docker Compose（コンテナで使用する場合）
• uv（任意ですが、推奨）

インストール

1. リポジトリをクローンします。

    git clone https://github.com/pmmvr/obsidian-index-service.git
    cd obsidian-index-service
   

2. 仮想環境をセットアップします。

   • uv を使用する場合（推奨）：

     uv venv
     source .venv/bin/activate # Linux/macOS
     .venv\Scripts\activate # Windows
     

   • python を使用する場合（標準）：

     python -m venv .venv
     source .venv/bin/activate  # Linux/macOS
     .venv\Scripts\activate     # Windows
     

3. 依存関係をインストールします。

   • uv を使用する場合（推奨）：

     uv sync  # Installs from uv.lock
     uv pip install pytest pytest-bdd pytest-mock  # For tests
     

   • pip を使用する場合：

     pip install -e .
     pip install pytest pytest-bdd pytest-mock  # For tests
     

ローカルでの実行

環境変数を設定します。

export OBSIDIAN_VAULT_PATH=/path/to/vault
export DB_PATH=/path/to/notes.sqlite

実行します。

python main.py

uv を使用する場合：

uv run python main.py

1 回限りのスキャンを実行する場合：

python main.py --scan-only

または、uv を使用します。

uv run python main.py --scan-only

コマンドラインオプション

• --vault-path：保管庫ディレクトリのパス
• --db-path：SQLite データベースのパス
• --scan-only：監視せずにスキャン

Docker の使用

1. ビルドして実行します。

   docker-compose up -d
   

2. 保管庫をマウントし、SQLite データベースを公開します。

他のサービスからの読み取り専用アクセス

別のサービスがデータベースを読み取れるようにするには（変更のスキャンなど）：

1. docker-compose.yml で obsidian-index-service と同じボリュームを使用します。

   services:
     your-service:
       image: your-image
       volumes:
         - ${DB_VOLUME_PATH:-./data}:/data:ro  # Read-only mount
   

2. Obsidian Index Service は /data/notes.sqlite（読み書き可能としてマウント）に書き込み、他のサービス（例：mcp-server）はそこから読み取ります。SQLite の WAL モードが同時アクセスを処理します。

仕組み

Obsidian Index Service は、次のプロセスで動作します。

1. 起動（ObsidianIndexService.__init__）

   • 環境変数またはコマンドライン引数から設定を読み込みます
   • データベース接続（DatabaseConnection）を初期化します
   • ノートプロセッサー（NoteProcessor）をセットアップします
   • 正常なシャットダウンのためのシグナルハンドラーを設定します

2. データベースの初期化（DatabaseConnection.__init__）

   • SQLite データベースを作成または接続します
   • 同時実行性を高めるため、データベースを WAL（Write-Ahead Logging）モードに設定します
   • 存在しない場合は、パス、タイトル、タグなどの列を含む notes テーブルを作成します

3. Vault の初回スキャン（NoteProcessor.scan_vault）

   • Vault ディレクトリ内のすべての Markdown ファイル（.md、.markdown）を検索します
   • 各ファイルからメタデータを抽出します
   • 抽出したすべてのメタデータをデータベースに追加します（NoteOperations.insert_note）

4. 継続的な監視（FileWatcher.watch）

   • ファイルシステムイベントを監視するため、Vault ディレクトリを監視します
   • 次のような各種イベントを処理します。
     • ファイルの作成：新しいファイルをインデックスに登録します
     • ファイルの変更：変更されたファイルのインデックスを更新します
     • ファイルの削除：インデックスからエントリを削除します
     • ファイルの移動／名前変更：パス情報を更新します

5. ファイル処理（NoteProcessor.process_note）

   • Markdown ファイルからメタデータを抽出します
   • パス、タイトル、親フォルダー、タグ、作成日／変更日が含まれます
   • この情報でデータベースを更新します（NoteOperations.upsert_note）

6. 正常なシャットダウン（ObsidianIndexService.shutdown）

   • 終了シグナルを受信した際に、ファイル監視とデータベース接続を適切に閉じます

このサービスはバックグラウンドで動作し、SQLite データベースを Obsidian Vault と継続的に同期します。これにより、他のアプリケーションは Markdown ファイルを直接解析することなく、このデータベースからノートのメタデータにアクセスできます。

開発

テストを実行します。

pytest

プロジェクトの状況

• 完了：コアのインデックス機能（メタデータ＋コンテンツ）、Docker のセットアップ、ファイル監視、データベースの CRUD。
• 次の予定：API を計画していましたが、代わりにプラグイン方式を採用しました。

今後のステップ（同期ツールの可能性）

いくつか手を加えれば、同期ツールとして活用できそうです。

• リモートバックエンド：クラウドストレージ（Dropbox など）またはサーバーのサポートを追加します。
• 同期ロジック：ローカルの変更（コンテンツ＋メタデータ）をリモートにプッシュし、リモートの更新を取得して、競合（最終書き込み優先など）に対処します。
• データベースの調整：sync_status 列と remote_id 列を追加します。
• ファイル監視の更新：変更をインデックス登録だけでなく、同期用にキューに追加します。
• CLI オプション：手動または継続的に同期を実行する --sync を追加します。
• エラー処理：ネットワーク障害時に再試行し、問題をログに記録します。