iMessage RAG MCP

ローカルのmacOS iMessage履歴をAIアシスタントから検索可能にするMCPサーバーです。

chat.dbをローカルのSQLiteデータベースに同期し、会話をコンテキストを考慮したチャンクに分割し、MCPエンドポイント経由でハイブリッド検索（密ベクトル＋語彙ベース、融合・再ランク付け）を提供します。すべてローカルで実行され、メッセージデータがマシンの外に出ることはありません。

特徴

• ハイブリッド検索 — FAISSの密ベクトル検索とTF-IDFの語彙ベース検索を相互ランク融合で融合し、クロスエンコーダーで再ランク付けします。

• 会話を考慮したチャンク分割 — メッセージを時間間隔でセッションにグループ化し、重複を持たせてチャンク化することで、取得したパッセージの一貫性を保ちます。

• コンテキスト拡張 — 結果には一致したチャンクだけでなく、周囲のメッセージも含まれます。

• 連絡先名の解決 — 電話番号とメールアドレスをmacOSのアドレス帳から実際の名前にマッピングします。

• 増分同期 — ソースデータベースのフィンガープリントにより、変更がない場合の冗長な作業を回避します。

• ローカルのみ — Appleのデータベースを読み取り専用で読み取り、すべてのインデックスはディスク上に保持されます。

Related MCP server: iMessage Max

要件

• macOS（~/Library/Messages/chat.dbを読み取ります）

• Python 3.10以上

• サーバーを実行するプログラム（ターミナル、iTerm、PyCharmなど）にフルディスクアクセスを許可してください。システム設定 → プライバシーとセキュリティ → フルディスクアクセスで許可し、そのプログラムを再起動してください。

インストール

git clone git@github.com:jaredtkatz/imessage-rag-mcp.git
cd imessage-rag-mcp
python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

初回実行時に、Hugging Faceから埋め込みモデルと再ランクモデルをダウンロードします（数百MB）。

使用方法

インデックスを構築してサーバーを起動します：

SYNC_ON_STARTUP=true ./run.sh

初回の同期とインデックス構築は、メッセージ履歴のサイズによっては数分かかることがあります。以降の実行では、フラグを省略して同期をスキップし、既存のインデックスに対してすぐに起動できます：

./run.sh

run.shは以下の薄いラッパーです：

python -m uvicorn mcp_server:app --host 0.0.0.0 --port 8000 --reload

MCPクライアントの接続

MCPクライアントを次の場所に向けます：

http://localhost:8000/mcp

HTTPエンドポイント

両方のエンドポイントはHTTP経由でも直接利用できます：

• GET /search?query=...&limit=8 — 完全なハイブリッドパイプライン（密ベクトル＋語彙ベース → 融合 → 再ランク → コンテキスト拡張）。これはMCP経由で公開されるツールです。

• GET /lexical?query=...&limit=20 — TF-IDFの結果のみ。検索のデバッグに便利です。

設定

すべての設定は環境変数で、適切なデフォルト値を持ちます。シェルまたはプロジェクトルートの.envファイルで設定できます：

cp .env.example .env

シェル変数は.envより優先されるため、単一の実行でファイルの値を上書きできます：

SYNC_ON_STARTUP=true ./run.sh

.envはgitignoreされています。

仕組み

1. 取り込み（ingest.py）— chat.dbから新規および最近変更された行を読み取り、text列が空の場合にattributedBodyからテキストを復元し、送信者名をアドレス帳に対して解決し、ローカルの正規データベースにアップサートします。

2. インデックス（indexer.py）— チャットごとにメッセージをグループ化し、時間間隔でセッションに分割し、各セッションを重複付きでチャンク化し、FAISSインデックスとTF-IDF行列を書き込みます。

3. 取得（rag.py）— 密ベクトル検索と語彙ベース検索を実行し、RRFでランキングを融合し、クロスエンコーダーで再ランク付けし、重複するチャンクを削除し、各結果を周囲のメッセージで拡張します。

4. 提供（mcp_server.py）— パイプラインをFastAPIアプリとして公開し、MCPサーバーとしてマウントします。

プロジェクト構成

config.py       Environment-driven settings and file paths
db.py           SQLAlchemy models for chat.db, Address Book, and local storage
ingest.py       Sync from chat.db into the canonical database
indexer.py      Session splitting, chunking, and index construction
rag.py          Hybrid retrieval, fusion, reranking, context expansion
mcp_server.py   FastAPI application and MCP mount
run.sh          Development server launcher
.env.example    Template for local configuration

データ保存

生成された成果物はimessage_rag_data/（gitignore済み）に保存されます：

messages.sqlite   Canonical messages and chunks
messages.faiss    Dense vector index
lexical.joblib    TF-IDF vectorizer and matrix
state.json        Sync watermark and source fingerprint

ディレクトリを削除すると、クリーンな再構築が強制されます。

注意事項と制限

• 同期は起動時のみ、かつSYNC_ON_STARTUP=trueの場合のみ行われます。バックグラウンドやオンデマンドの同期はまだないため、新しいメッセージを取得するにはサーバーを再起動してください。

• 添付ファイル、リアクション、編集済みメッセージの履歴はインデックスされません。テキストのみです。

• uvicornを複数ワーカーで実行すると、現在MCPマウントで404が発生するため、サーバーはシングルワーカーで実行されます。

• コーパスが変更されるたびにインデックス全体がゼロから再構築されます。増分再インデックスはありません。