kordoc

// Overview

kordoc converts Korean documents to Markdown and structured data. It reads HWP 3.x and 5.x, HWPX and HWPML (the Hancom word-processor formats used across Korean government), plus PDF, XLS/XLSX, DOCX, PPTX and PNG/JPG/WebP images. It parses the files directly, with no copy of Hancom Office needed, and runs as a JavaScript/TypeScript library, a command-line tool or an MCP server. Its author is a Korean local civil servant who built it after seven years of handling HWP files at the Gwangjin-gu District Office in Seoul.

Reading is only part of it. kordoc can diff two documents block by block or cell by cell (across formats), patch edited Markdown back into the original HWPX or HWP with the formatting kept, generate HWPX from Markdown with government-document presets, fill form fields and the two standard draft templates, place a seal image, render HWPX/HWP pages to images, and mask personal information. For RAG it emits structure chunks with heading breadcrumbs plus standalone table chunks, and can write every table as a plain GFM pipe table. OCR for scanned pages runs on the local CPU with no API key.

The project publishes its own measurements in its benchmark docs: on the external opendataloader-bench set of 200 PDFs it reports an overall score of 0.963 with default settings, and it reports a 100% table-structure match on 10,342 tables from 2,424 original HWPX documents. It is written in TypeScript, needs Node.js 20 or later on macOS, Linux or Windows, ships Python and Java SDKs that drive a resident engine worker, and is MIT-licensed. Setting `KORDOC_OFFLINE=1` blocks all outbound traffic for air-gapped networks.

// What it does

• Parses HWP 3.x/5.x, HWPX, HWPML, PDF, XLS/XLSX, DOCX, PPTX and images to Markdown, an IR of blocks and per-page text
• MCP server with 17 tools (parse, compare, fill forms, patch, generate, render, redact and more), registered in Claude Desktop, Claude Code, Cursor or Codex by `npx -y kordoc setup`
• Format-preserving round trip: diff two documents, then patch edited Markdown back into the original HWPX or HWP
• Generates HWPX from Markdown with government-document presets, tables, equations and charts, and fills form fields and standard draft templates
• RAG output with `--format chunks` (heading breadcrumbs plus standalone table chunks) and `--table-format gfm` for tables without HTML
• Local CPU OCR for scanned PDFs and images, and an offline mode (`KORDOC_OFFLINE=1`) for air-gapped networks

// Getting started

kordoc needs Node.js 20 or later. You can run the CLI with npx without installing anything, add it to a project as a library, or register it as an MCP server so an AI agent can read and edit documents from a file path.

npm install kordoc

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

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

const result = await parse("document.hwpx")
if (result.success) {
  console.log(result.markdown)
}

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

npx -y kordoc setup

# or register manually, e.g. in Codex
codex mcp add kordoc -- npx -y kordoc mcp

Commands and code are distilled from the project's own documentation — always check the official repo for the latest.

// When to use it

• Let Claude, Cursor or another MCP client read, compare and fill Korean HWP, PDF and Excel files
• Index Korean government and enterprise documents for RAG with heading-aware chunks and plain GFM tables
• Bulk-convert archives of HWP and HWPX files to Markdown without Hancom Office
• Draft official documents in Markdown and export them as formatted HWPX, or fill standard forms from JSON

// How kordoc compares

kordoc alongside other open-source parsing & ingestion tools AI/TLDR tracks, ranked by GitHub stars.