kordoc은 한국 공공·행정 문서에서 자주 만나는 HWP, HWPX, HWPML, PDF, DOCX, XLSX, 이미지 파일을 파싱·비교·생성·수정하는 CLI와 MCP 서버다. 단순 텍스트 추출을 넘어 표 복원, OCR, 양식 채움, 원본 서식 보존 patch, HWPX 생성, 렌더 검증까지 다룬다.
왜 중요하다
한국 업무 환경에서는 HWP/HWPX와 복잡한 공문서 표가 여전히 핵심 문서 형식이다. 일반 PDF·DOCX 파서나 LLM 입력 변환기만으로는 병합 표, 신구조문대비표, 결재란, 공문서 항목부호, 도장·서명 위치를 제대로 처리하기 어렵다. kordoc은 이 문제를 AI 에이전트가 다룰 수 있는 Markdown, JSON chunk, 렌더 이미지, HWPX 출력으로 연결한다.
주요 기능
| 기능 | 설명 |
|---|---|
| 문서 파싱 | HWP3/5, HWPX, HWPML, PDF, XLS/XLSX, DOCX, PNG/JPG/WebP |
| 표 복원 | 병합 셀, 무괘선 PDF 표, 신구조문대비표를 Markdown table로 복원 |
| OCR | PP-OCRv5 Korean 기반 로컬 OCR, 스캔본 표 감지 |
| 양식 채움 | 신청서·보고서 템플릿의 빈칸을 원본 서식 유지하며 채움 |
| patch | 원본 서식을 유지하고 문단·표 셀 텍스트만 교체 |
| 공문서 생성 | 기안문, 개조식 보고서, 공고문, 보도자료 preset |
| 렌더 검증 | HWPX를 SVG/PNG로 렌더해 에이전트가 결과를 확인 |
| MCP 연동 | Claude Desktop, Cursor, Claude Code, Codex 등에서 도구 호출 |
설치
npx -y kordoc setup마법사는 Claude Desktop, Cursor, Claude Code, Windsurf, VS Code, Gemini CLI, Zed, Codex 등을 감지해 MCP 설정을 패치한다. CLI만 쓰려면 설치 없이 npx kordoc <파일> 형식으로 실행할 수 있다.
Claude Code 플러그인 형태로도 쓸 수 있다.
/plugin marketplace add chrisryugj/kordoc
/plugin install kordoc@kordoc에이전트 워크플로
parse_document로 HWP/HWPX/PDF를 Markdown 또는 structured chunk로 읽는다.- LLM이 문서 내용을 요약, 비교, 수정안 작성, 개인정보 마스킹 계획을 세운다.
fill_form,patch_document,generate_document로 결과물을 만든다.render_document로 PNG를 받아 레이아웃이 깨졌는지 눈으로 확인한다.- 필요한 경우 다시 patch하고 렌더를 반복한다.
이 루프는 officecli와 비슷하게 “에이전트가 문서를 만들었다고 말하는 것”이 아니라 실제 렌더 결과를 보고 수정하게 만드는 데 초점이 있다.
언제 쓰면 좋은가
- 한국 공공기관, 학교, 연구기관, 기업 행정팀의 HWP/HWPX 문서를 자동 처리한다.
- 공문서 양식 채움, 신구대조표 분석, 개인정보 마스킹, 보도자료·공고문 초안 생성이 필요하다.
- PDF나 스캔 이미지 안의 복잡한 표를 RAG용 Markdown/JSON chunk로 바꾸고 싶다.
관련 문서
- officecli — Office 파일을 AI 에이전트가 읽고 고치는 오피스 CLI
- mcp — 에이전트와 외부 시스템을 연결하는 표준 프로토콜
- data-agent-correctness-layer — 에이전트 산출물 검증 레이어
참고 자료
- chrisryugj/kordoc — GitHub 공식 저장소