# kordoc

> Turns Korean HWP, HWPX, PDF and Office files into Markdown for people and AI agents

- Category: Retrieval & Knowledge (RAG) / Parsing & Ingestion
- Language: TypeScript
- Licence: MIT
- Repository: https://github.com/chrisryugj/kordoc
- Canonical page: https://ai-tldr.dev/tools/kordoc/
- Updated: 2026-10-11

## In short

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 sits in the Parsing & Ingestion category of the Retrieval & Knowledge (RAG) tools and is open-source, written in TypeScript and licensed MIT.

## 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.

1. Install the package

   PDF and OCR dependencies install by default; leaving them out with `--omit=optional` limits those features.

```bash
npm install kordoc
```

2. Convert documents from the command line

   Convert one file, a batch in parallel with `--jobs`, a page range as JSON, or a scanned PDF with OCR.

```bash
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
```

3. Generate and fill documents

   Turn Markdown into an HWPX report with a preset, or fill the built-in `gian` draft template from a JSON file of values.

```bash
npx kordoc generate report.md --preset report -o report.hwpx
npx kordoc fill --template gian -j values.json -o draft.hwpx
```

4. Parse from JavaScript or TypeScript

   `parse` detects the format and returns Markdown plus structured `blocks` and `metadata`; `markdownToHwpx` goes the other way.

```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)
}

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

5. Connect an AI agent over MCP

   `setup` registers the MCP server with installed clients such as Claude Desktop, Claude Code, Cursor and Codex; restart the client to get the tools. For manual registration, point the client at `npx -y kordoc mcp`.

```bash
npx -y kordoc setup

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

## 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

## Version history

- 2026-10-11 v4.21.23: Adds OCR of text inside images embedded in HWP and HWPX documents when `ocr: true` is set; default output is unchanged.