kordoc

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.964: opendataloader-bench 200문서, 공개 리더보드 12개 파서보다 높은 점수(4.22.14 측정). 측정 조건
• 🇰🇷 한국 공문서 표 구조 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 의존성은 기본 설치되며, --omit=optional로 제외하면 해당 기능이 제한됩니다.

AI 에이전트에 연결

npx -y kordoc setup

Claude Desktop·Claude Code·Cursor·Codex 등 설치된 클라이언트에 MCP를 등록합니다. 공식 MCP 레지스트리에도 io.github.chrisryugj/kordoc으로 등재돼 있습니다. 클라이언트를 재시작하면 파싱·비교·생성·검수·렌더 등 18개 도구를 사용할 수 있습니다.

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 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은 --keep-layout-tables로 추출합니다. 적용하지 못한 편집은 건너뛴 사유로 보고합니다. 서식 보존 편집 · CLI 전체

검증 결과

4.22.14 · 2026-10-19 검증(렌더 배치는 4.24.2 · 2026-10-24). 고정 코퍼스와 참조 기준으로 측정한 결과입니다.

표 구조 점수와 셀 내용·화면 재현은 별도 지표입니다. 중첩표 100%는 위 101표에 한정하며 전체 PDF·조판의 완전 일치를 뜻하지 않습니다. 채점 범위·제외 기준·옵션별 수치·재현 방법은 벤치마크 상세에 있습니다.

최근 업데이트

최신 배포: 4.24.2 · 2026-10-24

이전 버전과 상세 내용은 변경 이력에 있습니다.

자주 묻는 질문

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 줄·모델 선택

문서·보안

• 상세 사용법: 전체 CLI·MCP 도구·API·지원 포맷
• Java SDK · Python SDK: 상주 엔진 워커로 Java·Python 시스템에서 파싱 (워커 프로토콜)
• 공문서 생성 가이드 · 아키텍처
• 폐쇄망 설치: KORDOC_OFFLINE=1, MCP 접근 범위 KORDOC_ROOT
• 보안 정책 · 라이선스 MIT · 오픈소스 고지

만든 사람

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