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) — 파이프라인을 MCP 서버로 마운트된 FastAPI 앱으로 노출합니다.

프로젝트 구조

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가 발생하므로 서버는 단일 워커로 실행됩니다.

• 말뭉치가 변경될 때마다 전체 인덱스가 처음부터 다시 구축됩니다. 증분 재인덱싱은 없습니다.