hwp-rag-mcp 0.1.0__tar.gz

hwp_rag_mcp-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+htmlcov/
+

hwp_rag_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - Unreleased
+
+### Added
+
+- Local HWP/HWPX parsing, element-aware chunking, multilingual E5 embeddings, and FAISS search.
+- Safe FAISS and JSON persistence without pickle deserialization.
+- Explicit index status/sync CLI and MCP tools for Codex and Claude Code.
+- Korean-first setup and operations guide.
+

hwp_rag_mcp-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 HWP RAG MCP Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

hwp_rag_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+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.
+

hwp_rag_mcp-0.1.0/README.md

@@ -0,0 +1,152 @@
+# 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.
+

hwp_rag_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,87 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hwp-rag-mcp"
+version = "0.1.0"
+description = "Local HWP/HWPX retrieval for Codex and Claude Code over MCP"
+readme = "README.md"
+requires-python = ">=3.10,<3.14"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "HWP RAG MCP Contributors" },
+]
+keywords = ["hwp", "hwpx", "rag", "mcp", "faiss", "langchain", "korean"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Text Processing :: Indexing",
+]
+dependencies = [
+  "faiss-cpu>=1.12,<2",
+  "langchain-community>=0.4,<1",
+  "langchain-huggingface>=1,<2",
+  "langchain-hwp-hwpx-loader>=0.1.1,<0.2",
+  "langchain-text-splitters>=1,<2",
+  "mcp>=1.20,<2",
+  "platformdirs>=4,<5",
+  "sentence-transformers>=5,<6",
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2",
+  "mypy>=1.11",
+  "pytest>=8",
+  "pytest-asyncio>=0.24",
+  "ruff>=0.7",
+  "twine>=5",
+]
+
+[project.scripts]
+hwp-rag-mcp = "hwp_rag_mcp.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/jaypakdevkr/HWP-RAG-MCP"
+Repository = "https://github.com/jaypakdevkr/HWP-RAG-MCP"
+Issues = "https://github.com/jaypakdevkr/HWP-RAG-MCP/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hwp_rag_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src",
+  "/tests",
+  "/README.md",
+  "/LICENSE",
+  "/CHANGELOG.md",
+  "/pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+packages = ["hwp_rag_mcp"]
+warn_unused_ignores = false

hwp_rag_mcp-0.1.0/src/hwp_rag_mcp/__init__.py

@@ -0,0 +1,35 @@
+"""Local HWP/HWPX retrieval over the Model Context Protocol."""
+
+import os
+from importlib.metadata import PackageNotFoundError, version
+
+# Set this before importing FAISS/LangChain modules, which may transitively import
+# Hugging Face tokenizers. Parallel tokenizers are unnecessary for this local STDIO
+# process and have caused shutdown crashes on some macOS ARM Python builds.
+os.environ.setdefault("TOKENIZERS_PARALLELISM", "false")
+
+try:
+    __version__ = version("hwp-rag-mcp")
+except PackageNotFoundError:  # pragma: no cover - source tree without installation
+    __version__ = "0.1.0"
+
+from .index import IndexManager
+from .models import (
+    DocumentSummary,
+    IndexStatus,
+    SearchResponse,
+    SearchResult,
+    SyncFailure,
+    SyncReport,
+)
+
+__all__ = [
+    "DocumentSummary",
+    "IndexManager",
+    "IndexStatus",
+    "SearchResponse",
+    "SearchResult",
+    "SyncFailure",
+    "SyncReport",
+    "__version__",
+]

hwp_rag_mcp-0.1.0/src/hwp_rag_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""Module entry point for ``python -m hwp_rag_mcp``."""
+
+from .cli import main
+
+raise SystemExit(main())
+

hwp_rag_mcp-0.1.0/src/hwp_rag_mcp/cli.py

@@ -0,0 +1,67 @@
+"""Command-line interface for status, synchronization, and MCP serving."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from . import __version__
+from .index import IndexManager
+
+
+def _add_dataset_argument(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--dataset-dir",
+        type=Path,
+        default=None,
+        help="HWP/HWPX folder (CLI > HWP_RAG_DATASET_DIR > ~/Desktop/dataset)",
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="hwp-rag-mcp",
+        description="Build and serve a local HWP/HWPX FAISS retrieval index.",
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    status_parser = subparsers.add_parser("status", help="Check index freshness")
+    _add_dataset_argument(status_parser)
+
+    sync_parser = subparsers.add_parser("sync", help="Explicitly rebuild the index")
+    _add_dataset_argument(sync_parser)
+    sync_parser.add_argument("--force", action="store_true", help="Rebuild a current index")
+
+    serve_parser = subparsers.add_parser("serve", help="Run the MCP STDIO server")
+    _add_dataset_argument(serve_parser)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "serve":
+        from .server import run_server
+
+        run_server(args.dataset_dir)
+        return 0
+
+    try:
+        manager = IndexManager(args.dataset_dir)
+        if args.command == "status":
+            print(manager.status().model_dump_json(indent=2))
+            return 0
+        if args.command == "sync":
+            report = manager.sync(force=args.force)
+            print(report.model_dump_json(indent=2))
+            return 0 if report.state == "current" else 1
+    except Exception as exc:
+        print(f"{exc.__class__.__name__}: {exc}", file=sys.stderr)
+        return 1
+    parser.error(f"Unsupported command: {args.command}")
+    return 2
+

hwp_rag_mcp-0.1.0/src/hwp_rag_mcp/config.py

@@ -0,0 +1,73 @@
+"""Configuration and path resolution for the local RAG service."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from platformdirs import user_data_path
+
+DEFAULT_MODEL_NAME = "intfloat/multilingual-e5-small"
+DEFAULT_CHUNK_SIZE = 1_000
+DEFAULT_CHUNK_OVERLAP = 150
+DATASET_ENV_VAR = "HWP_RAG_DATASET_DIR"
+STORAGE_ENV_VAR = "HWP_RAG_STORAGE_DIR"
+
+
+def normalize_path(value: str | Path) -> Path:
+    """Expand and resolve a user-provided path without requiring it to exist."""
+
+    return Path(value).expanduser().resolve(strict=False)
+
+
+def resolve_dataset_dir(value: str | Path | None = None) -> Path:
+    """Resolve dataset path using CLI value, environment, then Desktop default."""
+
+    if value is not None:
+        return normalize_path(value)
+    environment_value = os.getenv(DATASET_ENV_VAR)
+    if environment_value:
+        return normalize_path(environment_value)
+    return normalize_path(Path.home() / "Desktop" / "dataset")
+
+
+def resolve_storage_root(value: str | Path | None = None) -> Path:
+    """Resolve the private application data directory used for indexes."""
+
+    if value is not None:
+        return normalize_path(value)
+    environment_value = os.getenv(STORAGE_ENV_VAR)
+    if environment_value:
+        return normalize_path(environment_value)
+    return normalize_path(user_data_path("hwp-rag-mcp", appauthor=False))
+
+
+def dataset_storage_key(dataset_dir: Path) -> str:
+    """Create a stable, non-sensitive storage key for an absolute dataset path."""
+
+    digest = hashlib.sha256(str(dataset_dir).encode("utf-8")).hexdigest()[:16]
+    return f"dataset-{digest}"
+
+
+@dataclass(frozen=True)
+class IndexConfig:
+    """Immutable settings that affect the generated vector index."""
+
+    dataset_dir: Path
+    storage_root: Path
+    model_name: str = DEFAULT_MODEL_NAME
+    chunk_size: int = DEFAULT_CHUNK_SIZE
+    chunk_overlap: int = DEFAULT_CHUNK_OVERLAP
+
+    def __post_init__(self) -> None:
+        if self.chunk_size <= 0:
+            raise ValueError("chunk_size must be greater than zero")
+        if self.chunk_overlap < 0 or self.chunk_overlap >= self.chunk_size:
+            raise ValueError("chunk_overlap must be non-negative and smaller than chunk_size")
+
+    @property
+    def index_dir(self) -> Path:
+        return self.storage_root / dataset_storage_key(self.dataset_dir)
+

hwp_rag_mcp-0.1.0/src/hwp_rag_mcp/embeddings.py

@@ -0,0 +1,26 @@
+"""Local multilingual embedding construction."""
+
+from __future__ import annotations
+
+import os
+
+from langchain_core.embeddings import Embeddings
+
+from .config import DEFAULT_MODEL_NAME
+
+
+def create_local_embeddings(model_name: str = DEFAULT_MODEL_NAME) -> Embeddings:
+    """Create the supported local E5 embedder with retrieval prompts enabled."""
+
+    # Hugging Face tokenizers can initialize worker resources that are unnecessary for
+    # this single-process STDIO server and unstable in some macOS ARM Python builds.
+    os.environ.setdefault("TOKENIZERS_PARALLELISM", "false")
+
+    from langchain_huggingface import HuggingFaceEmbeddings
+
+    return HuggingFaceEmbeddings(
+        model_name=model_name,
+        model_kwargs={"device": "cpu"},
+        encode_kwargs={"normalize_embeddings": True, "prompt": "passage: "},
+        query_encode_kwargs={"normalize_embeddings": True, "prompt": "query: "},
+    )