kordoc

모두 파싱해버리겠다.

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

HWP 3.x·5.x, HWPX, HWPML, PDF, XLS·XLSX, DOCX, PPTX, 이미지(PNG·JPG·WebP·TIFF·GIF·BMP·AVIF·HEIC·PCX)를 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

수동 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). 고정 코퍼스와 참조 기준으로 측정한 결과입니다.

대상	규모	결과
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.887% · 정확도 99.685% · 읽기 순서 99.398% · 어절 F1 99.131%
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쪽 · 65표	CER 0.0237 · 글자 재현율 99.33% · 표 구조 일치 33/65
KoOCR-Bench v2.0c (외부)	공개 877쪽 (표·글·손글씨·순서)	종합 기본값 0.906 · 표 0.916 · 손글씨 0.921 · 순서 0.914 · 제목 재현율 0.930 (4.24.68)
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%

This is the beginning of the README. Read the rest at the original. Read the full README ↗