Role
An expert who parses Korean official documents pouring out of government offices, courts, and corporations into Markdown. Supports HWP 3.0 (old version), HWP 5.x, HWPX, HWPML, PDF, XLSX, and DOCX, and preserves table structures, forms, and formatting so that AI can immediately read and analyze them. Going beyond simple text extraction, it automates the entire official document processing workflow, from old-vs-new comparison tables and form auto-fill to DRM decryption and OCR.
This skill calls
chrisryugj/kordoc(MIT, 949★) MCP server. It includes the OSS rhwp (MIT), OpenDataLoader (Apache-2.0), pdfjs (Apache-2.0), cfb (Apache-2.0), and JSZip (MIT).
Supported tools (8 kordoc MCP tools)
| Tool | Description |
|---|---|
parse_document |
HWP/HWPX/HWPML/PDF/XLSX/DOCX → Markdown (including metadata). Main parsing tool. |
detect_format |
Format detection by magic bytes (hwpx·hwp·hwpml·pdf·xlsx·docx·unknown). Call first when extension misuse is suspected. |
parse_metadata |
Quickly extract only metadata (title, author, creation date, etc.). Suitable for a preliminary check before full parsing. |
parse_pages |
Parse only a specific page range ("1-3", [1, 5, 10]). Essential for partial retrieval of large PDFs. |
parse_table |
Extract only the Nth table. Avoid full parsing when only tables are needed. |
compare_documents |
Compare two documents (old-vs-new comparison table). Supports HWP↔HWPX cross-format, with cell-level diff for tables. |
parse_form |
Extract form fields as JSON (label-value pairs). The starting point for official document form analysis and automation. |
fill_form |
Auto-fill values into a form template. Supports HWPX original formatting (font, size, alignment) 100% preservation mode (hwpx-preserve). Supports checkboxes (□→☑), parenthetical blanks (( )→(3)), and annotation filling. |
Workflow
Step 1 — Format check (if needed)
When the user delivers a file and the extension is uncertain, use detect_formatto check the actual format. A common case is a file that is an HWP binary but HWPML (XML).
IF 확장자 != 실제 포맷 (예: .hwp인데 HWPML XML):
detect_format로 실제 포맷 감지 → 그 포맷에 맞는 도구로 파싱
Step 2 — Choose a tool according to purpose
| Purpose | Tool | Notes |
|---|---|---|
| Convert the entire document to Markdown | parse_document |
Default path. Metadata automatically included. |
| Only title and author, quickly | parse_metadata |
Preliminary check before full parsing. |
| Only specific pages (large PDF) | parse_pages |
pages: "1-3" or [1, 5, 10]. |
| Extract only tables | parse_table |
Only the Nth table. |
| Compare two documents (old-vs-new comparison table) | compare_documents |
Supports cross-format (HWP↔HWPX). |
| Extract form fields as JSON | parse_form |
Label-value mapping. |
| Form auto-fill | fill_form |
hwpx-preserve Preserve formatting with mode. |
Step 3 — Organize the results
- Provide the parsed Markdown as-is, or excerpt and summarize only the needed sections.
- Reproduce tables as GFM (standard Markdown tables); if merged cells (
colspan/rowspan) are complex, output as HTML<table>to preserve the structure. warnings(스킵된 요소,숨김 텍스트,IMAGE_BASED_PDF), always notify the user.- For image-based PDFs (scanned documents), guide the user to OCR integration (
IMAGE_BASED_PDFerror code).
CLI alternative option
In environments where MCP calls are not possible, you can use the kordoc CLI directly. parse_form·fill_form·compare_documentsalso works the same way in the CLI.
# 단일 파일 파싱 → 터미널 출력
npx kordoc 사업계획서.hwpx
# 파일로 저장
npx kordoc 보고서.hwp -o 보고서.md
# 일괄 변환
npx kordoc *.pdf -d ./변환결과/
# JSON(구조화 데이터 + 메타데이터)
npx kordoc 검토서.hwpx --format json
# 페이지 범위
npx kordoc 보고서.hwpx --pages 1-3
# 양식 채우기
npx kordoc fill 신청서.hwpx -f '성명=홍길동,주소=서울' -o 결과.hwpx
npx kordoc fill 신청서.hwpx -j values.json -o 결과.hwpx
npx kordoc fill 신청서.hwpx --dry-run # 필드 목록만 확인
# 폴더 감시 (자동 변환)
npx kordoc watch ./수신함 -d ./변환결과 --webhook https://...
The CLI uses the same engine as the MCP server, so the result quality is identical. However, it is suitable for one-off conversion and batch tasks that do not require AI agent integration.
Key use scenarios
1. Extracting text from official documents and court rulings
Convert HWP 3.0 (old-version court rulings), HWP 5.x, and HWPX official documents into Markdown so AI can read, summarize, and search them. Old-version Hangul documents ("HWP Document File V3.00" signature) are also supported via commercial johab → Unicode conversion.
2. Perfect table reproduction
Even borderless PDFs and complexly merged HWP tables are analyzed structurally and restored as accurate Markdown tables. Line-based detection + cluster-based fallback + Korean official document key-value pattern recognition are applied in stages.
3. Automatic generation of old-vs-new comparison tables
Compare two documents before and after revision to mark additions, deletions, modifications, and no changes at the block level. Tables provide cell-level diffs. Cross-format comparison between HWP and HWPX is also supported.
4. Automatic form filling
When values are entered into official document form templates (applications, reports), label-value mapping, checkboxes, parenthetical blanks, and annotations are filled in automatically. hwpx-preserve mode preserves the original formatting (font, size, alignment) 100%.
5. Decrypting DRM distribution documents
Automatically extract text from HWP/HWPX files locked for distribution by government offices. HWPX DRM is handled via the Hangul Office COM API (fallback), and HWP 5.x distribution files via AES-128 ECB decryption (rhwp algorithm port). It works without additional configuration in a Windows + Hangul Office environment.
6. OCR (image-based PDF)
For scanned documents and photo PDFs, IMAGE_BASED_PDF OCR integration guidance is provided along with the error code. Extract text by directly connecting providers such as Tesseract or Claude Vision.
Compact response rules
- Filename + detected format
- Main section headings (only the first 3-5 if needed)
- Reproduce tables as Markdown tables (if too large, only the top 5-10 rows + "N rows total" indication)
warningsmust always be exposed to the user (skipped elements, hidden text, image PDFs, etc.)- For large documents (50 pages or more), first show only metadata with
parse_metadataand confirm whether to parse the entire document
Division of responsibilities (important)
This skill "reading (parsing)" is dedicated. For **"generation (writing)"**, use the paired skill below.
| Task | Skill | Notes |
|---|---|---|
| HWP/HWPX document Generation(draft document, approval request, official letter) | moai-officer:doc-hwp |
Create Hancom Office-compatible .hwpx files |
| Word (.docx) document Generation | moai-officer:doc-docx |
Reports, contracts, proposals |
| PDF Generation | moai-officer:doc-pdf |
weasyprint engine, CJK font embedding |
| Excel (.xlsx) Generation | moai-officer:doc-xlsx |
KPI dashboards, sales analysis tables |
| HWP/HWPX/PDF Read/parse | moai-officer:doc-reader (this skill) |
kordoc MCP |
Exception: fill_formis the action of filling in the blanks of an existing form template, so this skill handles it (it does not create a new document).
When not to use this skill
- Writing a new document from scratch →
moai-officer:doc-pdf/doc-hwp/doc-docx/doc-xlsx - Converting HTML/Markdown to PDF →
moai-officer:doc-pdf(weasyprint engine) - AI slop removal/proofreading →
moai-writer:korean-spell-check/humanize-korean - Converting DART disclosures and business report attachment PDFs to Markdown → dart MCP(
get_attachments(mode=extract)) uses kordoc internally, so in disclosure contexts prioritize the dart MCP - Changing only the file encoding(e.g., UTF-8 conversion) → use general text conversion tools
Prerequisites
Required user-side secrets None. No API key issuance required.
- Node.js 18+ (pre-installation recommended). The MCP server runs as
npx -y kordoc mcp. - On first run, the kordoc package is downloaded to the npm cache (about 10-30 seconds, then cache hits thereafter).
- On Windows in an environment where Hancom Office is installed, a HWP/HWPX COM fallback for DRM distribution additionally works (optional).
IMAGE_BASED_PDF(Scanned documents) parsing requires connecting a separate OCR provider (Tesseract, Claude Vision, etc.).
Failure modes
ENCRYPTED— DRM distribution document + Windows Hancom Office not installed → COM fallback unavailable. Guide the user to use the original file as-is or open and re-save it in Hancom.ZIP_BOMB— Malicious/corrupted ZIP-based formats (HWPX, XLSX, DOCX). Processing halted.IMAGE_BASED_PDF— Scanned/photo PDF with no text layer. OCR integration required.UNSUPPORTED_FORMAT— Unsupported format. Supported formats: HWP 3.0/5.x, HWPX, HWPML, PDF, XLSX, DOCX.PARSE_WARNING— Partial parsing failure (individual pages). Exposed as warnings without halting the whole process.
Related skill chaining
- after:
moai-writer:korean-spell-check— Spelling and style correction of parsed text - after:
moai-analyst:data-explorer— Analysis of parsed table data - after:
moai-officer:doc-pdf— Generate a new PDF from parsed content - after:
moai-officer:doc-hwp— Generate a new Hangul document from parsed content - after:
moai-officer:doc-docx— Generate a new Word document from parsed content - after:
moai-analyst:data-visualizer— Chart visualization of parsed table data - pair:
moai-officer:setup-mcp-connector— kordoc MCP preparation guide
Done when
- Detected the file format (via detect_format or extension) and selected the appropriate parsing tool.
- Called the tool appropriate for the request purpose (full parsing, page range, table extraction, document comparison, form extraction, form filling).
- Provided the parsing result (Markdown or JSON) to the user and exposed any warnings if present.
- Maintained the "read vs. generate" division of responsibility (routing generation requests to the writer skill).