Metadata-Version: 2.4
Name: ehxhf-789-hangul-quote-verifier
Version: 0.5.0
Summary: 한국어 직접인용을 원문(PDF·HWPX·txt, 스캔본은 OCR)과 글자 단위로 대조·검증하는 MCP 서버 — 초안 인용(APA) 추출(영문 스킵)·폴더 코퍼스·다중 인용 일괄 감사
Author-email: ehxhf789789 <ehxhf789789@gmail.com>
Keywords: citation,hwpx,korean,mcp,nfc,ocr,pdf,quotation,research
Requires-Python: >=3.10
Requires-Dist: mcp[cli]>=1.27.0
Requires-Dist: pymupdf>=1.24.0
Provides-Extra: ocr
Requires-Dist: easyocr>=1.7.0; extra == 'ocr'
Description-Content-Type: text/markdown

# ehxhf-789-hangul-quote-verifier

**한국어 인용 무결성 검증기** — 직접인용(直接引用)이 원문과 글자 단위로 일치하는지 검증하는 MCP 서버.

한국어는 유니코드 정규형(NFC/NFD) 차이·한자병기(漢字倂記)·띄어쓰기·문장부호 변형 때문에 *"눈에는 같은데 실제로는 다른"* 인용 오류가 흔합니다. 직접인용은 한 글자만 틀려도 연구윤리상 문제가 되지만, 범용 diff·표절검사기는 이런 한국어 특유의 변형을 모른 채 비교해 **거짓 불일치**(무해한 표기차를 오류로)와 **거짓 일치**(NFD라 눈에 안 보이는 차이를 통과)를 냅니다.

이 도구는 비교할 때만 정규화하고 **보고할 때는 원문/인용의 실제 표기를 보존**하며, 차이를 유형별로 분류해 **무해한 표기차와 의미를 바꾼 진짜 오류를 구분**합니다.

> ⚠️ "최초/유일"을 주장하지 않습니다. 인용 검증·diff·정규화 도구는 많습니다. 이 패키지의 좁은 차별화는 *"한국어 인용 무결성"이라는 워크플로를 한 묶음으로 패키징하고 불일치를 유형별로 분류한다*는 점입니다.

## 무엇을 검증하나

| 차이 유형 | 위험도 | 예시 |
|---|---|---|
| 자모정규화(NFC/NFD) | 무해 (눈에 안 보임 → 반드시 짚어줌) | 분해형 `ㄱㅏ` ↔ 완성형 `가` |
| 띄어쓰기 | 무해 | `설계기준강도는24MPa` ↔ `설계기준강도는 24 MPa` |
| 문장부호 | 무해 | `「콘크리트구조 설계기준」` ↔ `"콘크리트구조 설계기준"` |
| 한자병기 | 무해 | `철근(鐵筋) 콘크리트` ↔ `철근 콘크리트` |
| **실제 어휘변경** | **위험** ⚠️ | `24 MPa` ↔ `27 MPa` |

> 건설 분야 활용 예: KCS/KDS 표준시방서·설계기준, 국토교통부 고시, KCI 논문의 조문·수치를 원고에 직접인용할 때, 막판에 한 글자씩 원문 대조하는 작업을 자동화합니다.

## 원문 입력 형식 (국문 논문/시방서는 txt로 저장하지 않는다)

| 형식 | 처리 | 비고 |
|---|---|---|
| `.hwpx` | 한글 OWPML(ZIP+XML)을 **표준 라이브러리로 충실 추출** | 한자병기·낫표·수치까지 정확. 권장 |
| `.pdf` | PyMuPDF로 텍스트 레이어 추출 | 다단·표는 순서 뒤섞일 수 있음. **스캔본(이미지)은 OCR 필요→추출 불가** |
| `.txt/.md` 등 | 평문(UTF-8→cp949 폴백) | |
| `.hwp`(구형 바이너리) | **미지원** | 한글에서 `.hwpx`/PDF로 저장 후 사용 |

> **왜 채팅 첨부가 아니라 MCP가 파일을 읽는가:** 인용 검증의 기준 원문은 *한 글자도 틀리면 안 되는 정답지*다. LLM이 PDF를 보고 원문을 다시 타이핑하면 무의식적 "교정"으로 정답지가 오염된다. 그래서 MCP가 로컬 파일을 **기계적으로 추출**한다. (PDF의 띄어쓰기 추출 잡음은 이 도구가 '무해'로 처리하므로 대조에 큰 지장 없음.)

## 제공 도구 (MCP tools)

**원문 적재**
- `load_source_text(path?, text?, label?)` — 기준 원문 1개 적재(PDF/HWPX/txt 자동 추출 또는 붙여넣기).
- `load_source_folder(folder, recursive?, patterns?, max_files?)` — **폴더의 여러 원문을 코퍼스로 적재.** 이후 인용이 *어느 문서*에서 왔는지 자동 식별.
- `extract_document_text(path, max_chars=2000)` — 적재 전에 **추출 품질을 눈으로 점검**(PDF 다단/스캔본 확인용).

**검증**
- `verify_quote(quote, source_text?, allow_ellipsis=True)` — **핵심.** 인용 ↔ 원문 1:1 검증. `'…'`·`(중략)` 생략 인용은 조각별 + 원문 등장 순서까지.
- `verify_quotes_batch(quotes, source_text?, allow_ellipsis=True)` — **다중 인용 일괄.** 코퍼스가 적재돼 있으면 인용마다 출처 문서까지 식별.
- `locate_mismatch(quote, source_text?)` — 다른 부분만 위치·유형으로(`is_critical`로 위험 표시).

**초안(원고)에서 인용 추출 — 영문 스킵, 한국어만**
- `extract_quotes_from_draft(path?/text?, only_korean=True)` — 초안에서 직접인용 + APA 인용표시를 추출. **한글 없는 영문 인용은 모두 스킵**, 한국어 인용만.
- `audit_draft_quotes(draft_path, source_folder?, only_korean=True)` — **[통합] 초안 → 한국어 인용 추출 → 원문 폴더 대조 → 변조·출처·인용표시 누락까지 한 번에 감사.**

**유틸**
- `normalize_korean(text, mode='nfc', fold_whitespace?, fold_punctuation?)` — 정규화 유틸리티.

### 대표 워크플로 (원고 감사)
```
audit_draft_quotes("D:/내논문_초안.hwpx", source_folder="D:/인용한_논문들/")
→ 영문 인용 자동 스킵, 한국어 인용만 각 원문과 대조,
  "27 MPa(원문 24)" 같은 변조 + 인용표시 누락을 리포트
```

## 설치 / 실행

```bash
# 로컬 개발
uv sync
uv run mcp dev src/ehxhf_789_hangul_quote_verifier/server.py   # 인스펙터로 테스트

# 배포본 실행 (PyPI 업로드 후)
uvx ehxhf-789-hangul-quote-verifier
```

## Claude Desktop 연결

`%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "hangul-quote-verifier": {
      "command": "uvx",
      "args": ["ehxhf-789-hangul-quote-verifier"]
    }
  }
}
```

## 의존성

- 런타임: `mcp[cli]` + `pymupdf`(PDF 추출용). 검증 로직과 HWPX 추출은 **표준 라이브러리**(`unicodedata`·`re`·`difflib`·`zipfile`·`xml`)만 사용. 전부 **로컬 처리 → 네트워크·API·인증 불필요, 완전 오프라인.** 비공개 원고·미공개 논문에도 안전.

## 설계 메모

- 순수 로직(`core.py`)은 `mcp` 비의존이라 표준 파이썬만으로 단독 테스트 가능. `server.py`는 `@mcp.tool()` 래퍼.
- **한자병기 한계(정직)**: `철근(鐵筋)`처럼 괄호 병기 패턴만 등가 처리. `引用`↔`인용` 같은 한자→한글 독음 변환은 사전이 필요해 미지원.

## 라이선스

MIT (원하면 변경).
