Airsc is free for everyone. If it helps you, support it with $2–$20.

Support
VISign in
PluginSafeDocs, writing & contentBeginner friendly

kordoc

chrisryugj · chrisryugj/kordoc

Convert Korean documents (HWP, HWPX, PDF, Office) into clean Markdown or structured data using an MCP server or Claude plugin.

모두 파싱해버리겠다 — HWP·HWPX·PDF·Office 문서를 Markdown으로. 양식 자동 채우기와 신구대조를 갖춘 CLI·MCP 서버 | Convert Korean documents (HWP, HWPX, PDF, Office) to Markdown — CLI and MCP server with form filling and diff

2.4k stars439License: MITUpdated 8 days ago0 opens

Preview

▍

What you can do with it

  • Parse complex Korean government HWP files into Markdown for LLM analysis
  • Auto-fill Korean HWP document templates using JSON data via an AI agent
  • Batch convert scanned PDF documents to Markdown using OCR tools in Claude

Safety check

Safe

No risky patterns found in the files we scanned.

Automated scan of the repo files. Always review code you run.

From the README

kordoc

모두 파싱해버리겠다.

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

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

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

  • 📊 PDF 공개 벤치 종합 0.963 — opendataloader-bench 200문서. 공개 12개 파서 비교 1위(2026-09-29 기록). 측정 조건
  • 🇰🇷 한국 공문서 표 구조 100% — 원본 HWPX 2,424문서의 보이는 표 10,342개 전부 구조 일치. 4.21.20 검증

쓸모 있었다면 GitHub ⭐ 하나 눌러주세요. 다른 사람이 이 도구를 찾는 데 도움이 됩니다.

▶ 클릭하면 유튜브에서 재생됩니다.

새 영상: kordoc 공개벤치 1위 마크 · 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를 등록합니다. 클라이언트를 재시작하면 파싱·비교·생성·렌더 등 17개 도구를 사용할 수 있습니다.

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

--jobs는 파일 단위 병렬 변환이며 메모리 사용도 늘어납니다. 병렬 변환 안내

보고서·계획서·개조식·서울방침은 # 제목 바로 뒤 인용문(> …하고자 함)이 요약 상자가 됩니다(개조식은 표지가 있을 때(기본) 본문 첫 쪽 제목 상자 아래 — cover:false 면 첫 # 이 장 머리라 인용문은 ※ 참고). 보고 목적 한 문장(쉼표 허용) 3줄 이내로 쓰고, 넘거나 두 문장 이상이면 경고합니다. 업무보고는 > ▪ … 인용문이 자리와 관계없이 성과 요약 상자가 됩니다.

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
비교·편집블록·셀 단위 비교, HWPX·HWP 서식 보존 패치
작성Markdown → HWPX, 공문서 프리셋, 표·수식·차트
양식필드·누름틀 채우기, 표준 기안문 2종, 도장 날인
검토HWPX·HWP 미리보기·영역 추출, 구조·표기법 검사, 개인정보 마스킹

서식 보존 패치용 Markdown은 --keep-layout-tables로 추출합니다. 적용하지 못한 편집은 건너뛴 사유로 보고합니다. CLI·API 상세

검증 결과

4.21.20 · 2026-10-11 배포 검증. 고정 코퍼스와 참조 기준으로 측정한 결과입니다.

대상규모결과
HWPX2,424문서 · 10,342표표 구조 일치 10,342/10,342 · 100%
HWP 5.x ↔ HWPX1,130쌍 · 4,315표짝 문서의 표 구조 일치 100%
PDF 글744쌍글자 재현율 99.85% · 정확도 99.64% · 읽기 순서 99.23% · 어절 F1 99.00%
PDF 표708쌍 · 2,331표표 탐지 99.83% · 구조 일치 97.98% · 칸 F1 0.991
PDF 전체1,911문서 중 1,729건 채점글 커버리지 99.80%
OCR53문서 · 102쪽CER 0.0412 · 글자 재현율 99.02%

표 구조 점수와 셀 내용·화면 재현은 별도 지표입니다. 채점 범위·제외 기준·전 벤치 문서별 비교는 벤치마크 상세에 있습니다.

외부 PDF 벤치 opendataloader-bench 200문서는 4.21.20 배포 측정에서 기본값 종합 0.963, OCR 끔 0.939입니다. 옵션별 결과와 재현 방법

최근 업데이트

최신 배포: 4.21.20 · 2026-10-11

버전주요 변경
4.21.20PDF 괘선 없는 표 칸의 어절 가운데 꺾임을 붙여 씀("남⏎편이") · 채우기·패치 서식 보존(바뀐 문단만 줄 배치 캐시 삭제·강조 표지·균등 띄어쓰기·라벨 칸 방향) (PDF 어절 F1 98.987 → 98.998%)
4.21.19PDF 위아래로 쌓인 표와 사이 글줄을 한 표로 묶던 괘선 격자 버리기 — 지역 머리·각주가 제 표와 떨어지던 것 (PDF 읽기 순서 99.16 → 99.23%)
4.21.18쪽 넘김 문단 잇기도 줄 끝 공백 글리프를 어절 경계로 — "지원⏎활동이"·"계정⏎정보를" 을 띄워 씀 (PDF 어절 F1 98.986 → 98.987%, 5문서 상승)
4.21.17PDF 공백 없는 꽉 찬 줄 끝 + 영문 괄호 — "공적개발원조⏎(ODA)"·"하네스⏎(safety …)" 를 붙여 씀 (PDF 어절 F1 98.98 → 98.99%)
4.21.16PDF 표 쪽 넘김 갈린 행의 수량 이어짐 — 머리 칸 "30%" / 다음 쪽 "미만" 을 한 칸으로; 공문서 autoFit.safety(다른 조판기용 한 줄 판정 여유) (법령 별표 PDF 표 97.40 → 97.69%)
4.21.15PDF 줄 끝 공백 글리프로 어절 경계 꺾임 가르기 — 원문이 띄운 줄 꺾임("이루어⏎진다면")을 붙이던 것 (PDF 어절 F1 98.89 → 98.98%)
4.21.14한컴 PDF 유니코드 없는 기호 되살리기 — 자동 글머리표·괄호(U+F000)를 글꼴 윤곽 모양으로 "▸"·"□"·"《》"·"↓" 등으로; 텍스트층 커버리지 채점 기준 변경 (PDF 어절 F1 98.87 → 98.89%·글 재현율 99.83 → 99.84%)
4.21.13PDF 법령 별표 쪽 넘김 행 — 번호 열이 다음 차례면 새 행, "가)" 항목도 다음 항목 머리로, 쪽을 넘는 긴 칸은 두 행을 덮는 한 칸으로; parse-worker 가 닫힌 stdout 에서 조용히 끝남(#142) (법령 별표 PDF 표 구조 일치 96.82 → 97.40%, 문서별 하락 0)
4.21.12PDF 칸 숫자 줄·걸친 글상자·배분 이름표·첨자 겹침 — 칸을 채운 숫자 줄만 잇기, 서로 걸친 글상자는 글로, 숫자 행 배분 두 음절 붙이기, 붙은 첨자 겹침 허용 0.25em (PDF 어절 F1 98.86 → 98.87%·ODL 표 TEDS 0.9799 → 0.9802, 문서별 하락 0)
4.21.11PDF 목차·라벨탭 상자·칸 첨자 — 목차 리더 걷기, 제목 칩 상자를 글로, 목차 칸 제목·쪽 번호 짝짓기, 서식 칸 붙은 첨자 흡수 (PDF 글 정확도 99.58 → 99.64%·OCR CER 0.0421 → 0.0412, 문서별 하락 0 — 열화 OCR 은 표본 쪽 셋 이동)
4.21.10PDF 흐름도 표·괄호 풀이 — 선 격자 표를 품은 클러스터 후보 거름, 짧은 괄호 풀이 앞 줄 꺾임 이음 (PDF 어절 F1 98.84 → 98.85%·OCR CER 0.0443 → 0.0421, 문서별 하락 0)
4.21.9PDF 줄 꺾임 이음 — 낱말 가운데 꺾임·겹조사·계사·접미사·명사+하다, 본문 위 첨자 행 흡수 (PDF 어절 F1 98.81 → 98.84%·글 커버리지 99.79 → 99.80%, 문서별 하락 0)
4.21.8PDF 표 묶음 — 돌려 찍은 가로 표 세우기·데이터 표의 차트 오판·좁은 숫자 열·칸 걸친 한 조각·칸 안 쌓인 금액 (OCR CER 0.0445 → 0.0443·열화 OCR scan 0.0821 → 0.0805, 문서별 하락 0)
4.21.7PDF 토막 괘선 칸·글 조각 클립·연락처 표 — 예산서 상세 칸(OCR CER 0.0512 → 0.0445), ezPDF·MS Print 글 조각 클립이 만든 가짜 표, 연락처 6열 (열화 OCR scan 0.0954 → 0.0821·글 커버리지 99.78 → 99.79%, 문서별 하락 0)
4.21.6연락처 표 부서별 병합·여러 사람 칸 분할(PDF 표 구조 일치 97.94→97.98%), XLSX·XLS 200열 밖 칸 유실 수리, HWP3 포함 그림 추출, 수식 OCR LaTeX 명령 쪼개기·영역 상한 수리, PPTX 서식 트랙·코퍼스 보강(HWP3 75·서식 58·rhwp 230)
4.21.5PDF 품질 묶음 — OCR 두 단 가짜 표(#141 부작용)·그림 OCR 라벨 묶음·한 자리 눈금, 주소 링크·벡터 차트 값 축·단 끝줄·각주 순서 (ODL 기본 0.958 → 0.963, 문서별 하락 0) · 개조식·보고서 요약 상자가 md→hwpx→md→hwpx 왕복에서 유지
4.21.4MCP fill_form 값 파일 입력 fields_file(값이 대화에 안 남고 응답은 글자 수만), 전 벤치 묶음 러너·문서별 비교기 bench/suite.mjs
4.21.3PDF 수식 OCR 의 짝 없는 \left·\right
View source on GitHub