hwp-mcp-old-hangul — 옛한글 지원 개발 버전

이 저장소는 treesoop/hwp-mcp를 기반으로 옛한글 텍스트 추출과 HWPX 텍스트 수정을 확장한 별도 개발 저장소입니다. 원본 작성자의 MIT 라이선스와 크레딧을 유지합니다.

• 추가 도구: read_hwp_old_hangul — 한양 PUA 5,660개 변환, 원문 추출 비교, 미지원 문자 진단.

• 보존: 아래아·반치음·옛이응·확장 자모·채움문자·방점. 기존 읽기·Markdown 도구는 old_hangul: "unicode"로 변환을 선택합니다.

• 수정: HWPX 검색·치환과 템플릿 채우기도 old_hangul: "unicode"를 지원합니다. 숫자 참조·분리된 run·반복 출현을 처리하고, 문단의 쪽 설정 삭제와 셀의 잔여 텍스트 문제를 보완했습니다. .hwp 저장은 지원하지 않습니다.

• 문서: 업데이트·테스트 결과·참고 출처, 사용법·매핑 출처·제약.

• 검증: 합성 HWP/HWPX 및 MCP 호출을 포함한 123개 테스트 통과. HWPX 수정·저장·재열기를 검증했으며, 실제 한컴오피스의 표시·쪽 배치와 고문헌 특수 글꼴은 별도 검증이 필요합니다.

이 수정본 설치

Node.js 20 이상에서 이 저장소를 내려받아 다음 순서로 실행합니다.

npm ci
npm run build
npm test

MCP 클라이언트 설정에서 컴파일된 서버의 실제 절대 경로를 지정합니다.

{
  "mcpServers": {
    "hwp-mcp-old-hangul": {
      "command": "node",
      "args": ["/absolute/path/hwp-mcp-old-hangul/dist/server.js"]
    }
  }
}

이 개발 패키지는 private: true로 설정했고 npm에 배포하지 않았습니다. 아래 보존된 기존 README의 npx hwp-mcp와 npm 배지는 원본 공개 패키지를 가리킵니다. 이번 수정본은 위 로컬 실행 방식을 사용하세요.

Related MCP server: HWPX MCP Server

기반 프로젝트 README (수정 기능 설명 포함)

hwp-mcp

Claude · Cursor · ChatGPT 등 MCP 호환 AI에서 한글 문서(.hwp / .hwpx) 를 읽고 수정하고 새로 만들 수 있게 해주는 서버입니다.

hwp-mcp은 한컴오피스 문서를 AI 에이전트가 직접 다루도록 해주는 MCP(Model Context Protocol) 서버입니다. 읽기뿐 아니라 텍스트 수정, 템플릿 채우기, 새 문서 생성까지 가능합니다.

🍎 맥에서도 됩니다. 기존 HWP 자동화 도구 대부분은 한컴오피스 COM API 기반이라 Windows 전용이지만, hwp-mcp는 WebAssembly 엔진이라 macOS(Apple Silicon 포함) · Windows · Linux 어디서든 한컴오피스 설치 없이 동작합니다.

어떤 프로젝트인가요?

이 프로젝트는 두 부분으로 나뉩니다.

• 🔧 핵심 엔진: rhwp — Edward Kim 님의 rhwp는 한글 포맷(HWP 5.0 binary, HWPX/OWPML)을 Rust + WebAssembly로 구현한 오픈소스 엔진입니다. 파싱, 표·이미지·수식·머리말 추출, SVG 렌더링, 한컴 호환 Field API 등 포맷 처리 능력을 제공합니다.

• 🤝 hwp-mcp 가 한 일 (에이전트 어댑터) — @rhwp/core 위에 얹은 MCP 서버 layer. 우리가 추가한 것은:

  • read_hwp, fill_hwp_template, replace_hwp_text 같은 에이전트 친화적 도구 시그니처 — Claude/Cursor 같은 LLM이 자연어로 호출할 수 있게

  • 본문·표·이미지·머리말·꼬리말·각주·수식을 한 번에 dump 하는 시나리오 중심 traversal walker

  • 표 셀 병합 자동 처리, footnote/equation 자동 합본 같은 사용 편의 layer

  • rhwp 0.7.7 의 exportHwpx 라운드트립 한계를 우회하기 위한 .hwpx ZIP-level mutation layer (실제 쓰기를 가능하게 하는 핵심)

  • npm hwp-mcp 패키지 (한 줄 설치) + Node.js WASM 부트스트랩

요약: AI 에이전트가 한글 문서를 읽고 쓸 수 있게 해주는 어댑터입니다. 포맷 처리는 rhwp, 에이전트 연동은 hwp-mcp 가 담당합니다.

설치

Claude Code

claude mcp add hwp-mcp -- npx -y hwp-mcp

Claude Desktop / Cursor / VS Code (settings JSON)

{
  "mcpServers": {
    "hwp-mcp": {
      "command": "npx",
      "args": ["-y", "hwp-mcp"]
    }
  }
}

Node.js 20 이상 필요. macOS · Windows · Linux 모두 지원 — 엔진이 WebAssembly 기반이라 한컴오피스 설치 없이 OS 무관하게 동작합니다. pywin32·COM 자동화처럼 Windows에 묶이지 않아 맥북에서도 위 한 줄로 끝입니다.

설치 확인

claude mcp list | grep hwp-mcp
# hwp-mcp: npx -y hwp-mcp  - ✓ Connected

✓ Connected 가 뜨면 끝.

처음 써보기 (60초)

설치 직후 동작 확인용 가장 짧은 검증:

나: 새 hwpx 문서 만들어줘. 파일 이름은 hello.hwpx 이고 "안녕 한글" 한 줄만 들어가게.
AI: HWPX 문서 생성 완료 (created): hello.hwpx

나: hello.hwpx 읽어줘.
AI: # hello.hwpx
    안녕 한글

위 두 단계가 되면 읽기·쓰기 양쪽 다 동작합니다. 이제 실제 문서로:

• ~/Downloads/공고문.hwp 읽어줘

• report.hwpx 의 {{이름}}을 남대현으로, {{날짜}}를 2026-05-26으로 채워줘

• document.hwpx 의 첫 페이지를 SVG로 보여줘

안 되면?

v0.2.0 → v0.2.1 업그레이드:

claude mcp remove hwp-mcp
claude mcp add hwp-mcp -- npx -y hwp-mcp@latest
claude mcp list | grep hwp-mcp   # ✓ Connected

설정 파일 방식(Claude Desktop/Cursor)이면 args 를 ["-y", "hwp-mcp@latest"] 로:

{
  "mcpServers": {
    "hwp-mcp": {
      "command": "npx",
      "args": ["-y", "hwp-mcp@latest"]
    }
  }
}

여전히 안 되면: Issues 에 node --version, claude mcp list 출력, 실행 OS 적어서 알려주세요.

도구 목록

hwp-mcp가 노출하는 36개 MCP 도구입니다. 읽기·렌더는 .hwp/.hwpx 모두 지원, 쓰기는 .hwpx 전용입니다.

읽기 / 변환 (7)

메타 / 조회 (5)

시각 렌더 (4)

쓰기 — 텍스트 (5)

쓰기 — 구조 (9)

쓰기 — 서식 (2)

쓰기 — 이미지 / 표 / 신규 (4)

컨텐츠 추출 매트릭스

작성 매트릭스

.hwp 바이너리 쓰기는 rhwp 0.7.7 의 exportHwp 라운드트립 한계로 v0.2에서 미지원. 한컴오피스에서 .hwpx로 다른 이름 저장 후 쓰기 도구를 사용하시거나, v0.3 릴리스를 기다려주세요.

사용 예시

옛한글 읽기 (아래아·반치음·옛이응·방점)

옛한글이 들어 있는 HWP 5.x / HWPX를 읽을 때는 read_hwp_old_hangul을 사용합니다. 구형 한양 PUA 5,660개를 유니코드 첫가끝 자모로 변환하고, 기존 유니코드 자모·확장 자모·채움문자·방점은 그대로 보존합니다.

{"file_path":"/path/to/훈민정음.hwpx","include_original":true}

결과는 text(변환 결과), original_text(선택: 변환 전 추출문), analysis(문자 수와 경고)를 담은 JSON입니다. 기존 read_hwp, read_hwp_text, read_hwp_tables, convert_hwp_markdown에도 "old_hangul":"unicode"를 지정할 수 있습니다. 이 옵션을 생략하면 기존처럼 추출문을 보존합니다(preserve).

PUA는 글꼴에 따라 뜻이 달라질 수 있으므로 한양 PUA로 작성된 문서에만 변환을 요청하세요. 알 수 없는 PUA는 삭제하지 않고 남깁니다. 스캔 OCR, 현대어 번역, HWP 3.x 지원을 추가하는 기능은 아닙니다. 자세한 사용법·제약·개발 설치·매핑 출처: 옛한글 지원 안내. 변경 내용과 기반 프로젝트·데이터 출처: 업데이트 및 참고 출처.

정부 한글 문서 읽기

나: /Users/me/2026년_시행계획.hwpx 읽어줘

AI: # 2026년_시행계획.hwpx
    형식: .HWPX | 문단: 153개 | 표: 15개 | 이미지: 2개

    Ⅰ. 추진 배경
    □ (글로벌 현황) 전세계 AI 솔루션 시장 규모는 ...

    ### 표 9 (7행 x 4열)
    | 도메인 | 입력 데이터 | 학습 내용 | 산업AI 솔루션 적용 기능 예시 |
    | --- | --- | --- | --- |
    | 기계 | · 센서 데이터 로그 ... | ... | ... |

템플릿 채우기

나: /path/to/form.hwpx 에서 {{이름}}=남대현, {{회사}}=포텐랩 으로 채워줘

AI: 저장 완료 (saved): form_filled.hwpx
    총 2건 치환 (2 replacements)
      '{{이름}}' → 1건
      '{{회사}}' → 1건

텍스트 치환

나: /path/to/doc.hwpx 의 "산업AI" 를 "산업-AI" 로 바꿔줘

AI: '산업AI' → '산업-AI': 18건 교체 (replaced 18)
    저장 (saved): doc_modified.hwpx

새 .hwpx 만들기

나: employees.hwpx 에 "사원 명부" 와 "두 번째 줄" 두 줄을 가진 문서 만들어줘

AI: HWPX 문서 생성 완료 (created): employees.hwpx

이미지 추출

나: /path/to/document.hwpx 에서 이미지 빼줘

AI: 이미지 2개를 추출했습니다 (extracted 2 images):
    저장 위치: /path/to/document_images
      - image_001.bmp
      - image_002.bmp

페이지를 SVG로 렌더 (시각 분석용)

나: /path/to/document.hwpx 의 첫 페이지를 SVG로 보여줘

AI: <svg xmlns="..." width="793" height="1122" viewBox="...">
    <defs>...</defs>
    ...
    </svg>

또는 디스크로 저장:

나: /path/to/document.hwpx 모든 페이지 SVG로 저장해줘

AI: 9/9 페이지 SVG 저장 (rendered 9/9 pages):
    저장 위치: /path/to/document_pages
      - page_001.svg
      - page_002.svg ...

한계

hwp-mcp v0.2의 알려진 제약 사항입니다.

• .hwp 쓰기 미지원 — 읽기는 .hwp/.hwpx 모두 됩니다. 쓰기는 .hwpx만. .hwp 입력에 대해 쓰기 도구를 호출하면 명확한 에러 메시지를 돌려줍니다. 한컴오피스에서 .hwpx로 다른 이름 저장 후 사용하시거나, v0.3 릴리스를 기다려주세요.

• 크로스 포맷 저장 거부 — .hwpx 입력은 .hwpx로만 저장됩니다.

• 머리말/꼬리말/각주 추출 가능, 텍스트박스/미주/수식은 v0.3 — read_hwp_text 결과에 머리말은 --- headers ---, 꼬리말은 --- footers ---, 각주는 --- footnotes --- 블록으로 표시됩니다. 텍스트박스 본문, 미주, 수식 추출은 v0.3 예정.

• 검색어가 두 텍스트 노드에 걸치면 매칭 안 됨 — 예: 한 <hp:t>가 "산업"으로 끝나고 다음이 "AI"로 시작하면 "산업AI"는 매칭 X. 한컴 hwpctl과 동일한 한계입니다.

• create_hwpx_document의 표는 v0.2에서 텍스트 행으로 평탄화 — 진짜 OWPML 표는 v0.3에서.

어떻게 동작하나요?

• 읽기: @rhwp/core (rhwp의 Rust+WASM 파서) 가 섹션·문단·표(병합 셀 포함)·이미지를 traverse 합니다.

• 쓰기 (.hwpx): ZIP 아카이브 안의 Contents/section*.xml 을 직접 파싱해서 <hp:t> 텍스트 노드를 search/replace 한 뒤 다시 패키징합니다 (mimetype은 spec대로 stored). rhwp의 exportHwpx() 라운드트립 이슈를 우회하기 위한 layer입니다.

• 새 문서: rhwp의 createBlankDocument + insertText 로 작성한 뒤 exportHwpx 로 저장합니다 (텍스트 라운드트립이 안정).

크레딧

rhwp (@edwardkim, MIT) — 한글 포맷 파서·렌더러·Field API. 이 프로젝트의 포맷 처리는 rhwp 에 기반합니다: https://github.com/edwardkim/rhwp

hwp-mcp — rhwp 위에 AI 에이전트가 자연어로 호출할 수 있게 도구화한 MCP 어댑터.

커버리지

남은 큰 항목: .hwp 바이너리 쓰기, 차트, 스타일 정의·적용, 텍스트박스 본문 추출, hwpctl 30 Actions(의도적 제외).

업데이트 노트

미출시 — 옛한글 추출 지원

• read_hwp_old_hangul 추가: 유니코드 자모 변환, 변환 전 추출문 선택 반환, 알 수 없는 PUA 진단.

• 읽기·Markdown 변환 도구에 선택적 old_hangul 인자 추가. 기본 출력은 기존과 동일합니다.

• HWPX 본문의 비 ASCII XML 숫자 참조를 엔진이 누락하던 문제 보완 (원본 파일 변경 없이 메모리에서 처리).

• 공개 KTUG 한양 PUA 매핑을 포함하므로 외부 변환 서비스나 추가 런타임 패키지가 필요 없습니다.

v0.3.0 (2026-07-08)

• ✨ convert_hwp_markdown 신규 — HWP/HWPX → Markdown 변환. 문서 흐름 순서를 그대로 유지합니다(기존 read_hwp는 본문 뒤에 표를 몰아서 출력).

  • 표는 제자리에 GitHub 마크다운으로

  • 이미지는 <문서명>_images/로 추출 + 상대링크 (output_path 생략 시 markdown 문자열만 반환)

  • 수식은 $…$ 인라인, 각주는 문서 끝 [^N]: 목록

  • 개요 17 스타일 문단은 ####### heading으로 (best-effort)

• 내부: 순서 보존 traversal walker walkDocumentFlow 추가 — 수식 컨트롤이 1x1 표로도 응답하는 rhwp 특성 처리

v0.2.1 (2026-05-26)

• 🐛 bin-symlink 버그 수정 — v0.2.0에서 npx hwp-mcp 실행 시 서버가 조용히 종료되던 문제

v0.2.0 (2026-04-29)

• Python 구현 폐기, rhwp(Rust + WASM) 기반 전면 재작성 — 한컴오피스·OS 의존성 제거

• 읽기·렌더 .hwp/.hwpx 지원, .hwpx 쓰기(치환·템플릿·신규 생성·구조 편집) 34개 도구

v0.1 (2026-03-31)

• 최초 릴리스 (hangul-mcp → hwp-mcp 개명, Python 기반)

릴리스 / 이슈

• 변경 이력: 위 업데이트 노트 및 https://github.com/treesoop/hwp-mcp/releases

• 버그 신고 · 기능 제안: https://github.com/treesoop/hwp-mcp/issues

• npm 패키지: https://www.npmjs.com/package/hwp-mcp

이슈 올릴 때는 node --version, OS, MCP 클라이언트(Claude Code / Desktop / Cursor / …), 그리고 가능하면 재현되는 .hwpx 샘플을 첨부해주세요.

English

hwp-mcp is an MCP server for reading and writing Korean Hangul (.hwp / .hwpx) documents from Claude / Cursor / ChatGPT and any MCP-compatible client. Read and Markdown conversion work for both formats; write currently supports .hwpx (find/replace, template fill, create new doc) — .hwp write is planned. Runs on macOS (including Apple Silicon), Windows, and Linux — WebAssembly-based, no Hancom Office install required, no Windows-only COM automation. Built on top of rhwp (Rust + WebAssembly HWP engine by Edward Kim, MIT).

claude mcp add hwp-mcp -- npx -y hwp-mcp
claude mcp list | grep hwp-mcp   # ✓ Connected

Not seeing ✓ Connected? Upgrade to v0.2.1+ (npx -y hwp-mcp@latest) — v0.2.0 had a bin-symlink bug that made the server exit silently. Tools not appearing in your AI client? Restart the session; MCP tools load at startup.

License

MIT.