사용 안내
hunsdoc 0.1.1 기준
hunsdoc은 명령줄 도구 hunsdoc과 MCP 서버 hunsdoc-mcp 두 실행 파일로 이뤄져 있습니다. 이 안내는 자주 쓰는 사용법을 모았습니다. 옵션 전체는 hunsdoc --help와 hunsdoc <명령> --help에서 볼 수 있습니다.
1. 설치하기
다운로드 페이지에서 운영체제에 맞는 압축 파일을 받아 풀고, hunsdoc과 hunsdoc-mcp를 PATH에 두면 됩니다. 런타임 설치가 필요 없는 정적 실행 파일입니다.
# 예: Linux x86-64
curl -LO https://levelupsoft.com/hunsdoc/download/hunsdoc_0.1.1_linux_amd64.tar.gz
tar -xzf hunsdoc_0.1.1_linux_amd64.tar.gz
sudo install hunsdoc hunsdoc-mcp /usr/local/bin/
hunsdoc --version
macOS에서 “확인되지 않은 개발자” 경고가 뜨면 xattr -d com.apple.quarantine hunsdoc hunsdoc-mcp를 실행하세요. Windows 설치와 SHA-256 확인 방법은 다운로드 페이지에 있습니다.
소스 코드가 있다면 Go 1.26.6 이상으로 직접 빌드할 수도 있습니다.
go build -o hunsdoc ./cmd/hunsdoc go build -o hunsdoc-mcp ./cmd/hunsdoc-mcp
2. 문서 변환하기
파일을 주면 Markdown이 표준 출력으로 나옵니다. 진행 메시지와 경고는 표준 오류로 가므로 결과를 그대로 다른 프로그램에 넘길 수 있습니다. 한글(HWP 3.x·5.x·HWPX·HWPML), PDF, MS Office(워드 DOCX·엑셀 XLSX·XLS), 이미지(PNG·JPG·WebP, OCR 필요)를 같은 방법으로 넣습니다. 형식은 확장자가 아니라 파일 내용으로 판별합니다.
# 기본 — Markdown이 화면(stdout)으로 hunsdoc 보고서.hwpx # 파일로 저장 / 여러 파일을 폴더로 hunsdoc 보고서.pdf -o 보고서.md hunsdoc 문서들/*.hwp -d 결과/ # 워드·엑셀 — 엑셀은 시트마다 제목과 표, 수식 칸은 저장된 계산 결과로 hunsdoc 보고서.docx -o 보고서.md hunsdoc 예산.xlsx -o 예산.md # 일부 쪽만, 암호 문서 hunsdoc 편람.pdf -p 3-8 hunsdoc 기밀.hwp --password 123456
| 자주 쓰는 옵션 | 설명 |
|---|---|
--format json · --format chunks | 구조화 JSON / RAG용 청크 JSON(제목·개조식 위계 경로 + 표 독립 청크) |
--plain | 그림 자리·링크 주소·굵게 표기를 뺀 평문 Markdown(제목·목록·표 구조는 유지) |
--html-tables | 모든 표를 HTML 표로 — 병합 칸이 많은 표에 알맞습니다 |
--keep-layout-tables | 배치용 틀 표를 풀지 않고 원본 표 구조 그대로 둡니다(patch용 편집본은 이 옵션으로) |
--no-tables | PDF 표 감지를 끕니다 — 2단 시험지처럼 상자를 표로 오인하는 문서용 |
--no-header-footer | PDF 머리글·바닥글 자동 제거를 끕니다 |
--no-images | 그림 바이트를 꺼내지 않고 글자만 냅니다 |
--silent | 진행 메시지를 숨깁니다 |
3. 출력 형식과 종료 코드
스크립트에서 쓰기 쉽도록 성공과 실패를 분명히 나눕니다.
| 상황 | 표준 출력 | 종료 코드 |
|---|---|---|
| 성공 | 결과물만(Markdown·JSON) | 0 |
| 실패 | {"success":false,"code":"…","error":"…"} | 1 |
lint에서 error 등급 위반 발견 | 검수 결과 | 1 |
patch에서 적용하지 못한 편집이 남음 | 결과 파일은 만들고 건너뛴 내역은 표준 오류로 | 2 |
4. 공문서 만들기
마크다운을 한글에서 여는 HWPX 공문서로 조판합니다. 목록은 공문서 항목 기호(□·ㅇ)로, ## 제목은 프리셋에 맞는 장 제목으로 바뀝니다.
# 기본 프리셋은 기안문 hunsdoc generate 기안.md -o 기안문.hwpx # 프리셋 — 한글 이름이나 영문 이름 모두 됩니다(gen은 generate의 줄임) hunsdoc generate 보고서.md --preset 보고서 -o 보고서.hwpx hunsdoc gen 회의.md --preset minutes -o 회의록.hwpx # 개조식 — 표지·목차·장 헤더 자동, 표지 기관명과 결재란 hunsdoc generate 계획.md --preset 개조식 --org "○○시" --approval 담당,팀장,과장 -o 계획.hwpx # 점검 — 행정 표기법 검수(날짜·시간·금액·붙임), HWPX 구조 검증 hunsdoc lint 계획.md hunsdoc validate 계획.hwpx
| 프리셋 | 영문 이름 | 특징 |
|---|---|---|
| 기안문 | official | 기본값 · 본문 끝 “끝.” 표시 · 두문표(--doc-head)·결문표(--doc-foot) |
| 보고서 | report | 장 제목 띠 · 쪽번호 · 요약 상자(--summary) |
| 계획서 | plan | 장 제목 띠 · 쪽번호 |
| 통지 | notice | 장 제목 번호(1.) · 공고문 두문·결문(--notice-head) |
| 회의록 | minutes | 회의록 양식 |
| 개조식 | gaejosik | 표지·목차·장 헤더 자동 · 쪽번호 |
| 업무보고 | ministry | 중앙부처 업무보고 — 장 띠·절 숫자칸·소제목 박스·성과 요약 상자·별첨 띠 |
| 서울방침 | bangchim | 서울시 방침서 — 제목표·파랑 부제·요약 상자·[Ⅰ] 장 상자·❶ 과제 |
| 보도자료 | press | 보도자료 머리(--press-head)·부제(--press-sub) |
글꼴·크기·줄간격(--font·--pt·--line-spacing), 용지와 방향(--paper·--landscape), 그림 폴더(--image-dir) 같은 옵션은 hunsdoc generate --help에서 볼 수 있습니다.
5. 서식 그대로 고치기
글만 고치기 — patch
원본 HWPX·HWP의 글꼴·표·도장칸·그림은 그대로 두고, 고친 글만 원본 자리에 반영합니다. 반영한 뒤 문서를 다시 읽어 편집본과 같은지 확인합니다.
# 1) 편집용 마크다운 뽑기 — patch용은 --keep-layout-tables hunsdoc 원본.hwpx --keep-layout-tables -o 편집.md # 2) 편집.md 의 글을 고친 뒤 # 3) 바뀐 글만 반영 — -o 를 빼면 원본.patched.hwpx hunsdoc patch 원본.hwpx 편집.md -o 결과.hwpx
원본과 짝을 찾지 못한 편집(표를 글로 바꾸는 것 같은 구조 변경 등)은 버리지 않고 목록으로 알려 주며, 이때 종료 코드는 2입니다.
서식 빈칸 채우기 — fill
# 서식의 칸·누름틀 목록만 보기 hunsdoc fill 신청서.hwpx --dry-run # 값 채우기 — 쉼표 구분 또는 JSON 파일 hunsdoc fill 신청서.hwpx -f '성명=홍길동,전화=010-1234-5678' -o 결과.hwpx hunsdoc fill 신청서.hwpx -j 값.json --require-unique -o 결과.hwpx # 내장 표준 서식(일반기안문·간이기안문) hunsdoc fill --list-templates hunsdoc fill --template gian -f '제목=시험 기안' -o 기안문.hwpx
기본 출력은 원본 서식(테두리·글꼴·병합)을 유지하는 hwpx-preserve입니다. --require-unique를 주면 같은 이름의 칸이 두 곳 이상일 때 채우지 않고 멈춥니다.
도장·서명 얹기 — seal
hunsdoc seal 신청서.hwpx --image 도장.png --anchor "(인)" -o 결과.hwpx
“(인)” 같은 문구 위에 도장 그림을 글 앞에 띄워 놓습니다. 표나 쪽 크기를 바꾸지 않습니다(HWPX 전용). 겹침·옆 배치(--mode), 크기(--size-mm), 미세 조정(--dx·--dy)을 정할 수 있습니다.
6. 개인정보 가리기
# HWPX·HWP — 서식과 글자 수를 유지한 채 가린 새 파일(-o 를 빼면 이름.redacted.hwpx) hunsdoc redact 신청서.hwpx -o 신청서.공개용.hwpx # 무엇이 걸리는지 보고서만(파일은 만들지 않음) hunsdoc redact 신청서.hwpx --dry-run --json # 인명·주소까지, 가림 문자 바꾸기 hunsdoc redact 명단.hwpx --rules rrn,phone,name,address --mask-char ○ -o 명단.공개용.hwpx # PDF·워드·엑셀 — 원본은 그대로 두고 가린 Markdown만 hunsdoc redact 보고서.pdf -o 보고서.공개용.md hunsdoc redact 명단.xlsx -o 명단.공개용.md
| 구분 | 규칙 이름 | 대상 |
|---|---|---|
| 기본 | rrn phone email card account brn passport driver | 주민·외국인등록번호, 전화, 이메일, 카드, 계좌, 사업자등록번호, 여권, 운전면허 |
| 선택 | crn ip name address | 법인등록번호, IP 주소, 인명, 주소 |
HWPX·HWP는 본문·표·머리말/꼬리말·각주·글상자·메타데이터·미리보기 글까지 가립니다. PDF·워드·엑셀 원본은 고치지 않습니다. PDF를 공개하려면 PDF 편집기의 가림(redaction) 기능을 쓰거나, 가린 Markdown으로 새 문서를 만드세요. 그림 속 글자는 찾지 못하므로 결과는 반드시 사람이 확인하세요.
7. 렌더링과 표 추출
# HWPX 전체 쪽을 세로로 이은 SVG 한 장 hunsdoc render 문서.hwpx -o 문서.svg # 쪽별 SVG, HTML, 검색어 형광펜 hunsdoc render 문서.hwpx --pages 1-3 -d 쪽/ hunsdoc render 문서.hwpx --format html -o 문서.html hunsdoc render 문서.hwpx --highlight "예산,일정" -o 문서.svg # 표를 찾아 분류(데이터 표 / 배치용 표 / 불확실)한 JSON hunsdoc tables 문서.hwpx --cells -o 표.json
입력은 HWPX와 HWP(5.x)입니다. PNG·JPEG·PDF 출력과 영역 잘라내기는 지원하지 않습니다 — SVG를 브라우저나 변환 도구로 바꿔 쓰세요.
8. 폴더 감시
hunsdoc watch 받은편지함/ -d 변환결과/ hunsdoc watch 받은편지함/ -d 변환결과/ --webhook https://내부서버/hook
폴더에 문서가 들어오면 쓰기가 끝나기를 기다렸다가 자동으로 변환합니다. 한 번에 3개까지 처리하고 나머지는 대기열에 둡니다. 500MiB보다 큰 파일은 건너뜁니다. --webhook은 결과 요약을 보내는데, 내부망 주소로는 보내지 않도록 막혀 있습니다.
9. AI 에이전트 연동(MCP)
hunsdoc-mcp(또는 hunsdoc mcp)는 표준 입출력으로 동작하는 MCP 서버입니다. Claude Desktop이라면 설정 파일 claude_desktop_config.json에 다음처럼 등록합니다.
{
"mcpServers": {
"hunsdoc": {
"command": "/usr/local/bin/hunsdoc-mcp",
"env": { "HUNSDOC_ROOT": "/data/문서함" }
}
}
}
HUNSDOC_ROOT를 주면 AI가 읽고 쓸 수 있는 파일을 그 폴더 안으로 제한합니다.
| 도구 | 하는 일 |
|---|---|
parse_document · parse_pages · parse_chunks | 문서 → Markdown / 쪽 범위 / RAG 청크 |
detect_format · parse_metadata | 형식 판별 / 제목·작성자 같은 메타데이터 |
parse_table · extract_tables | N번째 표 / 표 추출·분류 |
compare_documents | 두 문서 비교(신구대조) — HWP↔HWPX도 가능 |
parse_form · fill_form · place_seal | 서식 칸 읽기 / 채우기 / 도장 얹기 |
patch_document | 서식 보존 편집 |
redact_document | 개인정보 가리기 |
generate_document · extract_profile | 공문서 생성 / 표 서식 프로필 |
render_document | SVG·HTML 렌더 PNG·JPEG·PDF 미지원 |
crop_regions | 영역 잘라내기 미지원 |
10. 스캔 문서 OCR
hunsdoc에는 글자 인식 엔진이 들어 있지 않습니다. --ocr이나 --ocr-force를 줄 때만 외부 프로그램을 불러 인식합니다. 쪽을 그림으로 바꾸는 데는 pdftoppm(없으면 mutool)을, 글자 인식에는 Tesseract 등을 씁니다.
# 설치 예 — macOS brew install tesseract tesseract-lang poppler # 설치 예 — Debian/Ubuntu apt install tesseract-ocr tesseract-ocr-kor poppler-utils # 스캔 PDF, 이미지 파일 HUNSDOC_OCR_PROVIDER=tesseract hunsdoc 스캔.pdf --ocr-force HUNSDOC_OCR_PROVIDER=tesseract hunsdoc 사진.png --ocr # 자체 인식기 — 쪽 그림을 표준 입력으로 받아 글을 표준 출력으로 내는 명령 HUNSDOC_OCR_CMD="my-ocr --page {page}" hunsdoc 스캔.pdf --ocr
인식 프로그램이 없거나 어떤 쪽에서 실패해도 문서 전체가 실패하지는 않습니다. 그 쪽만 경고와 함께 원래 내용으로 남습니다.
11. 폐쇄망 운영과 환경 변수
hunsdoc은 문서를 처리하면서 외부와 통신하지 않습니다. 밖으로 나가는 요청은 watch --webhook 하나뿐이고, HUNSDOC_OFFLINE=1을 주면 그 요청도 오류로 막습니다. 모델 다운로드 같은 숨은 통신은 없습니다.
| 환경 변수 | 역할 |
|---|---|
HUNSDOC_OFFLINE | 참이면 모든 외부 요청을 막습니다(KORDOC_OFFLINE도 인식) |
HUNSDOC_ROOT | MCP 서버와 generate --image-dir가 접근할 수 있는 폴더 제한(KORDOC_ROOT도 인식) |
HUNSDOC_OCR_PROVIDER | OCR 인식기 — tesseract |
HUNSDOC_OCR_CMD | OCR 인식기로 쓸 임의 명령({page}·{mime} 자리 채움) — HUNSDOC_OCR_PROVIDER보다 우선 |