HWPX MCP Server

한글 문서(HWPX)를 AI로 안전하게 읽고 · 편집하고 · 배치까지 재현한다.

한컴오피스 없이 Node.js만으로 동작하는 Model Context Protocol 서버. Claude·Cursor 등 MCP 클라이언트에 연결하면 146개 도구로 한글 문서를 다룰 수 있습니다.

HWPX는 ZIP + XML 구조라 한글 프로그램 없이도 다룰 수 있습니다. 하지만 "그냥 XML을 고치면" 문서가 깨지기 쉽습니다 — 이 서버는 무손실 CST와 쓰기 게이트 위에서 편집하고, 나아가 문서의 레이아웃을 재현하고 문서 전체를 구조적으로 재구성할 수 있음을 검증합니다.

// 30초 요약
open_document → search / edit (스타일 승계, 원자적 계획) → save_document   // 안전 편집
render_preview / render_pdf                                              // 저장 전 미리보기
reconstruct + verify:manipulation                                       // 원본과 구조·픽셀 동일 재구성 증명

✨ 무엇이 다른가 (Highlights)

• 🔒 무손실 CST 아키텍처 — 무손실 XML 구문 트리가 단일 진실 소스. 수정하지 않은 문서는 저장 시 바이트 단위로 동일하고, 편집은 대상 요소 스팬 안에서만 바이트를 바꿉니다.

• ✅ 검증되는 쓰기 — 저장 응답이 structural_integrity_verified(아카이브/XML 불변식)와 intent_verified(편집 의도 대비 사후조건)로 분리됩니다. 검증에 실패한 쓰기는 디스크에 도달하지 않습니다.

• 🧩 의미 기반 안전 편집 — insert_paragraphs는 스타일·탭·번호 서식은 승계하되 위험한 페이로드는 제거하고, preview_edit_plan / apply_edit_plan으로 다중 편집을 하나의 스냅샷/undo 경계에서 원자적으로 적용(실패 시 롤백)합니다.

• 🖼️ 레이아웃 재현 엔진 — 섹션 CST를 Page→Column→Block→Line 박스 트리로 배치(문단 여백·자간·줄간격, 표 auto-grow, 다단, 부동/인라인 객체). render_preview(페이지별 SVG HTML)와 render_pdf(헤드리스 Chrome)로 저장 전에 결과를 미리 봅니다.

• 🎯 조작 완전성 (v2.0) — 원본 문서를 빈 문서에 도구로 재구성하면 원본과 구조적으로 동일(해석-의미 diff=0)하고, 우리 렌더러로 출력한 PDF가 원본과 픽셀 동일함을 코퍼스 전체에서 게이트로 증명합니다.

• 🛠️ 146개 도구 — 문단·표·이미지·도형·수식·머리글/바닥글·각주/미주·북마크·하이퍼링크·메모·섹션·스타일·페이지·다단·목차·렌더·내보내기·undo/redo.

전체 변경 이력은 CHANGELOG.md를 참고하세요.

Related MCP server: Office Word MCP Server

📦 설치 (Installation)

요구사항: Node.js ≥ 18. PDF 출력을 쓰려면 Chrome 또는 Edge(선택).

git clone https://github.com/h9661/hwpx-mcp.git
cd hwpx-mcp
npm install
npm run build

MCP 클라이언트에 서버를 등록합니다 (경로는 빌드된 dist/index.js 절대 경로):

{
  "mcpServers": {
    "hwpx-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/hwpx-mcp/dist/index.js"]
    }
  }
}

Windows 경로는 / 또는 \\를 사용하세요. 등록 후 클라이언트를 재시작하면 도구 목록에 hwpx-mcp가 나타납니다.

🚀 빠른 시작 (Quick Start)

await mcp.open_document({ file_path: "report.hwpx" })

// 1) 스타일을 승계해 문단 삽입 (secPr/표/필드 등 위험 페이로드는 제거)
await mcp.insert_paragraphs({
  doc_id, section_index: 0, after_ref: "<현재 element_ref>",
  texts: ["새 문단 1", "새 문단 2"],
})

// 2) 같은 텍스트가 여러 곳일 때, 특정 셀만 정밀 치환
await mcp.replace_text_in_cell({
  doc_id, section_index: 0, table_index: 2, row: 3, col: 1,
  old_text: "대상", new_text: "새 내용",
})

// 3) 저장 전에 결과를 PDF로 미리보기
await mcp.render_pdf({ doc_id, output_path: "preview.pdf" })

await mcp.save_document({ doc_id })

🔌 도구 (Tools)

카테고리별 개요입니다. 전체 목록·파라미터는 MCP 클라이언트의 도구 패널에서 확인하세요.

✅ 검증 (Quality Gates)

이 저장소는 "잘 될 것"이 아니라 측정된 게이트로 품질을 담보합니다.

LAYOUT_GATE=1 / MANIP_GATE=1은 실문서 코퍼스가 있을 때만 동작하며(기밀 문서는 커밋 제외), 기본 테스트는 코퍼스 없이 빠르게 돕니다.

📋 지원 포맷 & 알려진 제한

Known limitations

• 자가검증 실패 문서는 읽기 전용: 열기 시 CST 라운드트립 자가검증에 실패한 문서는 조회만 가능하며, repair_xml로 복구 후 저장할 수 있습니다.

• 렌더 충실도는 우리 엔진 기준: render_preview/render_pdf는 한글의 인쇄 시점 재줄바꿈과 래스터라이저 차이가 있어 한글 출력과 100% 픽셀 일치는 아닙니다. 최종본은 한글에서 확인을 권장합니다(재구성-원본 픽셀 동일성은 우리 렌더러 기준으로 게이트 검증됨).

• PDF 출력엔 Chrome/Edge 필요: render_pdf는 헤드리스 브라우저(--print-to-pdf)를 사용합니다. CHROME_PATH로 경로 지정 가능.

• 병렬 테스트 flake(CellMerge, SemanticModel.corpus 등, ~1/8): 단독/부분 병렬에선 안정 → 로직 결함이 아닌 하네스 타임아웃 아티팩트.

🗺️ 로드맵 (Roadmap)

• 레이아웃 엔진 v2: 박스 모델 배치(표 auto-grow·다단·부동객체), 문자-클래스 폰트 메트릭, 캘리브레이션 CLI, 실문서 코퍼스 회귀 게이트(정확 페이지 98.58%).

• 프리뷰 렌더러: render_preview(페이지별 SVG HTML) + render_pdf(헤드리스 Chrome), 탭스톱·양끝맞춤·머리/바닥글·이미지·표까지 반영.

• 조작 완전성: 원본→빈 문서 재구성이 구조 diff=0 + 렌더 픽셀 동일 + 변형 왕복 무손실임을 코퍼스 전체 게이트로 증명(SemanticModel·StructuralDiff·Reconstructor·CoverageMap·MutationRoundTrip·verify:manipulation).

다음 (v2.x+)

• 범용 edit plan(삽입·수정·삭제·이동·표를 한 트랜잭션으로) · 문서 diff/patch

• 스타일 라이브러리 · 번호/불릿 확장 · 표 프리셋

• Markdown ⇄ HWPX 구조 보존 변환, HWP(바이너리) 읽기 브리지

• 대용량 스트리밍 · 증분 저장 · 벤치마크

PR·이슈 환영합니다 → GitHub Issues

🙏 Credits & License

• 계보: mjyoo2/hwp-extension → Dayoooun → h9661/hwpx-mcp

• License: MIT — LICENSE