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 스펙의 인증 공백 이슈를 원천 회피

설치

git clone https://github.com/Huntbae/localdocs-mcp.git
cd localdocs-mcp
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 툴

툴	설명
search_documents(query, top_k, path_prefix, file_suffix)	하이브리드 검색. 결과에 파일 경로·청크·점수·인덱스 신선도 포함
get_chunk_context(chunk_id, neighbors)	검색된 청크의 앞뒤 문맥 확장
get_document(path, max_chars, offset)	문서 전문 읽기(긴 문서는 이어 읽기)
list_indexed_files(path_prefix, only_errors, limit)	인덱스 목록·실패 파일 사유 조회
index_path(path)	파일/소규모 폴더 즉시 (재)인덱싱
index_status()	파일/청크/임베딩 통계, Ollama 가용성, 검색 모드

아키텍처

파일 (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

환경변수

변수	기본값	설명
LOCALDOCS_DB	~/.localdocs-mcp/index.db	인덱스 DB 경로
OLLAMA_HOST	http://127.0.0.1:11434	Ollama 주소
LOCALDOCS_EMBED_MODEL	bge-m3	임베딩 모델 (bona/bge-m3-korean 등으로 교체 가능)
LOCALDOCS_CHUNK_MAX_CHARS	1200	청크 최대 길이
LOCALDOCS_MAX_FILE_MB	100	이 크기 초과 파일은 건너뜀

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

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

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