需要 Node.js 20 或更高版本;用 --omit=optional 安装会限制 PDF、OCR、图片格式转换和 QR 读取功能;MCP 注册后需要重启客户端才能使用 22 个工具。
kordoc
chrisryugjMIT活跃维护把韩文 HWP/HWPX、PDF、Office 和扫描件统一转成 Markdown,还能做新旧对照、保留格式编辑、回写 HWPX 和公文校验,提供库、CLI 和 MCP 接口。
한국 문서를 읽고·고치고·새로 쓰는 AI 문서 도구 — HWP·HWPX·PDF·오피스·스캔(OCR)을 Markdown으로, 신구대조·서식 보존 편집·Markdown→HWPX 작성·HWP→HWPX 변환·양식 채우기·공문서 검수까지. 라이브러리·CLI·MCP | Read, diff, edit, write and convert Korean documents (HWP, HWPX, PDF, Office, scans) — library, CLI and MCP server
npm install kordoc
npx kordoc 문서.hwpx -o 문서.mdREADME 未说明 GPU 或显存要求;OCR 可在本地 CPU 上运行,无需 API 密钥,并支持在断网环境中使用。
把韩文 HWP、HWPX、PDF、Office 和扫描件转成 Markdown 并支持编辑生成的文档工具
把韩文 HWP/HWPX、PDF、Office 和扫描件统一转成 Markdown,还能做新旧对照、保留格式编辑、回写 HWPX 和公文校验,提供库、CLI 和 MCP 接口。
核心能力
- 把 HWP、HWPX、PDF、Office 和扫描件转成 Markdown 与结构化数据
- 按块和单元格比对文档,并在保留 HWPX、HWP 格式的前提下打补丁
- 把 Markdown 生成 HWPX,支持公文预设、表格、公式和图表
- 把 HWP 5.x 转成 HWPX,保留字体、段落、表格和图片等格式
- 提供 CLI、库和 MCP 服务器三种用法,可接入 AI 客户端
容易踩的坑
- v4.24.58最新正式版2026-11-09 · 2026-11-09 13:32 UTC
자체 OCR 표 구조 일치 31 → 32/65 · KoOCR-Bench 0.90370 → 0.90378 · 선택형 gVisor 샌드박스(#199) · 자체 벤치 문서별 하락 0
Added
- gVisor 샌드박스
KORDOC_SANDBOX=gvisor(Linux): 파싱 CLI(kordoc <파일>)와 parse-worker(Java·Python SDK 워커)가runsc do안에서 다시 실행된다. 네트워크를 끊고(--network=none,KORDOC_OFFLINE=1도 켬) 호스트 파일은 읽기만 보인다. sharp·onnxruntime·PDF 엔진 같은 네이티브 코드가 악성 문서로 장악되어도 호스트 커널·파일·네트워크에 직접 닿지 못한다. Linux 에서 runsc 가 없거나 띄우지 못하면 오류로 멈추고 격리 없이 계속하지 않는다. macOS·Windows 에서는 경고만 내고 그대로 실행한다. 샌드박스 안에서 쓴 파일은 사라지므로-o·-d·파일을 쓰는 하위 명령·MCP 서버·protocol 2transport.images: "files"는 오류로 거절한다(이런 경로는docker --runtime=runsc로 격리). 끄면(기본) 동작·출력은 그대로. 재사용 워커의 문서당 처리 시간은 일반 컨테이너의 1.08배(문서 5개 합계 2,613ms → 2,817ms, GitHub Actions 실측). 배포 가이드 docs/sandbox.md - CI
gvisor잡:npm test를 gVisor 컨테이너 안에서 네트워크 없이 돌리고,KORDOC_SANDBOX=gvisor경로의 격리(gVisor 커널 로그·네트워크 차단·호스트 파일 보호·실패 시 멈춤)를 단언한다. 첫 단계에서 컨테이너가 정말 gVisor 안인지dmesg의Starting gVisor...로 확인하고, 아니면 잡을 실패시킨다
Fixed
- OCR 표 이웃 칸 시각 값: 따로 검출된 OCR 값 상자끼리는 칸 경계를 조금 넘어도 한 낱말로 잇지 않는데, 값 판정이 숫자·쉼표·점만 봐서 "0:34"·"0:32" 가 한 칸에 "0:340:32" 로 붙고 이웃 칸이 비었다(생활시간 표). 시각의 ":" 도 값으로 본다 — KoOCR-Bench 0.90370 → 0.90378(생활시간 표 두 쪽 .802 → .827·.806 → .824, 내려간 쪽 0), 자체 OCR·OCR robust·ODL-OCR 문서별 하락 0
- OCR 표 맨 끝 "" 각주 칸: 표 속 산문 행을 문단으로 꺼내는 판정이 맨 끝 "※" 행만 표에 두고 " 단, 체류자격 변경 …"(신분증 표 안 각주 병합 칸)은 문단으로 꺼내 표가 한 행 모자랐다. 맨 끝 전폭 행 묶음이 모두 "※" 나 ""·""·"" 로 시작하면 표에 둔다 — 자체 OCR 표 구조 일치 31/65 → 32/65(topik 1 → 2), KoOCR-Bench 0.90370 그대로(교재 스캔 한 쪽 아프가 표 아래 "*" 각주가 표에 남아 CER .135 → .139), 자체 OCR·OCR robust·ODL-OCR 문서별 하락 0
- gVisor 샌드박스
- v4.24.572026-11-09 · 2026-11-09 08:07 UTC
查看更新说明
수식 OCR 재현율 0.9723 → 0.9758, BLEU-4 0.8997 → 0.9045(보고 전용) · 자체 OCR 표 구조 일치 28 → 31/65 · KoOCR-Bench 0.90370 그대로 · 자체 벤치 문서별 하락 0
Security
- 의존성 최소 버전을 보안 권고가 고쳐진 버전으로 올림. 종전 선언 범위는 취약한 버전을 허용해, 잠금 파일 없이 설치하거나 오래된 잠금 파일을 쓰는 설치가 권고에 노출될 수 있었다. 잠금 파일은 이미 고쳐진 버전을 고르고 있어 설치 버전·출력은 그대로(npm test 4,981건, Python SDK 86건(pytest 9.0.3), Java SDK 72건 통과,
npm audit0건)@xmldom/xmldom^0.9.10 → ^0.9.12: 2026-09 공개 권고(이차 시간·이차 메모리 파싱, 정규식 ReDoS,requireWellFormed우회 — GHSA-93r5-fhx6-vmg9·GHSA-965w-775f-mr7g·GHSA-8344-3jmq-59r6·GHSA-g53g-w8rj-fmg7·GHSA-vr34-hp96-76pp 외)@modelcontextprotocol/sdk^1.29.0 → ^1.32.0: HTTP 전송 요청 크기·처리 제한(GHSA-f897-62hf-6gxq, GHSA-46jr-4wx8-v453/CVE-2026-111768), 세션에 묶이지 않는 작업(GHSA-22jm-h49p-29qw/CVE-2026-111767), 베어러 토큰 검증(GHSA-rvq5-wwqv-78pq/CVE-2026-111771), OAuth 자격 증명 전송(GHSA-6qxp-vccf-f47h/CVE-2026-104850, GHSA-6prh-2h8m-c8cw/CVE-2026-111769).kordoc mcp는 stdio 전송이라 HTTP 계열은 직접 쓰지 않지만 SDK 를 함께 설치하는 앱이 영향받는다sharp^0.35.0 → ^0.35.5 (선택 의존·개발 의존·overrides): 동봉 libheif(GHSA-rgj7-g3m4-5g8c)·librsvg(GHSA-wq5f-xc86-pv6w, CVE-2026-96889) 취약점- overrides
adm-zip^0.6.0 → ^0.6.1 (onnxruntime-node가 끌어옴): 압축 폭탄 방어 우회·선언 크기 메모리 할당(GHSA-rcw4-f5rp-g42v, GHSA-7q85-xj36-vmfc/CVE-2026-77301), SUID 비트 보존(GHSA-j5f4-cc29-5x44/CVE-2026-102282), 비동기 풀기 오류로 프로세스 종료(GHSA-8238-w5pm-2374) 외 3건 - Python SDK 시험 의존
pytest>=8 → >=9.0.3: 임시 디렉터리 처리로 로컬 DoS·권한 상승(GHSA-6w46-j5rx-g56g/CVE-2025-71176). 시험 전용이라 배포물은 그대로(Python 3.11 에서 86건 통과)
Fixed
-
OCR 예산서 표 산출 내역 칸: 쌓인 행 가르기가 한 칸에 적힌 항목과 산출 내역("○전기요금 / -취수정 경정 80,000,000원", "○센터 공공요금 / 전기요금 5,600,000원 / …")·재원 내역("526,657 / 균 395,010")을 행으로 펼쳐, 원본 한 칸인 자체 OCR 예산서 표가 어긋났다(11-02 행 합침 아래 쌓인 행 가르기 뒤 부천 표 일치 2/2 → 0/2, 괴산 2/2 → 0/2 — 그때 스위트 문서별 비교는 CER 만 봐 놓쳤다). 이름표 둘째 줄부터 금액(…원)을 적은 줄이 있거나 재원 표지 금액 줄("국·도·균·시·군·구 + 금액")이 있으면 한 칸으로 둔다. 금액 없는 갈래 이름("○사업비 / -사회보험성 / -사업성", 관보 기금 운용)은 종전대로 펼친다 — 자체 OCR 표 일치 28/65 → 31/65(부천 0 → 2, 괴산 2013 0 → 1, 칸 F1 .918 → 1·.809 → .856), KoOCR-Bench 0.90370 그대로, 자체 OCR·OCR robust·ODL-OCR 문서별 하락 0
-
공문서 프리셋 정규화(
normalizeGongmunPreset)가 별칭 표를 프로토타입까지 뒤져, 프리셋에 "toString"·"constructor" 같은 이름을 주면 문자열 대신 함수를 돌려markdownToHwpx(gongmun.preset)와lintBlocks(preset)가preset.trim is not a function으로 죽었다. CLI·MCP·protocol 2 는 이미 자기 키만 받았고, 라이브러리로 부르는 쪽만 걸렸다. 표의 자기 키만 보고 모르면 종전대로official, 문자열이 아닌 값도official -
PDF 수식 OCR 긴 여러 줄 식: 인식기는 영역을 384×384 로 늘려 넣어 열 줄 넘는 증명식이 뭉개져 쓰레기("\displaystyle\frac{8}{4}[\left[a=…")가 나왔다 — 정답 식 500자 넘는 것 106개 중 26개를 놓쳤다(그 밖은 1~2%). 다섯 줄 이상인 display 영역은 줄 사이 빈 띠에서 갈라 줄마다 읽고
aligned로 잇는다. 줄 띠는 여러 줄에 걸친 큰 괄호(세로 획 22.5pt 이상)를 빼고 행을 세며, 합 기호 위아래 첨자처럼 작은 띠(가장 큰 띠의 절반 미만)나 줄 사이 틈보다 좁게(가장 큰 틈의 60% 미만) 붙은 띠는 이웃 줄에 붙인다. 넉 줄 이하는 통째로 읽는다(넉 줄 식까지 가르면 오른쪽 조건 열 "for 0≤s≤r²"·굵은 기호·정렬 기호가 빠져 10개가 나빠졌다) — 수식 벤치(20편 621쪽, 혼자 실행) 재현율 0.9723 → 0.9758, NED≤.3 재현율 0.9425 → 0.9494, 정밀도 0.9682 → 0.9699, BLEU-4 0.8997 → 0.9045(2609.15723 .864 → .903), 종전 짝 중 빠지거나 NED 가 나빠진 것 0
- 의존성 최소 버전을 보안 권고가 고쳐진 버전으로 올림. 종전 선언 범위는 취약한 버전을 허용해, 잠금 파일 없이 설치하거나 오래된 잠금 파일을 쓰는 설치가 권고에 노출될 수 있었다. 잠금 파일은 이미 고쳐진 버전을 고르고 있어 설치 버전·출력은 그대로(npm test 4,981건, Python SDK 86건(pytest 9.0.3), Java SDK 72건 통과,
- v4.24.562026-11-09 · 2026-11-09 00:26 UTC
查看更新说明
KoOCR-Bench 종합 0.90023 → 0.90370(손글씨 .908 → .921, 표 .9105 → .9120) · 자체 OCR·OCR robust·ODL-OCR 문서별 하락 0
Fixed
- OCR 저신뢰 줄이 많은 쪽 다시 읽기: 하늘 수채화 바탕 손편지(640×920)는 960 검출에서 손글씨 글줄이 획 조각 상자로 갈려 124줄 중 66줄을 저신뢰로 버렸고(CER .51), 남은 조각은 군집 표가 됐다. 쪽에서 버린 줄이 15개 이상이고 전체 줄의 15% 이상이면 검출 긴 변을 5/3 배로 키워(손글씨 rec 판정까지) 다시 읽고, 버린 줄이 줄고 확신도가 오르면 그것을 쓴다 — 손편지 두 쪽 CER .508 → .150·.277 → .142, KoOCR-Bench 0.90096 → 0.90370(손글씨 .9075 → .9212, 다른 쪽 그대로). 검출 크기를 늘 키우면 손글씨 108쪽 중 34쪽이 나빠졌다(1600 일괄 .0757 → .0929). 그림 영역만 읽는 쪽은 차트 눈금·범례 조각을 늘 많이 버려 걸리므로 끈다(ODL 027 "single" → "sing le"). 자체 OCR·OCR robust·ODL-OCR 문서별 하락 0
- OCR 표 "○ 항목 | 금액" 쌓인 행: 관보 기금 자금조달·운용 표는 한 행 칸 안에 "○ 자체수입 / ○ 정부내부수입 …" 과 "3,819,793,000,000원 / …" 을 줄로 쌓아 두는데, 쌓인 칸 대다수가 숫자여야 가르던 조건(60%)에 항목 칸이 걸려 한 행으로 남았다. 쌓인 칸마다 숫자 칸(줄 80% 이상 숫자, "원"·"-원" 포함)이거나 항목 칸(12자 이하 글 줄, "○" 글머리 하나 이상)이고 숫자 칸이 하나 이상이면 가른다. 줄 수가 같은 칸 수로 맞서면 줄이 많은 쪽을 행 수로 잡아 짧은 쪽(조달 4줄·운용 5줄)은 끝 행을 비운다 — 관보 두 쪽 CER .266 → .008·.314 → .148, KoOCR-Bench 0.90023 → 0.90096(내려간 쪽 0), 자체 OCR·OCR robust·ODL-OCR 문서별 하락 0. 금액 칸 없이 글만 쌓인 "○" 목록은 그대로
- v4.24.552026-11-08 · 2026-11-08 17:31 UTC
查看更新说明
Fixed
- PDF 수식 OCR: 검출기가 여러 줄 정렬식 전체와 그 안의 한 줄을 따로 잡으면(IoU 가 작아 NMS 를 지난다) 같은 줄이 큰 식 안에 한 번, 짝 없는 조각으로 또 한 번 나왔다(2609.15723 "+\frac{4L_f^2…}" 줄). 면적 85% 이상이 다른 display 상자 안이고 그 상자가 1.5 배 이상 높으면 뺀다 — 수식 벤치(20편 621쪽, 혼자 실행) 정밀도 0.9554 → 0.9682(10편 오름, 2609.15723 .757 → .822), 재현율 0.9728 → 0.9723(2609.15723 에서 NED .589 로 겨우 붙던 조각 짝 하나가 빠짐, 같은 논문 한 짝 NED .017 → .072), 다른 짝 그대로
- OCR 표 소수 짝("12.1/18.1", 기온 최저/최고): 좁은 숫자 글꼴에서 소수점이 앞뒤 숫자에 붙어 빠졌다("121/18.1"·"124/188"). 쪽의 수 짝 다섯 이상에 60% 넘게 양쪽이 소수일 때만 점이 빠진 짝을 가로로 늘려 다시 읽어, 양쪽 소수 하나씩이고 원래 숫자를 차례로 품으며 숫자가 하나까지만 늘면 받는다 — 날씨 표 서울 행 7칸 바로잡힘(KoOCR-Bench 종합 0.89885 그대로 — 그 표는 행·열 구조가 어긋나 칸 짝이 안 맞는다), 자체 OCR·OCR robust·ODL-OCR 문서별 하락 0
- OCR 칸 테두리 지우기(edgeTrim): 촘촘한 통계표에서 인식 박스에 걸친 칸 괘선을 글자로 읽어 "0:36" 이 ":36", "60.5" 가 "(.5" 가 됐다. 겹선(‖)은 두 선을 한 테두리로, 점선 세로선(위아래 끝에 닿고 빈 토막이 촘촘한 열)도 테두리로 보고, 박스 위아래 끝의 가로 괘선 행은 글 열 판정에서 뺀다. 끝 20% 안에 높이를 꽉 채운 실선이 있으면 그 너머 이웃 칸 글자 끝자락까지 지운다 — 생활시간 표 5칸 바로잡힘, KoOCR-Bench 0.89885 → 0.89887, 자체 OCR·OCR robust·ODL-OCR 문서별 하락 0(3문서 오름)
- HWP 3.x 글 추출(rhwp 0.9.0 대조): 사용자 정의 개요 번호(모양 0)의 한글 음절 형식(5)을 "가. 나. …" 로 읽는다(종전 기본 개요 "I. II." — 한컴 HWP5 저장본과 대조). 찾아보기 표식(ch=26)이 본문에 대체 문자(U+FFFC)를 남기던 것("입력기(IME")과 하이픈(ch=24)이 "-" 를 내던 것("Word-processor", 한컴 저장본 "Wordprocessor")을 HWP5·HWPX 경로처럼 글 없이 둔다. 사적 코드 0x2015(―)를 읽어 치수 화살표 가로선 62자가 살아난다 — 자체 HWPX·PDF·HWP5 짝 채점 게이트 PASS
- OCR 손글씨 rec 기본 문턱: 쪽 확신도 .85 미만·+.10 상승에서만 손글씨 rec 로 바꿔 .85~.90 손글씨 쪽을 놓쳤다. 쪽 확신도 .9 미만에서 +.10 넘게 오르면 바꾸고, +.08~.10 이면 손글씨 rec 확신도 .95 이상·두 결과 글 8% 이상 차이·글자 80자 이상일 때만 바꾼다 — 인쇄 시험지(손글씨 rec 확신도 .91~.94), 잡음 낀 인쇄 스캔(두 rec 글 차이 .007~.07), 짧은 목차 영역(64자)은 그대로. KoOCR-Bench 0.89887 → 0.90023(손글씨 .9007 → .9075, 17쪽 오르고 4쪽 내림, 수능·표 그대로), 자체 OCR·OCR robust·ODL-OCR 문서별 하락 0.
ocrRec: "auto"(.9·+.06)는 수능 수학 9쪽이 망가져 0.90006
- v4.24.542026-11-08 · 2026-11-08 08:51 UTC
查看更新说明
Fixed
- PDF·OCR 쪽에 좌우로 나란히 놓인 두 표: 같은 쪽 인접 표 잇기가 읽기 순서로 연달아 오고 열 수가 같은 표를 자리와 상관없이 행으로 이어, 오른쪽 표가 왼쪽 표 아래 행으로 쌓였다(지역별 혼인 건수 "지역 | 전체 | 초혼 | 재혼" 두 표·소관부처 목록 두 표). 가로 범위가 안 겹치고 세로로 절반 넘게 겹치는 두 표는 잇지 않는다 — KoOCR-Bench 0.89420 → 0.89698(표 묶음 4쪽 .41~.68 → .87~1.0, 수능 국어 두 쪽 CER .30 → .11, 하락 0), 자체 OCR·ODL·ODL-OCR·PDF 글·PDF 표 문서별 하락 0
- PDF 수식 OCR 쓰레기 거름이 바로 인식된 식을 버렸다: 등호 없는
aligned를 쓰레기로 봐\leq·\lesssim로만 잇는 여러 줄 부등식 유도가 통째로 빠졌고, 같은 첨자를 단 정상 식(S=\sum_{\ell,m}S_{\ell,m}Y_{\ell,m})이 첨자 되풀이로 반복 쓰레기에 걸렸다.aligned는 관계 기호(=·<·>·≤·≥·≲·≈·∼·≡ …)가 하나도 없을 때만, 반복 검사는 첨자를 지운 뒤에도 되풀이가 남을 때만 버린다 — 수식 벤치(20편 621쪽, 혼자 실행) 재현율 0.9447 → 0.9728, NED≤.3 재현율 0.9114 → 0.9425, 정확 일치 0.6033 → 0.6141, BLEU-4 0.8906 → 0.8974, 짝 2186 → 2251(종전 짝 중 빠지거나 NED 가 나빠진 것 0), 정밀도 0.9584 → 0.9554(새로 잡힌 식 중 정답지에 없는 display 식 11개 — 모두 실제 식), 쪽당 6.8초 - OCR 표 칸 음영: 20% 회색 머리 띠(휘도 204)를 잉크로 보면 띠 전체가 한 덩어리라 그 안의 진한 1px 세로선과 띠에 붙은 표 테두리까지 굵은 띠로 버려져 표 머리 칸이 뭉개졌다(관보 배출 정보 서식 두 단 머리 — 위 표 세로선 0개). 옅은 회색 면 가운데 양옆이 진한 괘선이고 네모를 채우며, 괘선이 면 밖으로 이어지거나(표 격자) 괘선 너머 다른 칸 음영과 맞닿은 면만 잉크에서 뺀다 — 아무 회색 면이나 빼면 그림 입체 틀 윤곽·사진 밝은 면 속 무늬·옅은 음영 칸 옆 진한 칸 가장자리가 가짜 괘선이 됐다(수능 한국사 order .97 → .51, 사진 칸 표 .44 → .10). 관보 두 쪽 CER .50 → .01·.149 → .088, 수능 국어 두 쪽 order .86 → .97·.99
- OCR 표 "값 (구성비)" 칸: 칸 상자 위아래에 걸친 칸 괘선(실선·점선) 행이 글자 사이 빈 열을 모두 막아 픽셀 빈 구간 근거가 없었고, "4,280 (100.0)" 이 두 열로 안 갈렸다. 상자 위아래 1/4 띠에서 폭의 35%(어디서든 85%) 넘게 잉크인 행은 빼고 센다. 값 아닌 글 둘뿐인 머리 줄이 틈 양옆에 글자 높이 1.2 배 안으로 붙으면("자기 집"·"전 세") 그 머리 행은 가르지 않아 두 열에 걸친다(열마다 따로 선 머리 "제조업 서비스 건설" 은 가른다) — 거처 점유 형태 표 .60 → 1.0, 장래인구 가정치 표 .913 → .922. 두 수정 합쳐 KoOCR-Bench 0.89698 → 0.89885(올라간 쪽 7, 내려간 쪽 3 — 각 −.002 이하), 자체 OCR·OCR robust·ODL-OCR 문서별 하락 0(robust 건축허가신청서 scan CER .57 → .37)
用户点评
登录用户的真实使用记录,可按版本和硬件筛选还没有人点评。第一个说出真实体验的人最有价值。
kordoc
모두 파싱해버리겠다.
대한민국에서 둘째가라면 서러울 문서지옥. 거기서 7년 버틴 공무원이 만들었습니다.
HWP 3.x·5.x, HWPX, HWPML, PDF, XLS·XLSX, DOCX, PPTX, PNG·JPG·WebP를 Markdown과 구조화 데이터로 변환합니다. 라이브러리·CLI·MCP 서버로 사용할 수 있습니다.
English · 상세 사용법 · 벤치마크 · 변경 이력

같은 법령 별표 한 건을 HWP·HWPX·PDF·스캔 이미지로 넣은 실제 출력입니다. 네 경우 모두 병합 칸(rowspan·colspan)을 같은 짜임의 표로 읽습니다. 스캔 이미지는 OCR이 자동으로 켜집니다.
- 📊 PDF 공개 벤치 종합 0.965: opendataloader-bench 200문서, 공개 리더보드(2026-09-29 기록) 12개 파서보다 높은 점수(4.24.50 측정). 측정 조건
- 🇰🇷 한국 공문서 표 구조 100%: 원본 HWPX 2,424문서의 보이는 표 10,342개 전부 구조 일치. 검증 결과
쓸모 있었다면 GitHub ⭐ 하나 눌러주세요. 다른 사람이 이 도구를 찾는 데 도움이 됩니다.
영상: 공개 벤치 측정 과정(2026-09-27 판, 1분 31초) · 양식 일괄 채우기 시연
설치
Node.js 20 이상 · macOS / Linux / Windows
npm install kordoc
CLI는 설치 없이 npx kordoc으로 실행할 수 있습니다. PDF·OCR·그림 형식 변환·QR 읽기 의존성은 기본 설치되며, --omit=optional로 제외하면 해당 기능이 제한됩니다.
AI 에이전트에 연결
npx -y kordoc setup
Claude Desktop·Claude Code·Cursor·Codex 등 설치된 클라이언트에 MCP를 등록합니다. 공식 MCP 레지스트리에도 io.github.chrisryugj/kordoc으로 등재돼 있습니다. 클라이언트를 재시작하면 파싱·비교·생성·검수·렌더 등 22개 도구를 사용할 수 있습니다.
VS Code·Cursor는 버튼 한 번으로 등록됩니다.
Claude Code 플러그인:
/plugin marketplace add chrisryugj/kordoc
/plugin install kordoc@kordoc
빠른 시작
CLI
npx kordoc 문서.hwpx -o 문서.md
npx kordoc *.pdf --jobs 4 -d ./결과
npx kordoc 문서.pdf --format json --pages 1-3
npx kordoc 스캔본.pdf --ocr -o 스캔본.md
npx kordoc generate 보고서.md --preset 보고서 -o 보고서.hwpx
npx kordoc to-hwpx 문서.hwp -o 문서.hwpx
npx kordoc to-hwpx ./옛문서 # 폴더째(하위 폴더까지) — 각 파일 옆에 .hwpx, 이미 있으면 건너뜀
npx kordoc 문서.pdf -o 문서.hwpx # PDF·DOCX 등도 읽은 내용으로 HWPX (그림 포함)
npx kordoc pack build 보고서1.hwpx 보고서2.hwpx 보고서3.hwpx --name 광양시 -o 광양시.kpack # 기관팩 (docs/agency-pack.md)
npx kordoc generate 새보고서.md --pack 광양시.kpack -o 새보고서.hwpx
npx kordoc fill --template gian -j 값.json -o 기안문.hwpx
npx kordoc lint 보고서.hwpx --gate --preset 보고서
--jobs는 파일 단위 병렬 변환이며 메모리 사용도 늘어납니다. 병렬 변환 안내
JavaScript / TypeScript
import { parse, markdownToHwpx } from "kordoc"
import { writeFile } from "node:fs/promises"
const result = await parse("문서.hwpx")
if (result.success) {
console.log(result.markdown)
// result.blocks: 구조화 데이터, result.metadata: 문서 정보
}
const hwpx = await markdownToHwpx("# 추진계획\n\n본문", {
gongmun: { preset: "보고서" },
})
await writeFile("보고서.hwpx", Buffer.from(hwpx))
주요 기능
| 작업 | 기능 |
|---|---|
| 읽기 | 문서 → Markdown·IR·쪽별 본문·RAG 청크, 로컬 OCR(손글씨 인식 포함), 그림 속 QR 값(--qr-codes), 그림 형식 통일(--image-format png|webp) |
| 비교·편집 | 블록·셀 단위 비교, HWPX·HWP 서식 보존 패치, 견본 서식 그대로 새 내용 쓰기 |
| 작성 | Markdown → HWPX, 공문서 프리셋·부서 서식 견본(--template), 표·수식·차트 |
| 변환 | HWP → HWPX — HWP 5.x 는 서식 그대로(글꼴·문단 모양·표·그림·도형·수식·머리말·각주·차트, 배포용·변경 추적 문서 포함). PDF·DOCX 등은 -o 문서.hwpx 로 읽은 내용을 HWPX 로 |
| 기관팩 | 우리 기관 문서 몇 건으로 서식 묶음(.kpack)을 만들어 그 서식대로 새 문서 — 기관팩 |
| 양식 | 필드·누름틀 채우기, 표준 기안문 2종, 도장 날인 |
| 검수 | 표기법·공공언어, 구성·AI 문체 게이트, 예산 산출근거 검산, 열린 문서 블록 단위 검수(lint-blocks) |
| 보기·보안 | HWPX·HWP 미리보기·영역 추출, 개인정보 마스킹 |
서식 보존 패치용 Markdown은 --keep-layout-tables로 추출합니다. 적용하지 못한 편집은 건너뛴 사유로 보고합니다. 서식 보존 편집 · CLI 전체
검증 결과
4.22.14 · 2026-10-19 검증(렌더 배치·별표는 4.24.24 · 2026-10-30, PDF 표는 4.24.35 · 2026-11-01, OCR 은 4.24.32 · 2026-11-01, HWP → HWPX 변환은 4.24.29 · 2026-10-31, PDF 글·KoOCR-Bench·opendataloader-bench 기본값과 OCR 켬은 4.24.50 · 2026-11-07). 고정 코퍼스와 참조 기준으로 측정한 결과입니다.
| 대상 | 규모 | 결과 |
|---|---|---|
| HWPX | 2,424문서 · 10,342표 | 표 구조 일치 10,342/10,342 · 100% |
| HWP 5.x ↔ HWPX | 1,130쌍 · 4,315표 | 짝 문서의 표 구조 일치 100% |
| HWP 5.x → HWPX 변환 | 한글 저장 짝 264쌍 (속성 대조 232쌍) | 속성 일치 99.21% · 완전 일치 69/232 · 글 264/264 · 한글 화면 대조 80문서 |
| PDF 글 | 744쌍 | 글자 재현율 99.885% · 정확도 99.682% · 읽기 순서 99.363% · 어절 F1 99.103% |
| PDF 표 | 708쌍 · 2,331표 | 표 탐지 99.83% · 구조 일치 98.24% · 칸 F1 0.9919 |
| HWPX 재조판 | 다중줄 25,187문단 (12개 폴더) | 모든 줄 시작 일치 24,941/25,187 · 99.02% |
| PDF 중첩표 (텍스트층) | 29문서 · 101표 | 구조·칸 내용 101/101 · 100% |
| 법령 별표 | 272건 · 346표 | HWP 346/346, PDF 343/346 · 99.13% |
| PDF 전체 | 1,911문서 중 1,729건 채점 | 글 커버리지 99.80% |
| OCR | 53문서 · 102쪽 · 66표 | CER 0.0239 · 글자 재현율 99.32% · 표 구조 일치 34/66 |
| KoOCR-Bench v2.0c (외부) | 공개 877쪽 (표·글·손글씨·순서) | 종합 기본값 0.904 · 표 0.912 · 손글씨 0.921 · 순서 0.913 · 제목 재현율 0.930 (4.24.56) |
| opendataloader-bench | PDF 200문서 | 종합 기본값 0.965 · ocr: true 0.967 · OCR 끔 0.939 (4.22.14) |
| HWPX 렌더 배치 | 한컴 PDF 짝 1,565문서(쪽 수 일치 1,508) · 글 조각 111,480 · 그림 4,300 | 글 위치(±1.5pt) 106,904 · 95.9% · 그림 위치(±2pt) 4,213 · 98.0% |
표 구조 점수와 셀 내용·화면 재현은 별도 지표입니다. 중첩표 100%는 위 101표에 한정하며 전체 PDF·조판의 완전 일치를 뜻하지 않습니다. 채점 범위·제외 기준·옵션별 수치·재현 방법은 벤치마크 상세에 있습니다.
최근 업데이트
최신 배포: 4.24.56 · 2026-11-09
| 버전 | 주요 변경 | 수치 변화 |
|---|---|---|
| 4.24.56 | OCR 저신뢰 줄을 많이 버린 쪽(바탕 그림 위 손편지)을 큰 검출로 다시 읽기 · OCR 표 "○ 항목 | 금액" 으로 쌓인 행 가르기(관보 자금조달·운용) | KoOCR-Bench 종합 0.90023 → 0.90370(손글씨 .908 → .921, 표 .9105 → .9120) · 자체 벤치 문서별 하락 0 |
| 4.24.55 | OCR 손글씨 쪽을 손글씨 인식기로 바꾸는 기본 문턱(.85~.90 쪽을 놓치던 것) · OCR 칸 괘선(겹선·점선)이 글자로 읽히던 것 · 점이 빠진 소수 짝("121/18.1") · PDF 수식 OCR 겹쳐 잡힌 중복 줄 · HWP 3.x 사용자 정의 개요 번호·찾아보기 표식·하이픈·가로선 | KoOCR-Bench 종합 0.89885 → 0.90023(손글씨 .901 → .908) · 수식 OCR 정밀도 0.955 → 0.968(보고 전용) · 자체 벤치 문서별 하락 0 |
| 4.24.54 | PDF·OCR 좌우로 나란히 놓인 두 표가 한 표로 쌓이던 것 · PDF 수식 OCR 쓰레기 거름이 부등식 유도·같은 첨자 식을 버리던 것 · OCR 표 회색 머리 띠 안 칸 구분선 · OCR "값 (구성비)" 칸 가르기 | KoOCR-Bench 종합 0.89420 → 0.89885(표 .902 → .911) · 수식 OCR 재현율 0.945 → 0.973(보고 전용) · 자체 벤치 문서별 하락 0 |
| 4.24.53 | PDF 수식 OCR: 긴 식이 256토큰에서 잘리던 것(최대 512)·여러 줄 식 조각 잇기 · OCR 한 행만 긋는 짧은 칸 구분선 · OCR 번호 뒤 띄어 쓴 장·절 제목 | 수식 OCR 재현율 0.931 → 0.945(보고 전용) · KoOCR-Bench 종합 0.89408 → 0.89420 · 제목 재현율 0.924 → 0.930 · 자체 벤치 문서별 하락 0 |
| 4.24.52 | PDF 그림을 글 사이 제자리에 두는 imagePlacement: "flow"(옵션) · 빈 그림 빼기 dropBlankImages · 띠 그림을 쌓은 상자가 1열 표가 되던 것 · OCR 표에 갇힌 문장 줄을 문단으로 (#195) | KoOCR-Bench 종합 0.8936 → 0.8941(표 .901 → .902) · 자체 벤치 문서별 하락 0 |
이전 버전과 상세 내용은 변경 이력에 있습니다.
자주 묻는 질문
Q. HWP·HWPX 파일을 Markdown으로 바꾸려면?
npx kordoc 문서.hwp -o 문서.md 한 줄입니다. 한컴오피스 없이 파일을 직접 읽으며, 여러 파일은 npx kordoc *.hwpx -d ./output으로 한 번에 바꿉니다.
Q. Claude·Cursor 같은 AI가 한글 문서를 읽게 하려면?
npx -y kordoc setup으로 MCP를 등록하면 AI가 파일 경로만 받아 HWP·PDF·엑셀을 읽고, 비교하고, 양식을 채웁니다.
Q. 인터넷이 막힌 폐쇄망에서도 되나요?
됩니다. KORDOC_OFFLINE=1이 외부 통신을 모두 막고, OCR도 API 키 없이 로컬 CPU에서 돕니다. 폐쇄망 설치
Q. RAG 색인용으로 쓸 수 있나요?
--format chunks가 제목 경로를 붙인 구조 청크와 독립 표 청크를 냅니다. 표를 HTML 없이 받으려면 --table-format gfm(API는 tableFormat: "gfm")을 씁니다. Python·Java에서는 Python SDK·Java SDK로 부릅니다.
Q. OCR 줄 좌표나 다른 모델이 필요하면?
--ocr --ocr-lines --format json이 줄별 상자·신뢰도를 내고, --ocr-det·--ocr-det-long-side로 검출 모델과 해상도를, --ocr-rec handwriting|auto로 손글씨 인식 모델을 고릅니다. OCR 줄·모델 선택
문서·보안
- 상세 사용법: 전체 CLI·MCP 도구·API·지원 포맷
- Java SDK · Python SDK: 상주 엔진 워커로 Java·Python 시스템에서 파싱 (워커 프로토콜)
- 공문서 생성 가이드 · 아키텍처
- 폐쇄망 설치:
KORDOC_OFFLINE=1, MCP 접근 범위KORDOC_ROOT - 보안 정책 · 라이선스 MIT · 오픈소스 고지
만든 사람
대한민국 지방공무원. 광진구청에서 7년간 HWP 파일과 싸우다가 이걸 만들었습니다. 5개 공공 프로젝트에서 수천 건의 실제 관공서 문서를 파싱하며 검증했습니다.