ehxhf-789-hangul-quote-verifier 0.5.0

한국어 직접인용을 원문(PDF·HWPX·txt, 스캔본은 OCR)과 글자 단위로 대조·검증하는 MCP 서버 — 초안 인용(APA) 추출(영문 스킵)·폴더 코퍼스·다중 인용 일괄 감사

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)" 같은 변조 + 인용표시 누락을 리포트

설치 / 실행

# 로컬 개발
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:

{
  "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 (원하면 변경).