Skip to content
Cobalt Rentals

MCP Registry

kordoc is a document parser that converts Korean and international document formats to Markdown and structured data. Built by a civil servant who spent seven years navigating Korea's complex document ecosystem, it handles HWP 3.x/5.x, HWPX, HWPML, PDF, XLS/XLSX, DOCX, PPTX, and PNG/JPG/WebP files. Use it as a library, CLI, or MCP server.

Key capabilities

  • Read: Markdown, intermediate representation, page text, RAG chunks, and local OCR
  • Compare and edit: Block and cell diffs, format-preserving HWPX/HWP patches, new content in a sample's format
  • Create: Markdown to HWPX conversion, government-document presets, department templates, tables, equations, and charts
  • Convert: HWP to HWPX with formatting preserved (fonts, paragraph shapes, tables, pictures, shapes, equations, headers, footnotes, charts)
  • Agency packs: Build house-style packs (.kpack) from your own agency documents and write new documents in that style
  • Fill forms: Fields, click-here controls, draft templates, and seal placement
  • Review: Notation and public-language rules, structure and AI-writing gate, budget calculation checks, block-level lint
  • View and protect: HWPX/HWP previews, region crops, and PII masking

Performance

  • 0.964 overall on the public PDF benchmark (opendataloader-bench, 200 documents), higher than 12 parsers on the public leaderboard
  • 100% Korean document table structure match across all 10,342 visible tables from 2,424 original HWPX documents
  • 99.885% character recall on PDF text extraction with 99.360% reading order accuracy
  • 99.83% table detection and 98.24% structure match on PDF tables

Installation

Requires Node.js 20+ on macOS, Linux, or Windows.

npm install kordoc

Run the CLI without installing globally: npx kordoc. PDF and OCR dependencies are installed by default; omit them with --omit=optional to limit 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 access 22 tools for parsing, comparison, generation, review, rendering, and more. kordoc is listed on the official MCP Registry as io.github.chrisryugj/kordoc.

One-click install for VS Code and Cursor via Claude Code plugin:

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

Quick start

CLI examples

Convert a single document:

npx kordoc document.hwpx -o document.md

Batch convert with parallel processing:

npx kordoc *.pdf --jobs 4 -d ./output

Extract specific pages as JSON:

npx kordoc document.pdf --format json --pages 1-3

OCR a scanned document:

npx kordoc scan.pdf --ocr -o scan.md

Generate a government document from Markdown:

npx kordoc generate report.md --preset report -o report.hwpx

Convert HWP to HWPX:

npx kordoc to-hwpx document.hwp -o document.hwpx npx kordoc to-hwpx ./old-docs # whole folder with subfolders

Fill a form template:

npx kordoc fill --template gian -j values.json -o draft.hwpx

Lint a document:

npx kordoc lint report.hwpx --gate --preset report

Use --jobs to convert files in parallel; this increases memory use. See batch conversion details for more options.

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)) ## Validation results Verification as of 4.24.40 (2026-11-03) across fixed corpora and reference criteria: - **HWPX parsing:** - Table structure match: 10,342 / 10,342 (100%) - Population: 2,424 documents with 10,342 tables - **HWP 5.x conversion:** - Paired-document table structure match: 100% - Attribute match: 99.21% (exact 69/232) - Text match: 264/264 - Population: 1,130 pairs with 4,315 tables - **PDF text extraction:** - Character recall: 99.885% - Precision: 99.682% - Reading order: 99.360% - Word-boundary F1: 99.103% - Population: 744 document pairs - **PDF tables:** - Detection: 99.83% - Structure match: 98.24% - Cell F1: 0.9919 - Population: 708 pairs with 2,331 tables - **OCR:** - Character error rate: 0.0239 - Character recall: 99.32% - Table structure: 34/66 - Population: 53 documents with 102 pages and 66 tables - **opendataloader-bench (200 PDF documents):** - Overall: 0.964 with defaults - Overall: 0.939 with OCR off Table structure, cell content, and visual fidelity are measured separately. See benchmark details for scope, exclusions, per-option scores, and reproduction instructions. ## Recent updates Latest release: 4.24.40 (2026-11-03) **4.24.40:** OCR repeated digits merged by condensed number fonts are re-read on horizontally stretched crops; stacked rows of label–value tables are expanded along label lines. **4.24.39:** OCR pages scanned sideways are turned upright; two-column layouts split by middle column rules or prose; outer label columns of open statistics tables; row expansion of large numeric tables. **4.24.38:** OCR headings on scanned and image pages; two-column reading order on pages with small label boxes; image formula OCR; to-hwpx engine that saves with Hancom Office itself. **4.24.37:** OCR tables with blank-separated columns inside ruled column groups; body rows without rules expanded; rows split under row spans; shaded header bands and first column edges; tables with header rows no longer read as charts. **4.24.36:** PDF word spacing in Hancom PDFs; spaces hidden by condensed tracking restored; commas overprinted on spaces stay attached; dotted dates keep their spaces; four-digit years split across lines are joined. See the [changelog](https://github.com/chrisryugj/kordoc/blob/main/CHANGELOG.md) for earlier releases and details. ## FAQ - **How do I convert an HWP or HWPX file to Markdown?:** `npx kordoc document.hwp -o document.md` 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. Set `KORDOC_OFFLINE=1` to block all outbound traffic. OCR runs on the local CPU with no API key required. - **Can I use it for RAG indexing?:** Use `--format chunks` to emit structure chunks with heading breadcrumbs plus standalone table chunks. Use `--table-format gfm` for tables without HTML. Python and Java SDKs are available for integration with those systems. - **Can I get OCR line boxes or use another model?:** Use `--ocr --ocr-lines --format json` to export line boxes and confidence. Use `--ocr-det` and `--ocr-det-long-side` to select the detector and resolution. ## Documentation - [Usage guide](https://github.com/chrisryugj/kordoc/blob/main/docs/usage-en.md): complete CLI, MCP tools, APIs, and format support - [Java SDK](https://github.com/chrisryugj/kordoc/blob/main/sdk/java/README.md) and [Python SDK](https://github.com/chrisryugj/kordoc/blob/main/sdk/python/README.md): parse from Java and Python systems - [Government-document generation](https://github.com/chrisryugj/kordoc/blob/main/docs/gongmunseo-engine-spec.md) and [Architecture](https://github.com/chrisryugj/kordoc/blob/main/docs/architecture.md) - [Offline deployment](https://github.com/chrisryugj/kordoc/blob/main/docs/offline-deployment.md): `KORDOC_OFFLINE=1` and file scope with `KORDOC_ROOT` - [Security policy](https://github.com/chrisryugj/kordoc/blob/main/SECURITY.md) · [MIT license](https://github.com/chrisryugj/kordoc/blob/main/LICENSE) · [Third-party notices](https://github.com/chrisryugj/kordoc/blob/main/NOTICE)