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

v4.24.58发布于 2026-11-09 13:32 UTC2,958star +20 / 7 天522fork同步于 2026-11-10 23:43 UTC

怎么上手

由 README 提炼,执行前请确认
npm install kordoc
npx kordoc 문서.hwpx -o 문서.md
硬件要求按 README 说明

README 未说明 GPU 或显存要求;OCR 可在本地 CPU 上运行,无需 API 密钥,并支持在断网环境中使用。

下载:源码 zip·GitHub Releases(安装包)本站不镜像安装包

项目说明

由 README 自动翻译提炼

把韩文 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 客户端

容易踩的坑

需要 Node.js 20 或更高版本;用 --omit=optional 安装会限制 PDF、OCR、图片格式转换和 QR 读取功能;MCP 注册后需要重启客户端才能使用 22 个工具。

内容由模型根据 README 生成,可能不完整或不准确,以官方文档为准。看原文 README

最近发版

5 个版本v4.24.58
  1. 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 2 transport.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
  2. 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 audit 0건)
      • @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

  3. 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. 금액 칸 없이 글만 쌓인 "○" 목록은 그대로
  4. 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
  5. 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)

用户点评

登录用户的真实使用记录,可按版本和硬件筛选
共 0 条

    还没有人点评。第一个说出真实体验的人最有价值。

    README 原文

    未翻译

    kordoc

    모두 파싱해버리겠다.

    npm version license MCP Registry

    대한민국에서 둘째가라면 서러울 문서지옥. 거기서 7년 버틴 공무원이 만들었습니다.

    HWP 3.x·5.x, HWPX, HWPML, PDF, XLS·XLSX, DOCX, PPTX, PNG·JPG·WebP를 Markdown과 구조화 데이터로 변환합니다. 라이브러리·CLI·MCP 서버로 사용할 수 있습니다.

    English · 상세 사용법 · 벤치마크 · 변경 이력

    같은 법령 별표를 HWP·HWPX·PDF·스캔 이미지로 넣은 kordoc 실제 출력

    같은 법령 별표 한 건을 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는 버튼 한 번으로 등록됩니다.

    VS Code에 설치 Cursor에 설치

    Claude Code 플러그인:

    /plugin marketplace add chrisryugj/kordoc
    /plugin install kordoc@kordoc
    

    수동 MCP 등록과 설치 문제 해결

    빠른 시작

    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))
    

    파싱 옵션·API·양식·렌더 예제

    주요 기능

    작업기능
    읽기문서 → 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). 고정 코퍼스와 참조 기준으로 측정한 결과입니다.

    대상규모결과
    HWPX2,424문서 · 10,342표표 구조 일치 10,342/10,342 · 100%
    HWP 5.x ↔ HWPX1,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%
    OCR53문서 · 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-benchPDF 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.56OCR 저신뢰 줄을 많이 버린 쪽(바탕 그림 위 손편지)을 큰 검출로 다시 읽기 · OCR 표 "○ 항목 | 금액" 으로 쌓인 행 가르기(관보 자금조달·운용)KoOCR-Bench 종합 0.90023 → 0.90370(손글씨 .908 → .921, 표 .9105 → .9120) · 자체 벤치 문서별 하락 0
    4.24.55OCR 손글씨 쪽을 손글씨 인식기로 바꾸는 기본 문턱(.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.54PDF·OCR 좌우로 나란히 놓인 두 표가 한 표로 쌓이던 것 · PDF 수식 OCR 쓰레기 거름이 부등식 유도·같은 첨자 식을 버리던 것 · OCR 표 회색 머리 띠 안 칸 구분선 · OCR "값 (구성비)" 칸 가르기KoOCR-Bench 종합 0.89420 → 0.89885(표 .902 → .911) · 수식 OCR 재현율 0.945 → 0.973(보고 전용) · 자체 벤치 문서별 하락 0
    4.24.53PDF 수식 OCR: 긴 식이 256토큰에서 잘리던 것(최대 512)·여러 줄 식 조각 잇기 · OCR 한 행만 긋는 짧은 칸 구분선 · OCR 번호 뒤 띄어 쓴 장·절 제목수식 OCR 재현율 0.931 → 0.945(보고 전용) · KoOCR-Bench 종합 0.89408 → 0.89420 · 제목 재현율 0.924 → 0.930 · 자체 벤치 문서별 하락 0
    4.24.52PDF 그림을 글 사이 제자리에 두는 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 줄·모델 선택

    문서·보안

    만든 사람

    대한민국 지방공무원. 광진구청에서 7년간 HWP 파일과 싸우다가 이걸 만들었습니다. 5개 공공 프로젝트에서 수천 건의 실제 관공서 문서를 파싱하며 검증했습니다.