localdocs-mcp

100% 로컬 문서 검색 MCP 서버 — 내 컴퓨터의 txt / pdf / docx / pptx / xlsx / hwp / hwpx / 이미지를 인덱싱하고, Claude(또는 임의의 MCP 클라이언트)가 하이브리드(BM25 + 시맨틱) 검색으로 내부 자료를 찾아 인용하게 합니다.

파일은 제자리에 둡니다. 데이터는 기기 밖으로 나가지 않습니다.

"작년 전기카트 제안서에서 가격 조건 찾아줘"
  → Claude가 search_documents 호출
  → ~/Documents/제안서.docx 3번 청크 인용과 함께 답변

특징

• 한국 문서 네이티브: HWP 5.0(바이너리)과 HWPX를 외부 프로그램 없이 자체 파서로 추출 (macOS에선 레거시 .doc/.rtf도 textutil로 지원)

• 하이브리드 검색: SQLite FTS5(BM25) + bge-m3 임베딩 코사인 유사도를 RRF로 병합 — 고유명사·파일명 검색과 의미 검색을 모두 잡음

• 단일 저장소: 파일 메타·청크·FTS·벡터를 SQLite 한 개 DB에 트랜잭션으로 저장 — 벡터DB/검색인덱스 이중화로 인한 동기화 불일치가 구조적으로 없음

• 우아한 성능 저하(graceful degradation): Ollama가 없거나 꺼져 있어도 BM25 검색으로 정상 동작. 임베딩은 나중에 embed로 백필

• 침묵 실패 금지: 파싱 실패 파일은 사유와 함께 기록되고 index_status / list_indexed_files(only_errors=true)로 확인 가능

• 최소 의존성: docx/pptx/xlsx/hwpx는 표준 라이브러리(zip+XML)로 직접 파싱. 필수 의존성은 mcp, pypdf, olefile, numpy, httpx 뿐

• stdio 전용: 네트워크 포트를 열지 않아 MCP 스펙의 인증 공백 이슈를 원천 회피

설치

원커맨드(macOS) — uv·의존성·Ollama·모델·Claude 등록까지 자동:

git clone https://github.com/Huntbae/localdocs-mcp.git
cd localdocs-mcp
./install.sh                 # 표준(문서 + 시맨틱 검색)
# ./install.sh --with-ocr    # 이미지 OCR 포함
# ./install.sh --no-ollama   # 키워드(BM25)만

전체 설치·사용·두 번째 기기(맥북프로) 설치·트러블슈팅은 docs/INSTALL.ko.md 참고.

수동 설치:

uv venv --python 3.11 && uv pip install -e .

# 선택: 이미지 OCR (easyocr, 용량 큼)
uv pip install -e ".[ocr]"

시맨틱 검색을 쓰려면 Ollama 설치 후:

ollama pull bge-m3

Ollama 없이도 키워드(BM25) 검색은 완전히 동작합니다.

사용법

1. 인덱싱 (CLI)

# 폴더 인덱싱 (증분 — 변경된 파일만 다시 처리)
localdocs-mcp index ~/Documents ~/Desktop/자료

# 상태 확인 (실패 파일 수, 임베딩 진행률, 검색 모드)
localdocs-mcp status

# 검색 동작 확인
localdocs-mcp search "전기카트 보조금"

# 삭제된 파일 정리 / 임베딩 백필
localdocs-mcp prune
localdocs-mcp embed

2. Claude Desktop 등록

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "localdocs": {
      "command": "/절대경로/localdocs-mcp/.venv/bin/localdocs-mcp",
      "args": ["serve"]
    }
  }
}

3. Claude Code 등록

claude mcp add localdocs -- /절대경로/localdocs-mcp/.venv/bin/localdocs-mcp serve

MCP 툴

아키텍처

파일 (txt/pdf/docx/pptx/xlsx/hwp/hwpx/이미지)
  → 추출기 (stdlib zip+XML, pypdf, 자체 HWP5 파서, textutil, easyocr*)
  → 청킹 (문단 경계 존중, 1200자, 150자 오버랩, 페이지/슬라이드 메타)
  → SQLite 단일 DB
      ├ files / chunks        (원문·출처·실패 기록)
      ├ chunks_fts (FTS5)     (BM25 키워드 검색)
      └ embeddings (BLOB)     (bge-m3 벡터, 없어도 동작)
  → MCP 서버 (FastMCP, stdio) — 검색·조회 전용 얇은 계층
                                 * = 선택 설치

운영 원칙: 무거운 인덱싱은 CLI(또는 cron/launchd), MCP 서버는 검색만.

주기적 자동 인덱싱 예시 (macOS launchd 대신 crontab):

# 매시간 증분 인덱싱
0 * * * * /절대경로/.venv/bin/localdocs-mcp index ~/Documents >> ~/.localdocs-mcp/cron.log 2>&1

환경변수

설계 결정 (방법론 재검토 반영)

초기 설계안 대비 다음 문제를 식별하고 수정했습니다:

1. ChromaDB + SQLite 이중 저장소 → SQLite 단일화. 두 저장소는 재인덱싱·삭제 시 동기화 드리프트가 필연적. 개인 코퍼스 규모(수십만 청크)에서는 numpy 전수 코사인이 충분히 빠르므로 벡터DB 자체를 제거.

2. Ollama 하드 의존 → 선택적 구성요소. 임베딩 불가 시 BM25 단독 모드로 자동 전환하고 status에 모드를 명시.

3. markitdown/kordoc 등 무거운 변환기 의존 → stdlib 우선. docx/pptx/xlsx/hwpx는 ZIP+XML이므로 직접 파싱. HWP 5.0도 olefile+zlib로 자체 구현(PrvText 폴백 포함). 외부 도구는 선택 설치로 강등.

4. 인덱서와 서버 결합 → 분리. 첫 인덱싱은 수 시간이 걸릴 수 있어 MCP 요청 경로에서 제거.

5. 실패 침묵 → 실패 기록 의무화. HWP 구버전 등 파싱 실패는 반드시 발생하므로 파일 단위로 사유를 남기고 조회 툴을 제공.

6. 인덱스 신선도 미표기 → 검색 응답에 index_freshness 포함. LLM이 오래된 결과임을 인지하고 답변에 반영 가능.

로드맵

• 스캔 PDF OCR 파이프라인 (텍스트 레이어 없는 PDF 자동 감지 → OCR)

• 이미지 캡셔닝 (로컬 비전 LLM로 사진류 인덱싱)

• 재랭킹 (bge-reranker) 옵션

• watchdog 기반 실시간 폴더 감시 데몬

• 검색 품질 평가 하네스 (질의-정답 셋 회귀 테스트)

개발

uv pip install -e ".[dev]"
.venv/bin/pytest

라이선스

MIT