Metadata-Version: 2.4
Name: hwp-rag-mcp
Version: 0.1.0
Summary: Local HWP/HWPX retrieval for Codex and Claude Code over MCP
Project-URL: Homepage, https://github.com/jaypakdevkr/HWP-RAG-MCP
Project-URL: Repository, https://github.com/jaypakdevkr/HWP-RAG-MCP
Project-URL: Issues, https://github.com/jaypakdevkr/HWP-RAG-MCP/issues
Author: HWP RAG MCP Contributors
License-Expression: MIT
License-File: LICENSE
Keywords: faiss,hwp,hwpx,korean,langchain,mcp,rag
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: <3.14,>=3.10
Requires-Dist: faiss-cpu<2,>=1.12
Requires-Dist: langchain-community<1,>=0.4
Requires-Dist: langchain-huggingface<2,>=1
Requires-Dist: langchain-hwp-hwpx-loader<0.2,>=0.1.1
Requires-Dist: langchain-text-splitters<2,>=1
Requires-Dist: mcp<2,>=1.20
Requires-Dist: platformdirs<5,>=4
Requires-Dist: sentence-transformers<6,>=5
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.7; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Description-Content-Type: text/markdown

# 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](https://docs.astral.sh/uv/) 사용을 권장합니다.

```bash
mkdir -p ~/Desktop/dataset
```

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

## 2. 최초 인덱스 생성

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

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

상태 확인과 강제 재구축:

```bash
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 서버를 등록합니다.

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

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

```toml
[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 연결

```bash
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` | 질문과 유사한 근거 청크 검색 |

예시 요청:

```text
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`에 표시되며, 다른 정상
문서는 계속 색인됩니다.

## 개발

```bash
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.

