kordoc 소개
관공서와 기업에서 오가는 한국 문서는 아래아한글(HWP·HWPX), PDF, 엑셀, 워드처럼 형식이 제각각이고, 특히 HWP 계열은 구조가 복잡해 프로그램으로 내용을 꺼내기가 까다롭습니다. 그래서 LLM에게 이런 문서를 읽히거나 검색·요약에 쓰려면, 먼저 사람이 열어서 복사·붙여넣기로 옮기는 수작업이 끼어들곤 합니다. kordoc은 바로 이 지점을 자동화하기 위해 만들어진 문서 처리 도구입니다.
kordoc은 HWP 3.x/5.x, HWPX, HWPML, PDF, XLS, XLSX, DOCX와 PNG/JPG/WebP 이미지까지 받아 마크다운으로 변환 하고, 반대로 마크다운을 다시 한글 문서(HWPX)로 되돌리는 기능을 함께 제공합니다. 명령줄 도구(CLI)로도 쓸 수 있고, MCP(Model Context Protocol) 서버 로 등록하면 Claude나 Cursor 같은 AI 클라이언트가 문서를 직접 읽고 쓸 수 있습니다. 행정 문서를 오래 다뤄 온 개발자가 만든 도구로, 실제 관공서 문서 수천 건으로 검증했다고 밝히고 있습니다.
이 글에서는 kordoc이 어떤 문서를 어떻게 처리하는지, AI 에이전트와 어떻게 연동되는지, 그리고 설치와 CLI 사용법을 정리합니다. kordoc은 TypeScript로 작성되었고 npm 패키지 kordoc 으로 배포되며, Node.js 18 이상 환경에서 동작합니다.
kordoc이 다루는 문서와 처리 흐름
kordoc의 출발점은 다양한 문서를 AI가 읽기 좋은 마크다운으로 바꾸는 파싱 입니다. 선이 없는 PDF 표나 복잡하게 병합된 HWP 표도 구조를 분석해 마크다운 테이블로 복원하고, 법령 개정안의 신구조문대비표처럼 까다로운 표도 대상으로 삼습니다. 스캔본이나 이미지처럼 텍스트층이 없는 경우에는 내장 OCR이 자동으로 동작하는데, 한국어 PP-OCRv5 모델(약 18MB)을 첫 사용 시 내려받아 API 키 없이 로컬에서 추론합니다.
RAG 파이프라인을 위한 배려도 있습니다. --format chunks 옵션은 헤딩과 개조식 항목의 위계를 breadcrumb 경로로 보존한 구조 청크(JSON)를 만들고, 표는 독립 청크로 분리합니다. 아래 그림은 입력 문서에서 마크다운·청크를 거쳐 AI 에이전트로, 다시 원본 서식을 보존한 문서로 되돌아오는 kordoc의 전체 흐름을 정리한 것입니다.
kordoc의 AI 에이전트 연동 (MCP)
kordoc은 MCP 서버를 내장하고 있어, AI 클라이언트가 문서 도구를 직접 호출하도록 연결할 수 있습니다. 가장 간단한 방법은 대화형 설치 마법사입니다.
npx -y kordoc setup
이 명령은 설치된 AI 클라이언트(Claude Desktop, Cursor, Claude Code, Windsurf, VS Code, Gemini CLI, Zed, Codex 등)를 감지해 설정 파일을 자동으로 패치합니다. 설정 파일을 직접 편집하려면 다음과 같이 등록합니다.
{
"mcpServers": {
"kordoc": {
"command": "npx",
"args": ["-y", "kordoc", "mcp"]
}
}
}
등록 후 재시작하면 문서 도구가 활성화됩니다. 대표적인 도구는 다음과 같습니다.
| 도구 | 설명 |
|---|---|
parse_document |
HWP/HWPX/PDF/XLSX/DOCX를 마크다운으로 변환 |
parse_chunks |
RAG용 구조 청크(JSON) 추출 (헤딩 위계 보존, 표는 독립 청크) |
compare_documents |
두 문서를 비교해 바뀐 부분을 분석 (크로스 포맷) |
fill_form |
양식 템플릿의 빈칸을 원본 서식 보존한 채 채우기 |
patch_document |
편집된 마크다운을 원본 HWPX/HWP에 서식 보존 반영 |
generate_document |
마크다운(표·수식·차트 포함)을 HWPX로 생성 |
render_document |
HWPX를 조판 그대로 PNG/SVG로 렌더링 |
redact_document |
개인정보를 탐지해 서식 보존 마스킹 |
이 외에 포맷 감지, 특정 페이지·표 추출, 양식 필드 추출, 도장 날인 등을 포함해 총 15개의 도구가 제공됩니다. Claude Code에서는 MCP 등록 대신 플러그인으로도 쓸 수 있는데, /plugin marketplace add chrisryugj/kordoc 로 마켓플레이스를 추가한 뒤 설치하면 .hwp/.hwpx 언급이나 공문서 생성 요청에 kordoc 스킬이 자동으로 활성화됩니다.
kordoc 설치와 CLI 사용법
AI 연동 없이 명령줄에서만 쓴다면 별도 설치 없이 npx 로 바로 실행할 수 있습니다.
npx kordoc 사업계획서.hwpx # 터미널 출력
npx kordoc 보고서.hwp -o 보고서.md # 파일 저장
npx kordoc *.pdf -d ./변환결과/ # 일괄 변환
npx kordoc 검토서.hwpx --format json # JSON (blocks + metadata)
npx kordoc fill 신청서.hwpx -f '성명=홍길동' -o 결과.hwpx # 양식 채우기
npx kordoc generate 보고서.md -o 보고서.hwpx --preset 보고서 # 마크다운 → HWPX
npx kordoc patch 원본.hwpx 편집.md -o 반영.hwpx # 서식 보존 라운드트립
아래는 kordoc으로 문서를 변환하는 실제 동작 모습입니다.
kordoc의 서식 보존 라운드트립
kordoc에서 눈에 띄는 기능은 원본 서식을 보존하는 라운드트립 입니다. patchHwpx(HWPX)와 patchHwp(HWP 5.x 바이너리)는 변환한 마크다운을 편집해 넘기면 바뀐 문단이나 표 셀의 텍스트만 원본 안에서 교체하고, 나머지 서식은 그대로 둡니다. 저자들은 실측 공문서 코퍼스 324건을 자기참조로 채점한 자체 벤치마크에서 HWPX 텍스트 재현율 99.998%, 표 구조 정확 일치 100%(1,421개 표 기준)를 보고합니다. 이 수치는 저장소의 bench/ 채점기로 재현할 수 있습니다.
반대 방향으로는 마크다운을 한국 행정 공문서 표준 서식의 HWPX로 생성할 수 있습니다. 항목부호 자동화(1. 가. 1) 가) …), 둘째 줄 내어쓰기, 기안문·보고서·공고문 프리셋을 지원하며, 이때 근거로 삼은 표준 문법은 저장소의 docs/gongmunseo-reference.md 문서에 정리되어 있습니다.
kordoc의 라이선스
kordoc은 MIT 라이선스로 공개되어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다. 다만 내부적으로 HWP5 복호화(rhwp, MIT), PDF 표 감지(OpenDataLoader PDF, Apache 2.0), OLE2 컨테이너 파싱(cfb, Apache 2.0), PDF 텍스트 추출(pdfjs-dist, Apache 2.0) 등 여러 오픈소스 구성요소를 포함하므로, 재배포 시에는 저장소의 NOTICE 파일에 정리된 각 구성요소의 라이선스를 함께 확인하는 것이 좋습니다.
kordoc 홈페이지 (npm)
https://www.npmjs.com/package/kordoc
kordoc 프로젝트 GitHub 저장소
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! 텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다. 
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 