저는 서울 광진구청에서 근무하는 공무원입니다. 직장에서 7년 동안 HWP 파일과 씨름했는데, 최근 LLM을 업무에 접목시키기 시작하면서 이 파일들이 첫 번째 벽이 되었습니다. 제가 업무상 읽고 쓰는 거의 모든 문서가 HWP 또는 HWPX 형식이기 때문입니다. RAG 파이프라인이나 AI 에이전트는 Markdown을 원합니다. 그래서 저는 한국 문서를 Markdown 및 구조화된 데이터로 변환하는 MIT 라이선스의 TypeScript 라이브러리인 kordoc, CLI, 그리고 MCP 서버를 구축했습니다.
HWP의 실제 구조는 무엇인가요
HWP는 한글(Hancom) 워드 프로세서 형식이며, 그 종류가 하나 이상입니다:
- HWP 5.x는 OLE2 컴파운드 파일(CFB)입니다. 본문은 UTF-16LE의 텍스트를 포함하는 zlib 압축된 일련의 레코드로 구성됩니다. 손상된 파일의 경우, kordoc은 rhwp에서 포팅한 관대한 CFB 복구 파서를 포함합니다.
- HWPX는 XML을 담은 ZIP 아카이브입니다: 본문용 섹션 XML과 스타일 및 번호 매기기용
head.xml로 구성됩니다. ZIP 중앙 디렉토리가 손상된 경우, kordoc은 로컬 파일 헤더를 직접 스캔합니다.
- HWP 3.x (1996년~2002년)는 원시 deflate 및 Johab 인코딩 한글이 포함된 단일 바이너리 스트림입니다.
- HWPML 2.x는 XML 기반의 변형 형식입니다.
이 모든 것은 Hancom Office 설치가 필요하지 않습니다. kordoc은 파일을 직접 읽습니다.
kordoc이 하는 일
HWP 3.x/5.x, HWPX, HWPML, PDF, XLS/XLSX, DOCX, PPTX, PNG/JPG/WebP를 Markdown 및 구조화된 데이터로 변환합니다. 읽는 것 외에도 블록 및 셀 차이점(diffs), 형식 보존 HWPX/HWP 패치, 정부 문서 프리셋을 사용한 Markdown to HWPX 생성, 양식 채우기, 미리 보기, PII 마스킹 기능을 제공합니다. MCP를 통해 에이전트에게 17개의 도구를 노출합니다.
빠른 시작
macOS, Linux 또는 Windows의 Node.js 20+에서 사용 가능합니다.
npm install kordoc
npx kordoc document.hwpx -o document.md
...
라이브러리로 사용하는 방법:
import { parse } from
Claude Code에서는 플러그인으로도 설치할 수 있습니다:
/plugin marketplace add chrisryugj/kordoc
/plugin install kordoc@kordoc
현재 PyPI에 Python SDK가 있습니다. 이 SDK는 엔진을 번들로 포함하지 않습니다. 대신 상주하는(resident) kordoc 엔진 워커를 시작하고 이를 재사용하므로, 기기에 Node.js 20+와 npm 패키지, 그리고 Python 3.11+:이 필요합니다:
npm i -g kordoc # engine
pip install kordoc # SDK
from kordoc import KordocClient
with KordocClient() as client:
...
## 어려운 부분들 (The hard parts)
### 병합 셀 테이블 (Merged-cell tables)
제가 처리하는 문서들은 병합되고 중첩된 셀을 가진 테이블로 가득합니다. kordoc은 테이블을 두 번의 과정을 거쳐 배치합니다. 먼저 `colSpan`/`rowSpan`으로부터 그리드 크기를 계산한 다음, 셀들을 배치합니다. RAG 인덱싱을 위해 `--table-format gfm` (API: `tableFormat:
### 에어 갭 네트워크 (Air-gapped networks)
kordoc는 에어 갭 네트워크에서도 작동하도록 설계되었습니다. `KORDOC_OFFLINE=1`을 설정하면 모든 아웃바운드 트래픽이 차단되며, OCR은 API 키 없이 로컬 CPU에서 실행됩니다. MCP의 경우, `KORDOC_ROOT`가 서버가 접근할 수 있는 파일을 제한합니다. 53개의 문서와 102페이지에 대해 OCR 측정 결과 CER은 0.0412, 문자 재현율(character recall)은 99.02%입니다.
## 한계점 (Limitations)
표 구조(Table structure), 셀 내용(cell content), 시각적 충실도(visual fidelity)는 별개의 측정 항목입니다. 구조 점수가 100%라고 해서 모든 셀의 텍스트나 모든 페이지의 모양이 완벽하다는 의미는 아닙니다. PDF 표의 경우, 100%가 아닌 97.98%의 구조 일치율을 보였습니다. 기본 OCR은 OCR 모델이 이미 캐시된 경우에만 실행되며, 그렇지 않으면 아무것도 다운로드되지 않고 `NEEDS_OCR` 또는 `SKIPPED_IMAGE` 경고를 받게 됩니다. 형식 유지 패치는 적용할 수 없는 편집 내용은 건너뛰고 그 이유를 보고합니다. HWPX 셀 편집 경로는 동일한 수의 비어있지 않은 줄을 필요로 하므로, 빈 줄(blank lines), 추가되거나 삭제된 줄, 리터럴 `<br>`, 모호한 매핑은 여전히 지원되지 않습니다.
## 보조 프로젝트: korean-law-mcp
제가 직장에서 의존하는 두 번째 도구는 [korean-law-mcp](https://github.com/chrisryugj/korean-law-mcp)입니다. 이는 한국의 공식 법률 데이터베이스(법제처 Open API)를 위한 MCP 서버 및 CLI입니다. 이 도구는 법령, 판례, 행정 규칙, 지방 조례, 조약 및 법적 해석을 다루는 42개의 API를 10개의 도구로 묶었습니다. LLM 작업과 가장 관련성이 높은 부분은 인용 검증(citation verification)입니다: `legal_analysis(mode="verify_citations")`는 텍스트에 인용된 법령 조항 및 사건 번호를 공식 출처와 비교하여 존재 여부와 내용을 확인합니다. 이 도구는 kordoc를 사용하여 법령 부속서를 구문 분석하며, 공식 MCP 레지스트리에 등재되어 있습니다. 필요한 API 키는 무료입니다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
npx --ignore-scripts --omit=optional korean-law-mcp setup
## 피드백 환영 (Feedback welcome)
만약 한국 문서를 다루신다면, 가장 유용한 것은 문제가 발생하는 실제 파일을 이슈(issue)로 보내주시는 것입니다. 별점은 다른 사람들이 이 도구를 찾는데도 도움이 됩니다: [github.com/chrisryugj/kordoc](https://github.com/chrisryugj/kordoc)