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 18 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
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, PDF text, PDF tables and OCR: 4.24.6 · 2026-10-25). 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.881% · precision 99.676% · reading order 99.307% · word-boundary F1 99.064%
PDF tables	708 pairs · 2,331 tables	Detection 99.83% · structure match 98.20% · 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.0332 · character recall 99.02% · table structure 25/67
opendataloader-bench	200 PDF documents	Overall 0.964 with defaults · 0.939 with OCR off
HWPX render layout (4.24.6)	Hancom PDF pairs · 90,906 text runs · 4,107 images	Text position (±1.5pt) 87,620 · 96.4% · 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.6 · 2026-10-25

Version	Highlights	Measured change
4.24.6	OCR: budget-statement sub-rows (expense codes and item lines), coloured header bands split into cells, two stacked lines inside a cell no longer swapped · PDF: four-glyph vertical side tabs · Rendering: page-number restarts · HWPX: whitespace in indented XML	OCR CER 0.0409 → 0.0332 · OCR table structure 24 → 25/67 · rendered text position 87,509 → 87,620 · PDF reading order 99.302% → 99.307%
4.24.5	PDF: line-drawn fraction bars restored as equations, false borderless tables from monospace lines, overprinted table-of-contents page numbers · OCR: sub-rows stacked without rules, faint white dividers in coloured header bands, no underline markup on OCR text · HWPX·HWP: below-table captions in reading order	PDF reading order 99.247% → 99.302% · annex equations 7 → 11/11 · OCR table structure 21 → 24/67
4.24.4	Rendering: overfull lines shrink spaces to 20% then every glyph, cell heights grown by floating objects, documents authored with a KoPub substitute font, page-bottom row checks · PDF: cell edges crossed by a neighbouring cell's rule	Rendered text positions 87,289 → 87,509 (new measurement basis) · images 4,017 → 4,019 · PDF table structure 98.16% → 98.20%
4.24.3	Rendering: merged cells that Hangul saved split across pages, staggered merged-row heights, inherited odd/even master pages, rotated pictures in groups, shadowed pictures · PDF: continuations of rows split at each page bottom are kept	Rendered text positions 86,954 → 87,215 · images 3,881 → 4,017 · annex PDF recall 0.99976 → 0.99982
4.24.2	Rendering matched to Hancom PDF output: floating tables carried over from the previous page, stacked floats inside cells, double-counted vertical offsets, last-row height, spaces before line breaks, page numbers	Rendered text positions 86,508 → 86,954 / 90,550 · images 3,872 → 3,881 / 3,976

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.