HWP·HWPX 변환 API 와 MCP 도구

한글 문서(HWP 5.x, HWPX)를 코드나 AI 도우미에서 읽습니다. 구조가 있는 글, Markdown, 편집할 수 있는 DOCX 로 바꿉니다.

엔드포인트

주소	돌려주는 것
`POST /v1/hwp/text`	JSON: `text`, 읽는 순서대로 `blocks`(문단, 행·칸·병합 범위가 든 표, 표 안의 표), `stats`(구역·문단·표·쪽 수)
`POST /v1/hwp/markdown`	JSON: `markdown`(문단, 표는 Markdown 표)
`POST /v1/hwp/docx`	JSON: `outputs[0]` 에 DOCX(base64, 문단·표)
`POST /v1/hwp/pdf`	서버에서는 안 됨(오류 `browser_only`). 쪽 그리기는 글꼴이 필요해 브라우저에서만: HWP → PDF

curl -X POST https://toolsthatdontupload.com/v1/hwp/markdown \
  -H "X-API-Key: 내_키" -F file=@공고문.hwp

JSON 으로도: {"name": "공고문.hwp", "base64": "..."}.

OpenAPI 명세: /openapi/files.json.

MCP

MCP 서버의 hwp_to_markdown, hwp_to_text, hwp_to_docx 에 name, base64 를 넘깁니다(10 MB 까지).

MarkItDown·Docling 플러그인

오픈소스(MIT) 플러그인으로 MarkItDown·Docling 에서 .hwp·.hwpx 를 이 API 로 읽을 수 있습니다. API 방식에서는 아래 "한도·비용·파일"에 적은 대로 문서가 우리 서버로 전송됩니다. TTDU_HWP_BACKEND=local 로 두면 같은 PC 의 오프라인 로컬 실행기를 불러 문서가 PC 밖으로 나가지 않습니다. 소스·설정·오류 종류: github.com/etacbae6768-a11y/ttdu-hwp-plugins.

pip install markitdown-ttdu-hwp   # MarkItDown
markitdown --use-plugins 공고문.hwp

pip install docling-ttdu-hwp      # Docling

남는 것과 빠지는 것

본문 문단(순서·줄바꿈·탭)과 표(병합 칸은 빈칸). 표 안의 표는 부모 표 바로 뒤에.
빠지는 것: 배치·글꼴·색·그림. 머리말·꼬리말·각주·글상자는 빠질 수 있습니다. 쪽 모양 그대로 보려면 브라우저 도구를 쓰세요.
암호·배포용(DRM)·손상 문서는 422(코드 unsupported, invalid_input), 손상 파일이 한도를 넘는 메모리를 요구하면 413.

한도·비용·파일

변환 1번 = 파일 호출 1회입니다(키가 있으면 하루 무료 20회 중 1회, 넘으면 60크레딧; 키가 없으면 IP 당 하루 20회). 파일 1개 15 MB(MCP 10 MB). 문서가 우리 서버(Cloudflare Worker)로 전송되어 그 요청 동안 메모리에서만 처리되며, 문서와 결과를 저장하지 않습니다. 기본 요청 기록은 개인정보처리방침대로 남습니다.

시험

2026-11-07 표본 51개(실제 공개 문서 5, 부처 지침 1, 표가 든 생성 문서 40, 깨짐·암호 5): 읽을 수 있는 46개 모두 브라우저 도구와 글·구조가 완전히 같았고, 나머지 5개는 같은 오류 코드였습니다. 독립 리더와 글자 일치 99.9~100%, 생성 문서 40개는 알려진 문단·표와 정확히 같았습니다.

고지

@rhwp/core 0.8.6(MIT)을 씁니다(라이선스). 본 제품은 한글과컴퓨터의 HWP 문서 파일(.hwp) 공개 문서를 참고하여 개발하였습니다. 한글(HWP)은 ㈜한글과컴퓨터의 상표이며, 이 서비스는 한글과컴퓨터와 관계가 없습니다.