iMessage RAG MCP

MCP-сервер, который делает вашу локальную историю iMessage на macOS доступной для поиска ИИ-ассистентами.

Он синхронизирует chat.db в локальную базу данных SQLite, разбивает разговоры на контекстно-зависимые фрагменты и предоставляет гибридный поиск (плотный + лексический, с объединением и реранжированием) через MCP-эндпоинт. Всё работает локально — данные сообщений не покидают ваш компьютер.

Возможности

• Гибридный поиск — плотный векторный поиск FAISS объединяется с лексическим поиском TF-IDF через reciprocal rank fusion, затем реранжируется с помощью cross-encoder.

• Разбиение с учётом контекста разговора — сообщения группируются в сессии по временным промежуткам, затем разбиваются на фрагменты с перекрытием, чтобы найденные отрывки оставались связными.

• Расширение контекста — результаты включают окружающие сообщения, а не только совпадающий фрагмент.

• Определение имён контактов — номера телефонов и адреса электронной почты сопоставляются с реальными именами из вашей адресной книги macOS.

• Инкрементальная синхронизация — отпечаток исходной базы данных позволяет избежать лишней работы, если ничего не изменилось.

• Только локально — базы данных Apple читаются в режиме только для чтения; все индексы остаются на диске.

Related MCP server: iMessage Max

Требования

• macOS (читает ~/Library/Messages/chat.db)

• Python 3.10+

• Полный доступ к диску для программы, которая запускает сервер (Terminal, 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 (несколько сотен МБ).

Использование

Создайте индекс и запустите сервер:

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 игнорируется git.

Как это работает

1. Загрузка (ingest.py) — читает новые и недавно изменённые строки из chat.db, восстанавливает текст из attributedBody, когда обычный столбец text пуст, сопоставляет имена отправителей с адресной книгой и выполняет upsert в локальную каноническую базу данных.

2. Индексация (indexer.py) — группирует сообщения по чатам, разбивает их на сессии по временным промежуткам, разбивает каждую сессию на фрагменты с перекрытием, затем создаёт индекс FAISS и матрицу TF-IDF.

3. Поиск (rag.py) — выполняет плотный и лексический поиск, объединяет ранжирования с помощью RRF, реранжирует с помощью cross-encoder, удаляет перекрывающиеся фрагменты и расширяет каждый результат окружающими сообщениями.

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/ (игнорируется git):

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 с несколькими воркерами в настоящее время вызывает ошибки 404 на MCP-подключении, поэтому сервер работает с одним воркером.

• Весь индекс пересобирается с нуля при каждом изменении корпуса; инкрементальной переиндексации нет.