kordoc

모두 파싱해버리겠다. Parse them all.

Korea's document hell is second to none. Built by a civil servant who survived seven years in it.

Convert HWP 3.x/5.x, HWPX, HWPML, PDF, XLS/XLSX, DOCX, PPTX and PNG/JPG/WebP to Markdown and structured data. Use it as a library, CLI or MCP server.

한국어 · Usage guide · Benchmarks · Changelog

_{Actual output for one statute annex given as HWP, HWPX, PDF and a scanned image. All four read the merged cells (rowspan, colspan) into the same table structure. OCR turns on automatically for images.}

📊 0.964 overall on the public PDF benchmark: opendataloader-bench, 200 documents, higher than the 12 parsers on the public leaderboard (measured on 4.22.14). Measurement details
🇰🇷 100% Korean document table structure match: all 10,342 visible tables from 2,424 original HWPX documents. Validation

If this saves you time, a GitHub ⭐ helps others find it.

Videos (Korean): public benchmark run (2026-09-27 cut, 1 min 31 sec) · batch form filling demo

Install

Node.js 20+ · macOS / Linux / Windows

npm install kordoc

Run the CLI without installing it globally: npx kordoc. PDF/OCR dependencies are installed by default; omitting them with --omit=optional limits those features.

Connect an AI agent

npx -y kordoc setup

Registers MCP with installed clients such as Claude Desktop, Claude Code, Cursor and Codex. Restart the client to use 20 tools for parsing, comparison, generation, review, rendering and more. kordoc is also listed on the official MCP Registry as io.github.chrisryugj/kordoc.

One-click install for VS Code and Cursor:

Claude Code plugin:

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

Manual MCP setup and installation troubleshooting

Quick start

CLI

npx kordoc document.hwpx -o document.md
npx kordoc *.pdf --jobs 4 -d ./output
npx kordoc document.pdf --format json --pages 1-3
npx kordoc scan.pdf --ocr -o scan.md
npx kordoc generate report.md --preset report -o report.hwpx
npx kordoc fill --template gian -j values.json -o draft.hwpx
npx kordoc lint report.hwpx --gate --preset report

--jobs converts files in parallel and increases memory use. Batch conversion details

JavaScript / TypeScript

import { parse, markdownToHwpx } from "kordoc"
import { writeFile } from "node:fs/promises"

const result = await parse("document.hwpx")
if (result.success) {
  console.log(result.markdown)
  // result.blocks: structured data; result.metadata: document metadata
}

const hwpx = await markdownToHwpx("# Plan\n\nBody text", {
  gongmun: { preset: "report" },
})
await writeFile("report.hwpx", Buffer.from(hwpx))

Parse options, APIs, forms and rendering examples

Features

Task	Capabilities
Read	Markdown, IR, page text, RAG chunks and local OCR
Compare and edit	Block/cell diffs, format-preserving HWPX/HWP patches, new content in a sample's format
Create	Markdown → HWPX, government-document presets and department templates (`--template`), tables, equations and charts
Agency packs	Build a house-style pack (`.kpack`) from a few of your own agency documents and write new documents in that style — agency packs
Fill forms	Fields, click-here controls, two draft templates and seal placement
Review	Notation and public-language rules, structure and AI-writing gate, budget calculation checks, block-level lint for open documents (`lint-blocks`)
View and protect	HWPX/HWP previews and region crops, PII masking

Extract Markdown for format-preserving patches with --keep-layout-tables. Unsupported edits are skipped with a reason. Format-preserving editing · Full CLI reference

Validation

4.22.14 verification · 2026-10-19 (render layout: 4.24.14; PDF text, PDF tables and OCR: 4.24.17 · 2026-10-29). Results use fixed corpora and reference criteria.

Target	Population	Result
HWPX	2,424 documents · 10,342 tables	Table structure match 10,342/10,342 · 100%
HWP 5.x ↔ HWPX	1,130 pairs · 4,315 tables	Paired-document table structure match 100%
PDF text	744 pairs	Character recall 99.883% · precision 99.678% · reading order 99.312% · word-boundary F1 99.067%
PDF tables	708 pairs · 2,331 tables	Detection 99.83% · structure match 98.24% · cell F1 0.9919
HWPX reflow	25,187 multiline paragraphs (12 folders)	All line starts match 24,941/25,187 · 99.02%
Nested PDF tables (text layer)	29 documents · 101 tables	Structure and cell content 101/101 · 100%
Statute annexes	272 documents · 346 tables	HWP 346/346, PDF 342/346 · 98.84%
All PDFs	1,729 scored out of 1,911 documents	Text coverage 99.80%
OCR	53 documents · 102 pages · 67 tables	CER 0.0244 · character recall 99.32% · table structure 26/67
opendataloader-bench	200 PDF documents	Overall 0.964 with defaults · 0.939 with OCR off
HWPX render layout (4.24.14)	Hancom PDF pairs · 90,840 text runs · 4,107 images	Text position (±1.5pt) 87,643 · 96.5% · image position (±2pt) 4,019 · 97.9%

Table structure, cell content and visual fidelity are separate metrics. The nested-table 100% applies only to these 101 tables, not all PDF parsing or page layout. See benchmark details for scope, exclusions, per-option scores and reproduction.

Recent updates

Latest release: 4.24.17 · 2026-10-29

Version	Highlights	Measured change
4.24.17	OCR: leading chapter numbers and page numbers after leaders missed by the detector, two-line table cells dropped as one box, shadowed bullets ❐·○ and table-of-contents ◎ on skewed pages, bracket pair consistency, tortoise-shell brackets 〔〕 and the parallel sign ∥, table-of-contents lines split where the leader broke · optional detector `ocrDet: "medium"` (#176)	OCR CER 0.0250 → 0.0244 · character recall 99.27% → 99.32% · precision 99.54% → 99.56% · all 9 degraded-input sets improved (clean 0.0394 → 0.0386, blur 0.0550 → 0.0522, scan 0.0693 → 0.0668)
4.24.16	OCR: short table-of-contents leaders ··, Ⅲ in task codes read as Hangul and [ before boxed numbers, circled numbers with a hyphen touching the ring, Roman numeral stroke counts after Hangul (Ⅰ vs Ⅱ), closing parens of form cells next to a cell border or after a long blank	OCR CER 0.0255 → 0.0250 · character recall 99.23% → 99.27% · precision 99.53% → 99.54% · 8 of 9 degraded-input sets improved (clean 0.0397 → 0.0394; scan 0.0692 → 0.0693)
4.24.15	OCR: form placeholder boxes □□-□□□, leading table-of-contents dashes and lone trailing page numbers missed by the detector, large ■ bullets, liter sign ℓ, small ring 。, leading middle dots buried under the line above, hallucinated slash cells · PDF: joining two-line paragraphs in widely spaced Chinese and Japanese text	OCR CER 0.0260 → 0.0255 · character recall 99.19% → 99.23% · 8 of 9 degraded-input sets improved (clean 0.0405 → 0.0397; noise 0.0485 → 0.0486) · PDF word-boundary F1 99.066% → 99.067%
4.24.14	Rendering: cell positions in tables with `cellSpacing` · OCR: 「 read as a space or quote, page numbers missed by the detector, leading ○ before Latin acronyms or read as C, ring-only cells ○, diamond bullets ◆·◇·◈, far closing paren in form cells	Rendered text position 87,577 → 87,643 · OCR CER 0.0263 → 0.0260 · all 9 degraded-input sets improved (clean 0.0409 → 0.0405)
4.24.13	Agency packs (`.kpack`): build a style pack from a few of an agency's own documents and write new documents in that style · OCR: borderless-table column order and widely spread justified words, stroke fragments inside a read glyph box, leading □ outside the line box, period on the start date of ~ ranges, phone sign ☎ · PDF and HWP: Hancom soft hyphens shown as visible hyphens (minus signs in change columns) · patch added-paragraph emphasis style and render overlap of grown tables (#175)	Agency-pack reproduction of unseen documents: Seoul 68.3% → 74.3% · Gwangyang 77.1% → 94.5% · OCR CER 0.0281 → 0.0263 · all 9 degraded-input sets improved (clean 0.0429 → 0.0409)

See the changelog for earlier releases and details.

FAQ

How do I convert an HWP or HWPX file to Markdown?
npx kordoc document.hwp -o document.md. It reads the file directly, without Hancom Office. Convert many files at once with npx kordoc *.hwpx -d ./output.

How do I let Claude, Cursor or another AI agent read Korean documents?
Run npx -y kordoc setup to register the MCP server. The agent can then read, compare and fill HWP, PDF and Excel files from a file path.

Does it work on an air-gapped network?
Yes. KORDOC_OFFLINE=1 blocks all outbound traffic, and OCR runs on the local CPU with no API key. Offline deployment

Can I use it for RAG indexing?
--format chunks emits structure chunks with heading breadcrumbs plus standalone table chunks. Use --table-format gfm (API: tableFormat: "gfm") for tables without HTML. From Python or Java, use the Python SDK or Java SDK.

Can I get OCR line boxes or use another model?
--ocr --ocr-lines --format json exports line boxes and confidence; --ocr-det and --ocr-det-long-side select the detector and resolution. OCR lines and models

Documentation and security

Usage guide: complete CLI, MCP tools, APIs and format support
Java SDK · Python SDK: parse from Java and Python systems through a resident engine worker (worker protocol, Korean)
Government-document generation · Architecture
Offline deployment: KORDOC_OFFLINE=1; MCP file scope with KORDOC_ROOT
Security policy · MIT license · Third-party notices

About the Author

A local civil servant in Korea. Built this after seven years of wrestling HWP files at the Gwangjin-gu District Office in Seoul. Validated on thousands of real government documents across five public-sector projects.