hwp-rag-mcp 0.1.0

Local HWP/HWPX retrieval for Codex and Claude Code over MCP

HWP RAG MCP

hwp-rag-mcp는 바탕화면의 .hwp/.hwpx 문서를 로컬에서 파싱하고 검색할 수 있게 해 주는 MCP 서버입니다. 문서는 로컬 E5 임베딩과 FAISS로 색인되며, Codex 또는 Claude Code가 검색 근거를 받아 최종 답변을 작성합니다.

• 외부 문서 API나 OpenAI API 키가 필요하지 않습니다.
• 문서 내용과 벡터 인덱스는 사용자 컴퓨터에만 저장됩니다.
• 표, 각주, 미주, 메모의 LangChain 메타데이터를 유지합니다.
• 파일 변경 후 사용자가 명시적으로 동기화해야 하므로 검색 동작이 예측 가능합니다.

현재 버전은 개인용·소규모 데모 문서함을 대상으로 합니다. OCR, 이미지 검색, 자동 파일 감시, 원격 MCP 전송, 서버 내부 답변 생성은 지원하지 않습니다.

1. 준비

Python 3.10~3.13과 uv 사용을 권장합니다.

mkdir -p ~/Desktop/dataset

검색할 HWP/HWPX 파일을 ~/Desktop/dataset에 넣습니다. 하위 폴더도 재귀적으로 검색합니다. 심볼릭 링크와 다른 확장자는 무시합니다.

2. 최초 인덱스 생성

uvx --from hwp-rag-mcp hwp-rag-mcp sync \
  --dataset-dir ~/Desktop/dataset

최초 실행에서는 intfloat/multilingual-e5-small 모델과 로컬 추론 의존성을 다운로드하므로 시간과 디스크 공간이 필요합니다. 이후 모델 캐시와 인덱스가 유지되는 동안에는 오프라인 검색이 가능합니다.

상태 확인과 강제 재구축:

uvx --from hwp-rag-mcp hwp-rag-mcp status \
  --dataset-dir ~/Desktop/dataset

uvx --from hwp-rag-mcp hwp-rag-mcp sync \
  --dataset-dir ~/Desktop/dataset --force

--dataset-dir를 생략하면 HWP_RAG_DATASET_DIR 환경변수, 그다음 ~/Desktop/dataset을 사용합니다.

3. Codex 연결

CLI에서 로컬 STDIO MCP 서버를 등록합니다.

codex mcp add hwp-rag -- \
  uvx --from hwp-rag-mcp hwp-rag-mcp serve \
  --dataset-dir ~/Desktop/dataset

직접 설정할 경우 ~/.codex/config.toml에 다음을 추가할 수 있습니다. MCP 프로세스가 셸을 거치지 않는 환경을 고려하면 절대경로가 가장 안전합니다.

[mcp_servers.hwp-rag]
command = "uvx"
args = [
  "--from", "hwp-rag-mcp",
  "hwp-rag-mcp", "serve",
  "--dataset-dir", "/Users/your-name/Desktop/dataset",
]
tool_timeout_sec = 600

등록 후 codex mcp list 또는 Codex의 /mcp 메뉴에서 연결 상태를 확인합니다.

4. Claude Code 연결

claude mcp add hwp-rag -- \
  uvx --from hwp-rag-mcp hwp-rag-mcp serve \
  --dataset-dir ~/Desktop/dataset

프로젝트 단위 설정이 필요하면 Claude Code의 --scope project 옵션을 함께 사용합니다.

5. MCP 도구

도구	용도
get_index_status	인덱스가 missing, current, stale인지 확인
sync_index	파일 변경 후 전체 인덱스를 명시적으로 재구축
list_documents	마지막 유효 인덱스에 포함된 문서 목록 확인
search_documents	질문과 유사한 근거 청크 검색

예시 요청:

HWP 문서에서 연차휴가 신청 조건을 검색하고, 근거 파일명을 함께 표시해 줘.

search_documents는 최대 20개 결과를 반환하며, 정확한 파일명 목록으로 검색 범위를 제한할 수 있습니다. 파일이 변경되면 오래된 인덱스로 검색하지 않고 먼저 sync_index를 요구합니다.

인덱스와 개인정보

• FAISS 인덱스는 운영체제별 사용자 데이터 디렉터리에 저장됩니다.
• 데이터셋 절대경로의 SHA-256 일부를 저장 폴더 키로 사용합니다.
• index.faiss, documents.json, manifest.json만 저장하며 pickle 역직렬화는 사용하지 않습니다.
• manifest에는 파일 크기, 수정 시각, SHA-256과 모델·분할 설정이 기록됩니다.
• MCP 도구는 서버 시작 시 지정한 데이터셋 밖의 파일 경로를 입력받지 않습니다.
• API 키를 텍스트 파일로 저장하거나 읽는 기능은 없습니다.

문제 해결

index_missing

데이터셋 경로와 파일 확장자를 확인한 뒤 CLI의 sync를 실행합니다.

index_stale

파일이 추가·수정·삭제되었거나 분할 설정이 달라졌습니다. sync 또는 MCP의 sync_index를 실행합니다.

최초 동기화가 MCP에서 시간 초과됨

모델 다운로드가 포함된 최초 동기화는 터미널의 hwp-rag-mcp sync로 먼저 완료합니다. Codex 설정에서는 필요하면 tool_timeout_sec를 늘립니다.

암호화 또는 손상 문서

해당 파일은 동기화 보고서의 skipped_files 또는 failed_files에 표시되며, 다른 정상 문서는 계속 색인됩니다.

개발

python -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
ruff check .
pytest
python -m build
twine check dist/*

English summary

HWP RAG MCP builds a local, explicitly synchronized FAISS index from Korean HWP/HWPX files and exposes evidence retrieval over MCP. It uses a local multilingual E5 model, requires no embedding API key, and leaves answer generation to Codex or Claude Code.