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 images (PNG/JPG/WebP/TIFF/GIF/BMP/AVIF/HEIC/PCX) 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.965 overall on the public PDF benchmark: opendataloader-bench, 200 documents, higher than the 12 parsers on the public leaderboard (as recorded on 2026-09-29; measured on 4.24.50). 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, image-format conversion and QR-reading 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 22 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 to-hwpx document.hwp -o document.hwpx
npx kordoc to-hwpx ./old-docs   # whole folder (subfolders too) — .hwpx next to each file, existing ones skipped
npx kordoc document.pdf -o document.hwpx   # PDF, DOCX and others become HWPX from what was read (images included)
npx kordoc pack build report1.hwpx report2.hwpx report3.hwpx --name Gwangyang -o gwangyang.kpack   # agency pack (docs/agency-pack-en.md)
npx kordoc generate new-report.md --pack gwangyang.kpack -o new-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

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 and statute annexes: 4.24.24 · 2026-10-30; PDF tables: 4.24.35 · 2026-11-01; OCR: 4.24.32 · 2026-11-01; HWP → HWPX conversion: 4.24.29 · 2026-10-31; PDF text, KoOCR-Bench and opendataloader-bench defaults and OCR on: 4.24.50 · 2026-11-07). Results use fixed corpora and reference criteria.

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.78 · 2026-11-14

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, and --ocr-rec handwriting|auto selects the handwriting recognizer. 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
• gVisor sandbox: run the parser inside gVisor to protect the host (Linux; KORDOC_SANDBOX=gvisor or docker --runtime=runsc, Korean)
• 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.