Kordoc
БесплатноПоддерживаетсяParse Korean documents (HWP3-5, HWPX, HWPML, PDF, XLS(X), DOCX) to Markdown — CLI + MCP server with lossless patch/roundtrip, form-filler, document diff, print
Описание
Parse Korean documents (HWP3-5, HWPX, HWPML, PDF, XLS(X), DOCX) to Markdown — CLI + MCP server with lossless patch/roundtrip, form-filler, document diff, print & layout-preserving SVG renderer
README
모두 파싱해버리겠다.
npm version npm downloads GitHub stars license MCP Registry
대한민국에서 둘째가라면 서러울 문서지옥. 거기서 7년 버틴 공무원이 만들었습니다.
한국 공문서를 AI가 읽고 쓸 수 있게 합니다. HWP 3.x·5.x, HWPX, HWPML, PDF, XLS·XLSX, DOCX, PPTX, 이미지(PNG·JPG·WebP·TIFF·GIF·BMP·AVIF·HEIC·PCX)를 Markdown과 구조화 데이터로 바꾸고, Markdown에서 HWPX·HWP 공문서를 만듭니다. 라이브러리·CLI·MCP 서버로 씁니다.
English · 상세 사용법 · 벤치마크 · 변경 이력

같은 법령 별표 한 건을 HWP·HWPX·PDF·스캔 이미지로 넣은 실제 출력입니다. 네 경우 모두 병합 칸(rowspan·colspan)을 같은 짜임의 표로 읽습니다. 스캔 이미지는 OCR이 자동으로 켜집니다.
- 📊 PDF 공개 벤치 종합 0.965: opendataloader-bench 200문서, 공개 리더보드(2026-09-29 기록) 12개 파서보다 높은 점수(4.24.50 측정). 측정 조건
- 🇰🇷 한국 공문서 표 구조 100%: 원본 HWPX 2,424문서의 보이는 표 10,342개 전부 구조 일치. 검증 결과
- 🧩 Claude 플러그인 디렉터리 게시: 설치 1,700건 이상(2026. 11. 14. 집계). 공식 MCP 레지스트리에도 등록돼 있습니다.
쓸모 있었다면 GitHub ⭐ 하나 눌러주세요. 다른 사람이 이 도구를 찾는 데 도움이 됩니다.
영상: 공개 벤치 측정 과정(2026-09-27 판, 1분 31초) · 양식 일괄 채우기 시연
목차: 설치 · 빠른 시작 · 주요 기능 · 검증 결과 · 최근 업데이트 · 자주 묻는 질문 · 문서·보안
설치
Node.js 20 이상 · macOS / Linux / Windows
npm install kordoc
CLI는 설치 없이 npx kordoc으로 실행합니다. PDF 글은 패키지에 든 wasm 엔진으로 읽습니다. OCR·그림 형식 변환·QR 읽기 의존성은 기본으로 설치되며, --omit=optional로 빼면 해당 기능이 제한됩니다.
AI 에이전트에 연결
| 쓰는 곳 | 방법 |
|---|---|
| Claude Desktop·Claude Code·Cursor·Codex 등 | npx -y kordoc setup: 설치된 클라이언트를 찾아 MCP를 등록합니다 |
| VS Code·Cursor | 아래 단추로 등록합니다 |
| Claude Code 플러그인 | /plugin marketplace add chrisryugj/kordoc 뒤 /plugin install kordoc@kordoc |
| Claude 앱 | 플러그인 디렉터리에서 kordoc을 찾아 설치합니다 |
| 그 밖의 MCP 클라이언트 | 공식 MCP 레지스트리 io.github.chrisryugj/kordoc 또는 수동 등록 |
클라이언트를 다시 시작하면 파싱·비교·생성·검수·렌더 등 22개 도구를 씁니다. 등록이 안 되면 수동 MCP 등록과 설치 문제 해결을 보세요.
빠른 시작
CLI
npx kordoc 문서.hwpx -o 문서.md
npx kordoc *.pdf --jobs 4 -d ./결과
npx kordoc 문서.pdf --format json --pages 1-3
npx kordoc 스캔본.pdf --ocr -o 스캔본.md
npx kordoc generate 보고서.md --preset 보고서 -o 보고서.hwpx
npx kordoc to-hwpx 문서.hwp -o 문서.hwpx
npx kordoc to-hwpx ./옛문서 # 폴더째(하위 폴더까지): 각 파일 옆에 .hwpx, 이미 있으면 건너뜀
npx kordoc 문서.pdf -o 문서.hwpx # PDF·DOCX 등도 읽은 내용으로 HWPX (그림 포함)
npx kordoc pack build 보고서1.hwpx 보고서2.hwpx 보고서3.hwpx --name 광양시 -o 광양시.kpack # 기관팩 (docs/agency-pack.md)
npx kordoc generate 새보고서.md --pack 광양시.kpack -o 새보고서.hwpx
npx kordoc fill --template gian -j 값.json -o 기안문.hwpx
npx kordoc lint 보고서.hwpx --gate --preset 보고서
--jobs는 파일 단위 병렬 변환이며 메모리 사용도 늘어납니다. 병렬 변환 안내
JavaScript / TypeScript
import { parse, markdownToHwpx } from "kordoc"
import { writeFile } from "node:fs/promises"
const result = await parse("문서.hwpx")
if (result.success) {
console.log(result.markdown)
// result.blocks: 구조화 데이터, result.metadata: 문서 정보
}
const hwpx = await markdownToHwpx("# 추진계획\n\n본문", {
gongmun: { preset: "보고서" },
})
await writeFile("보고서.hwpx", Buffer.from(hwpx))
파싱 옵션·API·양식·렌더 예제 · Python·Java에서는 Python SDK·Java SDK
주요 기능
- 읽기: 문서 → Markdown·IR·쪽별 본문·RAG 청크, 로컬 OCR(손글씨 인식 포함), 그림 속 QR 값(
--qr-codes), 그림 형식 통일(--image-format png|webp) - 비교·편집: 블록·셀 단위 비교, HWPX·HWP 서식 보존 패치, 견본 서식 그대로 새 내용 쓰기
- 작성: Markdown → HWPX·HWP(HWP는
npm install @rhwp/core뒤-o 문서.hwp), 공문서 프리셋·부서 서식 견본(--template)·보고서 PDF 모양 따르기(--layout), 목차 쪽 번호, 표·수식·차트 - 변환: HWP 5.x → HWPX 서식 그대로(글꼴·문단 모양·표·그림·도형·수식·머리말·각주·차트, 배포용·변경 추적 문서 포함). PDF·DOCX 등은
-o 문서.hwpx로 읽은 내용을 HWPX로 - 기관팩: 우리 기관 문서 몇 건으로 서식 묶음(
.kpack)을 만들어 그 서식대로 새 문서 작성 - 양식: 필드·누름틀 채우기, 표준 기안문 2종, 도장 날인
- 검수: 표기법·공공언어, 구성·AI 문체 게이트, 예산 산출근거 검산, 열린 문서 블록 단위 검수(
lint-blocks) - 보기·보안: HWPX·HWP 미리보기·영역 추출, 개인정보 마스킹
서식 보존 패치용 Markdown은 --keep-layout-tables로 추출합니다. 적용하지 못한 편집은 건너뛴 사유로 보고합니다. 서식 보존 편집 · CLI 전체
검증 결과
고정 코퍼스와 참조 기준으로 측정한 결과입니다. 측정판: 기본 4.22.14(2026-10-19) · 렌더 배치·별표 4.24.24(2026-10-30) · HWP → HWPX 변환 4.24.29(2026-10-31) · OCR 4.24.32(2026-11-01) · PDF 표 4.24.35(2026-11-01) · PDF 글·opendataloader-bench 기본값과 OCR 켬 4.24.50(2026-11-07) · KoOCR-Bench 4.24.68.
| 대상 | 규모 | 결과 |
|---|---|---|
| HWPX | 2,424문서 · 10,342표 | 표 구조 일치 10,342/10,342 · 100% |
| HWP 5.x ↔ HWPX | 1,130쌍 · 4,315표 | 짝 문서의 표 구조 일치 100% |
| HWP 5.x → HWPX 변환 |
한글 저장 짝 264쌍 (속성 대조 232쌍) | 속성 일치 99.21% · 완전 일치 69/232 · 글 264/264 · 한글 화면 대조 80문서 |
| PDF 글 | 744쌍 | 글자 재현율 99.887% · 정확도 99.685% · 읽기 순서 99.398% · 어절 F1 99.131% |
| PDF 표 | 708쌍 · 2,331표 | 표 탐지 99.83% · 구조 일치 98.24% · 칸 F1 0.9919 |
| HWPX 재조판 | 다중줄 25,187문단 (12개 폴더) | 모든 줄 시작 일치 24,941/25,187 · 99.02% |
| PDF 중첩표 (텍스트층) | 29문서 · 101표 | 구조·칸 내용 101/101 · 100% |
| 법령 별표 | 272건 · 346표 | HWP 346/346, PDF 343/346 · 99.13% |
| PDF 전체 | 1,911문서 중 1,729건 채점 | 글 커버리지 99.80% |
| OCR | 53문서 · 102쪽 · 65표 | CER 0.0237 · 글자 재현율 99.33% · 표 구조 일치 33/65 |
| KoOCR-Bench v2.0c (외부) | 공개 877쪽 (표·글·손글씨·순서) | 종합 기본값 0.906 · 표 0.916 · 손글씨 0.921 · 순서 0.914 · 제목 재현율 0.930 |
| opendataloader-bench | PDF 200문서 | 종합 기본값 0.965 · ocr: true 0.967 · OCR 끔 0.939 (4.22.14) |
| HWPX 렌더 배치 | 한컴 PDF 짝 1,565문서(쪽 수 일치 1,508) · 글 조각 111,480 · 그림 4,300 | 글 위치(±1.5pt) 106,904 · 95.9% · 그림 위치(±2pt) 4,213 · 98.0% |
표 구조 점수와 셀 내용·화면 재현은 별도 지표입니다. 중첩표 100%는 위 101표에 한정하며 전체 PDF·조판의 완전 일치를 뜻하지 않습니다. 채점 범위·제외 기준·옵션별 수치·재현 방법은 벤치마크 상세에 있습니다.
최근 업데이트
최신 배포: 4.25.2 · 2026-11-19
| 버전 | 바뀐 점 | 실측 변화 |
|---|---|---|
| 4.25.2 | parse-worker가 입력 파일을 비동기로 읽어, 큰 파일을 읽는 동안에도 워커가 신호와 출력을 처리합니다(#224). 백신이 수식 변환 파일을 잘못 잡을 때의 예외 등록 방법을 설치 문제 해결에 적었습니다(#223) |
150MB 입력에서 함수가 돌아오기까지 동기 구간 14ms → 0ms · 파서 출력 무변 |
| 4.25.1 | generate --layout을 --plain과 함께 주거나 MCP에서 프리셋 없이 layout_path를 주면 PDF 모양을 버리고 범용 HWPX를 만들던 것을, 이제 파일을 만들기 전에 오류로 알립니다(#217, @LimePencil) |
잘못된 두 조합은 PDF를 읽거나 파일을 쓰기 전에 멈춤(CLI·MCP 진입점 시험) · 파서·생성 엔진 무변 |
| 4.25.0 | measure로 PDF의 모양을 재고 generate --layout으로 보고서에 적용합니다. 보고서·계획서 목차에 쪽 번호를 넣고 Windows 한컴 자동화를 끌 수 있습니다 |
한컴에서 연 9쪽 견본의 장 4개와 붙임 쪽 번호가 모두 일치했습니다 |
| 4.24.83 | 첫 열이 「1)」「2)」 번호뿐인 테두리 없는 표가 각주 목록으로 판정돼 글로 풀리던 문제를 고쳤습니다(#214). 쪽 아래 번호 줄은 본문에 그 번호를 가리키는 작은 글씨 참조가 있을 때만 각주 목록으로 봅니다 | 점수 벤치 5,465문서·PDF 글 744·PDF 표 730·별표 544·ODL 200·OCR 56·견고성 54 문서별 변화 0 · KoOCR 877쪽 출력 그대로(0.90657) · 채점 코드 무변 |
| 4.24.82 | PDF 글층을 패키지에 든 wasm 엔진(hayro)으로 읽습니다. PDF를 읽으려고 따로 설치할 것이 없고(pdfjs-dist 빠짐), 큰 문서를 더 빨리, 메모리를 덜 쓰며 읽습니다. OCR 판정 3건(격자 표를 건너 묶인 표 후보·두 단 본문·분수 막대)도 고쳤습니다(#213, @VerifiedIdiot) |
자체 벤치 문서별 하락 0 (점수 5,465·PDF 글 744·PDF 표 730·별표 544·ODL 200·OCR 56) · ODL 1문서 nid 0.99441 → 0.99684 · KoOCR 0.90653 → 0.90657 · 큰 문서 13개 144~157초 → 95~98초, 최대 메모리 1.95~2.20GB → 1.15~1.24GB |
이전 버전과 상세 내용은 변경 이력에 있습니다.
자주 묻는 질문
Q. HWP·HWPX 파일을 Markdown으로 바꾸려면?
npx kordoc 문서.hwp -o 문서.md를 실행합니다. 한컴오피스 없이 파일을 직접 읽으며, 여러 파일은 npx kordoc *.hwpx -d ./output으로 함께 바꿉니다.
Q. Claude·Cursor 같은 AI가 한글 문서를 읽게 하려면?
npx -y kordoc setup으로 MCP를 등록하면 AI가 파일 경로만 받아 HWP·PDF·엑셀을 읽고, 비교하고, 양식을 채웁니다.
Q. 인터넷이 막힌 폐쇄망에서도 되나요?
됩니다. KORDOC_OFFLINE=1이 외부 통신을 모두 막고, OCR도 API 키 없이 로컬 CPU에서 돕니다. 폐쇄망 설치
Q. RAG 색인용으로 쓸 수 있나요?
--format chunks가 제목 경로를 붙인 구조 청크와 독립 표 청크를 냅니다. 표를 HTML 없이 받으려면 --table-format gfm(API는 tableFormat: "gfm")을 씁니다. Python·Java에서는 Python SDK·Java SDK로 부릅니다.
Q. OCR 줄 좌표나 다른 모델이 필요하면?
--ocr --ocr-lines --format json이 줄별 상자·신뢰도를 내고, --ocr-det·--ocr-det-long-side로 검출 모델과 해상도를, --ocr-rec handwriting|auto로 손글씨 인식 모델을 고릅니다. OCR 줄·모델 선택
문서·보안
- 상세 사용법: 전체 CLI·MCP 도구·API·지원 포맷
- Java SDK · Python SDK: 상주 엔진 워커로 Java·Python 시스템에서 파싱 (워커 프로토콜)
- 공문서 생성 가이드 · 아키텍처
- 폐쇄망 설치:
KORDOC_OFFLINE=1, MCP 접근 범위KORDOC_ROOT - gVisor 샌드박스: 파서를 gVisor 안에서 실행해 호스트 보호(Linux,
KORDOC_SANDBOX=gvisor·docker --runtime=runsc) - 보안 정책 · 라이선스 MIT · 오픈소스 고지
Star History
만든 사람
대한민국 지방공무원. 광진구청에서 7년간 HWP 파일과 싸우다가 이걸 만들었습니다. 5개 공공 프로젝트에서 수천 건의 실제 관공서 문서를 파싱하며 검증했습니다.
라이선스: MIT
Установить Kordoc в Claude Desktop, Claude Code, Cursor
unyly install kordocСтавит в Claude Desktop, Claude Code, Cursor и VS Code — сам разбирается с npx, uvx и сборкой из исходников.
Впервые? Поставь CLI: curl -fsSL https://unyly.org/install | sh
Или настроить вручную
Выполни в терминале:
claude mcp add kordoc --env ONNXRUNTIME_NODE_INSTALL="" -- npx -y kordocПошаговые гайды: как установить Kordoc
FAQ
Kordoc MCP бесплатный?
Да, Kordoc MCP бесплатный — установка в пару кликов через Unyly без оплаты.
Нужен ли API-ключ для Kordoc?
Да, требуются переменные окружения: ONNXRUNTIME_NODE_INSTALL. Unyly подставит их в конфиг при установке.
Kordoc — hosted или self-hosted?
Self-hosted: сервер запускается локально на твоей машине командой из раздела установки.
Как установить Kordoc в Claude Desktop, Claude Code или Cursor?
Открой Kordoc на unyly.org, выбери вкладку своего клиента (Claude Desktop, Claude Code, Cursor) и нажми Install — конфиг сгенерируется автоматически, без правки JSON.
Изменения
Версии и запрашиваемые доступы со временем.
- Новая версия опубликована
- Новая версия опубликована
- Новая версия опубликована
- Новая версия опубликована
- Новая версия опубликована
- Новая версия опубликована
- Новая версия опубликована
- Новая версия опубликована
Похожие MCP
Playwright
Browser automation, scraping, screenshots
автор: MicrosoftPuppeteer
Browser automation and web scraping.
автор: modelcontextprotocolGarmin Connect
An MCP server for Garmin Connect that provides access to fitness activities, health statistics, and sleep data by routing requests through a headless browser to
автор: etweisbergHiggsfield Unlimited
MCP server for Higgsfield AI that enables unlimited-mode image, video, audio generation, uploads, and job management via multiple parallel accounts, using brows
автор: nukIeeropentabs-dev/opentabs
Plugin-based server and Chrome extension that gives AI agents access to web apps through your authenticated browser session, with a plugin SDK.
автор: opentabs-devhlydecker/ucsc-genome-mcp
Interact with the UCSC Genome Browser API to find genomes, chromosomes and more.
автор: hlydecker34892002/bilibili-mcp-js
Search Bilibili content, with LangChain integration examples.
автор: 34892002achiya-automation/safari-mcp
Native Safari browser automation without a Chrome dependency.
автор: achiya-automationagent-infra/mcp-server-browser
Browser automation using Puppeteer, supporting local and remote browser connections.
автор: bytedanceaparajithn/agent-scraper-mcp
Web scraping: clean content extraction, CSS-selector scraping, Playwright screenshots, link and metadata extraction, and Google search.
автор: aparajithnCompare Kordoc with
Не уверен что выбрать?
Найди свой стек за 60 секунд
Автор?
Embed-бейдж для README
Похожее
Все в категории browse
