kordocBLOCK
모두 파싱해버리겠다 — HWP·HWPX·PDF·Office 문서를 Markdown으로. 양식 자동 채우기와 신구대조를 갖춘 CLI·MCP 서버 | Convert Korean documents (HWP, HWPX, PDF, Office) to Markdown — CLI and MCP server with form filling and diff
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
모두 파싱해버리겠다.
[](https://www.npmjs.com/package/kordoc) [](LICENSE)
대한민국에서 둘째가라면 서러울 문서지옥. 거기서 7년 버틴 공무원이 만들었습니다.
HWP 3.x·5.x, HWPX, HWPML, PDF, XLS·XLSX, DOCX, PPTX, PNG·JPG·WebP를 Markdown과 구조화 데이터로 변환합니다. 라이브러리·CLI·MCP 서버로 사용할 수 있습니다.
English · 상세 사용법 · 벤치마크 · 변경 이력
- 📊 PDF 공개 벤치 종합 0.963 — opendataloader-bench 200문서. 공개 12개 파서 비교 1위(2026-09-29 기록). 측정 조건
- 🇰🇷 한국 공문서 표 구조 100% — 원본 HWPX 2,424문서의 보이는 표 10,342개 전부 구조 일치. 4.21.22 검증
쓸모 있었다면 GitHub ⭐ 하나 눌러주세요. 다른 사람이 이 도구를 찾는 데 도움이 됩니다.
[](https://youtu.be/Q13GmgDcIw0)
▶ 클릭하면 유튜브에서 재생됩니다.
새 영상: kordoc 공개벤치 1위 마크 · 2026-09-27 · 1분 31초
설치
Node.js 20 이상 · macOS / Linux / Windows
npm install kordoc
CLI는 설치 없이 npx kordoc으로 실행할 수 있습니다. PDF·OCR 의존성은 기본 설치되며, --omit=optional로 제외하면 해당 기능이 제한됩니다.
AI 에이전트에 연결
npx -y kordoc setup
Claude Desktop·Claude Code·Cursor·Codex 등 설치된 클라이언트에 MCP를 등록합니다. 클라이언트를 재시작하면 파싱·비교·생성·렌더 등 17개 도구를 사용할 수 있습니다.
Claude Code 플러그인:
/plugin marketplace add chrisryugj/kordoc /plugin install kordoc@kordoc
수동 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 fill --template gian -j 값.json -o 기안문.hwpx
--jobs는 파일 단위 병렬 변환이며 메모리 사용도 늘어납니다. 병렬 변환 안내
보고서·계획서·개조식·서울방침은 # 제목 바로 뒤 인용문(> ...하고자 함)이 요약 상자가 됩니다(개조식은 표지가 있을 때(기본) 본문 첫 쪽 제목 상자 아래 — cover:false 면 첫 # 이 장 머리라 인용문은 ※ 참고). 보고 목적 한 문장(쉼표 허용) 3줄 이내로 쓰고, 넘거나 두 문장 이상이면 경고합니다. 업무보고는 > ▪ ... 인용문이 자리와 관계
4f5a1d8afa9fOBSERVED · 2026-10-11Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control.
claude mcp add kordoc -- npx -y [email protected] mcp
Exposed tools (17)
16 read · 1 write · 0 destructive.
| Tool | Risk | Description |
|---|---|---|
compare_documents | read | 두 한국 문서 파일을 비교하여 추가/삭제/변경된 블록을 표시합니다. 신구대조표 생성에 활용됩니다. 크로스 포맷(HWP↔HWPX) 비교 가능. |
crop_regions | read | HWPX·HWP 문서를 렌더해 표·이미지·문단·도형 영역을 페이지 이미지에서 잘라 파일로 저장합니다(render_document 와 같은 조판 엔진, 페이지 로컬 pt bbox 를 실배율로 환산). 표가 진짜 데이터표인지 조직도인지는 판단하지 않습니다(그건 extract_tables) — 렌더러가 아는 개체를 자를 뿐. 결과: output_dir/<유형>_<번호>_page_<쪽>.png + regions.json(id·유형·페이지·bbox pt). |
detect_format | read | 파일의 포맷을 매직 바이트와 컨테이너 내부 구조로 감지합니다 (hwpx, hwp, hwp3, hwpml, pdf, xls, xlsx, docx, pptx, image, unknown). |
extract_profile | read | 참조 HWPX 문서에서 표 서식 프로필(테두리·음영·열 너비·셀 글꼴)을 JSON으로 추출합니다. 추출한 프로필을 generate_document의 profile_path로 넘기면 원본 문서 없이 같은 표 서식을 재현합니다 — \ |
extract_tables | read | |
fill_form | read | 한국 서식 문서의 빈칸을 채워서 새 문서로 출력합니다. hwpx-preserve를 사용하면 원본 서식(테두리, 폰트, 병합 등)을 100% 유지합니다. HWPX 누름틀(CLICK_HERE) 필드는 이름으로 정확 매칭되어 우선 채워집니다. file_path 대신 template으로 내장 정부 표준 기안문 서식을 쓸 수 있습니다 — gian(일반기안문, 별지 제1호서식: 행정기관명·수신자·경유·제목·본문·붙임·발신명의·기안자·검토자·결재권자 등 23필드) / gian-simple(간이기안문, 별지 제2호서식: 내부결재용 13필드). |
generate_document | read | 마크다운을 HWPX 한글 문서로 생성합니다. \ |
parse_chunks | read | 문서를 RAG용 구조 청크 JSON으로 파싱합니다. 헤딩·개조식 위계(□○- / 1.·가.·1))가 breadcrumb 경로로 보존되고 표는 독립 청크로 나옵니다 — 임베딩·인덱싱 전처리용. 자르기(토큰 상한·오버랩)는 소비자 몫입니다. |
parse_document | read | 한국 문서 파일(HWP, HWPX, PDF, XLSX, DOCX)과 이미지(PNG/JPG/WebP)를 마크다운으로 변환합니다. 파일 경로를 입력하면 포맷을 자동 감지하여 텍스트를 추출합니다. 이미지는 OCR(내장 PP-OCRv5)이 자동 적용되고 표 괘선도 복원됩니다. |
parse_form | read | 한국 서식 문서에서 레이블-값 쌍을 구조화된 JSON으로 추출합니다. 양식/서식 문서에 최적화. |
parse_metadata | read | 문서의 메타데이터(제목, 작성자, 날짜 등)만 빠르게 추출합니다. 전체 파싱 없이 헤더/매니페스트만 읽습니다. |
parse_pages | read | 문서의 특정 페이지 범위만 파싱합니다. PDF와 한컴 저장본 HWP/HWPX는 실제 페이지 기준(metadata.pageMode=layout), 조판 캐시가 없는 생성 파일은 섹션 단위 근사(pageMode=section)입니다. |
parse_table | read | 문서에서 N번째 테이블만 추출합니다 (0-based index). 테이블이 없거나 인덱스 범위를 초과하면 오류를 반환합니다. |
patch_document | write | 원본 HWPX/HWP의 서식(글꼴·표·도장칸·이미지)을 1바이트도 건드리지 않고, 편집된 마크다운의 바뀐 텍스트만 제자리 치환해 새 문서로 출력합니다. parse_document로 얻은 마크다운을 수정해 넘기세요 — 양식 빈칸 채우기·문구 수정에 적합하며 한컴 한글에서 변조 경고 없이 열립니다. (블록 추가/삭제·표 구조 변경은 미지원, 미적용 항목은 결과에 보고) |
place_seal | read | 도장/서명 이미지를 앵커 문구(\ |
redact_document | read | |
render_document | read | HWPX·HWP 문서를 실제 조판 그대로 렌더해 PNG/JPEG 이미지로 응답하거나 SVG·HTML·PDF 파일로 저장합니다. generate_document·fill_form·patch_document·place_seal 결과물을 눈으로 확인하는 용도 — 생성/수정 후 이 도구로 렌더해 깨짐·잘림·배치를 검증하고 다시 고치는 루프를 권장합니다. 한컴 저장본(HWPX·HWP 모두)은 조판 캐시로 정확히, AI 생성본(캐시 없음)은 순수 조판 엔진(reflow)으로 렌더되며 후자는 한컴 실조판의 근사입니다 (참고용 미리보기). |
Trust audit
BLOCKgrade D · trust 69/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | WARN |
| L1 | Static analysis of the code | FAIL |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | PASS |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (5 observation(s))
- Network
- declared (9 observation(s))
- Shell
- declared (1 observation(s))
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (25)
hostname === "metadata.google.internal" ||
간이기안문_서식.hwpx
일반기안문_서식.hwpx
11111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111000000111111111111111111111111110000001111111111111111111111111100000
11111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111101111111111111111111111111011110000000111111111111111111110011110000001111111111111111111111111100001
11111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111000000000000000000001111111111110011111111111111111111111111111111111
11111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111101111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111
11111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111110011111111111111111111111111111100000000000000000000011111111111111
const jsonContent = readFileSync(jsonPath, "utf-8").replace(/^/, "")
raw = JSON.parse(text.replace(/^/, "")) // Windows 메모장·PowerShell 저장본의 UTF-8 BOM
dummy.hwpx
HWP3-password-123456.hwp
HWP5-nopassword-123456.hwpx
const sha1 = buf => createHash("sha1").update(buf).digest("hex")return createHash("sha1").update(buf).digest().subarray(0, 16)return createHash("sha1").update(data).digest("hex")/** 표준 보안 처리기 R2(RC4 40bit) 사용자 암호 PDF */
const rc4 = (key: Buffer, data: Buffer): Buffer => {new Error("EACCES: permission denied, open '/home/user/.ssh/id_rsa'"),wire_options({"file_path": "/etc/passwd"})for (const bad of [{ filePath: "/etc/passwd" }, { onProgress: 1 }, { nope: true }, { ocr: "auto" }, { pages: [0] },"/etc/passwd",
import { markdownToHwpx, placeSealHwpx } from "../../dist/index.js"import { assertNetworkAllowed } from "../../shared/offline.js"import { disableOrtTelemetry } from "../../ocr/runtime-env.js"Gates applied: no_behavioural_pass.
4f5a1d8afa9ffull audit observations/trust-audit/mcp-server/chrisryugj__kordoc.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-11 | 4f5a1d8afa9f | BLOCK | D | 69 | first audit |
Questions
What is the kordoc MCP server?
모두 파싱해버리겠다 — HWP·HWPX·PDF·Office 문서를 Markdown으로. 양식 자동 채우기와 신구대조를 갖춘 CLI·MCP 서버 | Convert Korean documents (HWP, HWPX, PDF, Office) to Markdown — CLI and MCP server with form filling and diff
What tools does kordoc expose?
17 in total: 16 read-only, 1 that write, and 0 that can delete or overwrite. Every one is listed on this page with its risk.
Is kordoc safe to connect to an agent?
No — not without reading the findings first. The audit graded it D (69/100) and found 1 critical or high issue in the source. Each one is listed on this page with the file and line it is on.
What credentials does kordoc need?
No credential environment variables were found in its source, so it appears to need none.
How does kordoc run?
It speaks stdio, so it runs as a local process your client starts. It is published on npm as kordoc at 4.21.22.
How current is this page?
The grade is for one exact copy of the source (4f5a1d8afa9f), read on 2026-10-11. The repository is watched and re-audited when it changes.