hwpx-mcp-server 2.16.0

MCP server for reading, editing, inspecting, and validating local HWPX documents with AI agents.

📄 hwpx-mcp-server

AI 에이전트가 HWPX 문서를 바로 읽고, 찾고, 채우고, 만들게 하는 MCP 서버

한글 워드프로세서 없이 · 순수 파이썬 · 크로스 플랫폼

---

🧩 HWPX Stack (3종)

계층	레포	역할
📦 라이브러리	python-hwpx	순수 파이썬 HWPX 파싱·편집·생성 코어
🔌 MCP 서버	hwpx-mcp-server	MCP 클라이언트(Claude Desktop, VS Code 등)에서 HWPX 조작
🎯 에이전트 스킬	hwpx-plugins	에이전트가 HWPX를 바로 쓰게 해주는 공식 스킬/플러그인 번들

---

왜 / 무엇을 하나

hwpx-mcp-server는 모델 컨텍스트 프로토콜(MCP) 표준 서버로, python-hwpx 위에서 HWPX 문서의 열람·검색·편집·양식채움·생성·추출을 AI 클라이언트에서 직접 수행하게 합니다.

• 운영체제 무관 — Windows, macOS, Linux에서 동작
• 한글 워드프로세서 불필요 — 순수 파이썬 처리, 서버·CI·로컬 어디서나 같은 흐름
• AI 연동 중심 — Claude Desktop, VS Code, Gemini CLI 등 MCP 클라이언트와 직접 연결
• 문서 조작을 도구 호출로 표준화 — 읽기·편집·복제·양식채움·검증을 하나의 도구 집합으로 노출
• stateless 호출 — 도구마다 filename을 명시하는 일관된 방식

참고 이 서버는 Open XML 기반 .hwpx 포맷을 지원합니다. 바이너리 .hwp는 직접 편집 대상이 아닙니다.

빠른 시작

설치 및 실행

uv 기준:

uvx hwpx-mcp-server

또는 pip 설치 후 실행:

pip install hwpx-mcp-server
hwpx-mcp-server

비-HWPX 문서(PDF/DOCX/XLSX/HTML/TXT)를 document_to_markdown 경로로 읽으려면 MarkItDown adapter extra를 함께 설치합니다.

pip install "hwpx-mcp-server[ingest]"

요구 사항: Python >= 3.10 · python-hwpx >= 2.23.0

MCP 클라이언트 설정

설정 파일에 아래 블록 하나만 넣으면 hwpx 서버를 바로 잡습니다.

• Claude Desktop — claude_desktop_config.json
• Gemini CLI — ~/.gemini/settings.json
• VS Code — .vscode/mcp.json (키가 mcpServers 대신 servers)
• Cursor / Windsurf — 각 에디터의 MCP 설정 파일

{
  "mcpServers": {
    "hwpx": {
      "command": "uvx",
      "args": ["hwpx-mcp-server"]
    }
  }
}

환경 변수를 넘길 때는 env 블록을 추가합니다.

{
  "mcpServers": {
    "hwpx": {
      "command": "uvx",
      "args": ["hwpx-mcp-server"],
      "env": {
        "HWPX_MCP_MAX_CHARS": "12000",
        "HWPX_MCP_ADVANCED": "0",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

hwpx-plugins 번들의 런처(plugins/<host>/hwpx-plugin/scripts/hwpx-mcp-server)로도 실행할 수 있습니다. 로컬 개발 시 레포가 공통 부모 아래에 없으면 HWPX_MCP_SERVER_REPO, PYTHON_HWPX_REPO를 절대경로로 지정하세요.

하나의 흐름부터

처음부터 모든 도구를 외울 필요는 없습니다. 보통 아래 하나로 시작합니다.

1. 읽기 — get_document_info → get_document_outline / get_document_text → find_text, get_table_map 등으로 필요한 부분만. (저장하지 않음)
2. 안전 수정 — copy_document로 사본 생성 → 읽기 도구로 대상 확인 → search_and_replace, set_table_cell_text, apply_edits 등 가장 작은 변경 → 다시 읽어 확인 → 검토가 끝난 복사본을 handoff.

핵심은 copy first · smallest edit · re-read after edits입니다.

무엇을 하나

기본 모드에서 다수의 HWPX 도구를 제공하며, 고급 모드(HWPX_MCP_ADVANCED=1)에서 점검·검증용 도구가 추가됩니다. 아래는 테마별 대표 하이라이트입니다. 전체 도구 목록·시그니처는 docs/use-cases.md와 docs/skill-first-workflows.md를 참고하세요.

• 📖 읽기·탐색 — get_document_info, get_document_text, get_document_outline, find_text, get_table_text, get_table_map, find_cell_by_label, list_styles. get_document_map은 아웃라인·표 지도·누름틀·앵커를 한 호출로 반환(왕복 최소화). (저장하지 않음)
• 📥 로컬 문서 ingest — document_to_markdown, document_extract_json, markdown_to_document_plan이 로컬 문서를 Markdown/JSON/document plan으로 변환합니다. HWPX는 python-hwpx 엔진을 우선 사용하고, 비-HWPX는 [ingest] extra 설치 시 MarkItDown adapter로 처리합니다.
• 🔎 검색·치환 — search_and_replace, batch_replace, replace_in_paragraph, replace_by_anchor. (find_text 외 즉시 저장)
• ✏️ 편집·트랜잭션 — add_heading, add_paragraph/insert_paragraph/delete_paragraph, add_page_break, add_memo 계열. apply_edits는 연산 목록 원자 적용(중간 실패 시 전체 롤백·dry_run·expected_revision 동시성 가드·idempotency_key), undo_last_edit는 .bak 복원, byte_preserving_patch는 미수정 영역 바이트 보존, add_tracked_edit는 변경 추적(redline).
• 📊 표·양식채움 — add_table, set_table_cell_text, merge_table_cells/split_table_cell, format_table, table_compute(합계·평균·소계), fill_by_path(성명 > right 경로 구문). 바이트 보존 구조적 양식채움: 셀 바이트 채움(빈/다중 문단)·행/열/표 삭제·복제 삽입·열 너비 자동맞춤·폰트 축소맞춤을 양식 서식을 재구성하지 않고 그대로 보존하며 수행하고 실제 한컴으로 검증(verify_fill). analyze_template_formfit/apply_template_formfit은 승인된 양식을 원본과 다른 destination에만 반영.
• 🖊️ 누름틀 양식 — list_form_fields, fill_form_field(서식 보존), analyze_form_fill(라벨 매칭 신뢰도 등급).
• 🧾 선언형 문서 생성 — hwpx.document_plan.v1로 OWPML을 직접 만지지 않고 선언: validate_document_plan/analyze_document_plan(파일 미생성) → create_document_from_plan(생성+검증), inspect_document_authoring_quality, inspect_operating_plan_quality, create_proposal_document. compose_exam은 양식 HWPX+마크다운 → 시험지 재조판(verify_question_splits).
• 🏛️ 공문서·비교·대량 생산 — inspect_official_document_style(행정업무 규정 lint: 항목기호 위계·"끝."·붙임·날짜), inspect_reference_consistency, doc_diff/create_comparison_table_document(신구대조표), mail_merge(템플릿+CSV/JSON → N부·파일명 패턴·zip), inspect_mail_merge_placeholders.
• 🎨 서식·그림·생성기 — set_paragraph_format, set_page_setup, set_header_footer, set_page_number, set_list_format, format_text, create_custom_style(입력은 pt/mm/% 인간 단위); insert_picture(manifest 자동 등록)/replace_picture; build_image_grid(사진대지)·build_meeting_nameplates·build_organization_chart.
• 🖥️ 프리뷰·추출·복구·진단 — render_preview(HTML/PNG 시각 자기검증), hwpx_to_markdown/hwpx_to_html/hwpx_extract_json(payload·URL 입력, 파일 미수정), repair_hwpx(원본 보존·mimetype-first 재패킹, recover=true로 손상 ZIP LFH scan 복구; 응답 crcOk/validatePackage.ok/recovered 확인), mcp_server_health(배포 스큐 자기진단·capability handshake).
• 🔬 고급(HWPX_MCP_ADVANCED=1) — package_parts, package_get_xml/package_get_text, object_find_by_tag/object_find_by_attr, plan_edit/preview_edit/apply_edit, validate_structure, lint_text_conventions.

위치 계약 — paragraph_index는 본문 직속 문단의 0-based 인덱스입니다. 표 안 문단은 이 인덱스에 섞지 않고 {"kind":"table_cell_paragraph","table_index":0,"row":0,"col":1,"cell_paragraph_index":0} 같은 location 객체로 지정하며, get_table_map/find_text가 반환한 값을 그대로 넘길 수 있습니다.

안전 사용 원칙

이 서버의 공개 표면은 위 MCP 도구 집합입니다. 워크플로 문서나 스킬 예시는 이 도구들의 조합 패턴이지 별도 계약이 아닙니다.

• read first — 먼저 읽기 도구로 문서를 파악한다.
• copy before risky edits — 결과물을 보존해야 하면 copy_document를 먼저 호출한다.
• mutating tools persist immediately — 수정 도구는 호출 즉시 저장되므로 검토용은 복사본에서 작업한다.
• explicit handoff uses the reviewed copy — 납품·handoff는 검토가 끝난 복사본 파일 기준.
• advanced mode는 점검/검증용으로 분리 — package inspection·edit planning·validation은 HWPX_MCP_ADVANCED=1일 때만 쓰고 기본 흐름과 섞지 않는다.

품질 게이트 계약 (no raw XML)

모델은 operation/plan만 보내고 raw XML을 직접 편집하지 않습니다. raw_xml_replace, arbitrary_xpath_mutation 같은 원시 XML 표면은 public 도구로 노출되지 않습니다. 모든 쓰기는 python-hwpx의 단일 SavePipeline 게이트(VisualComplete)를 통과하며 우회 경로가 없습니다(무결성·XML·OPC/ID·열림안전·FormFit·레이아웃·시각 오라클 → 하나의 리포트).

• 모든 쓰기 응답에 visualComplete 블록이 실립니다: ok, status(verified/unverified/failed), errorCodes, warnings, suggestedRetry.
• quality 블록으로 게이트를 올립니다(생략 시 transparent = 열림안전만). 예: apply_edits(..., quality="strict") 또는 quality={"mode":"strict","overflowPolicy":"fail","layoutLint":"strict"}.
• 게이트가 실패하면 저장이 보류되고(ok=false), 구조화된 오류 코드(FIELD_OVERFLOW, STALE_LINESEG_DETECTED, VISUAL_COMPLETE_FAILED, …)와 suggestedRetry로 재시도합니다.
• capability handshake가 core/mcp/plugin 버전+해시를 점검하고, skew 시 쓰기를 fail-closed로 차단합니다(mcp_server_health.capability). 진단/우회는 HWPX_MCP_REQUIRE_CAPABILITY=0.

visual_review_required=true는 구조/파일 기반 검증은 통과했지만 렌더링된 시각 레이아웃은 아직 증명되지 않았다는 뜻입니다. 운영 계획서·template-formfit 결과를 최종 제출 가능(submission-ready)으로 주장하려면 열린 문서를 검토해 hwpx.visual-review.v1 증거를 남기고 current.status="observed_pass"여야 합니다.

환경 변수

변수	설명	기본값
HWPX_MCP_MAX_CHARS	텍스트 반환 도구 기본 최대 길이	10000
HWPX_MCP_AUTOBACKUP	1이면 저장 전 .bak 백업 생성	1
HWPX_MCP_ADVANCED	1이면 고급 도구 활성화	0
HWPX_MCP_SANDBOX_ROOT	설정 시 이 root 내부 상대/절대경로만 허용	unset
HWPX_MCP_FETCH_TIMEOUT_SECONDS	URL 기반 HWPX fetch timeout	20.0
HWPX_MCP_QUALITY	전역 기본 저장 게이트 정책(transparent/strict). 도구별 quality가 우선	transparent
HWPX_MCP_REQUIRE_CAPABILITY	0이면 capability skew fail-closed를 끔(진단/전문가용)	1
LOG_LEVEL	로그 레벨	INFO

더 보기

• 실전 사용 사례: docs/use-cases.md
• 스킬 기반 워크플로: docs/skill-first-workflows.md
• 보안·하드닝 가이드: docs/hardening_guide_ko.md
• 종합 테스트 리포트: tests/hwpx_mcp_report_updated.md
• 변경 이력: CHANGELOG.md

테스트

python -m pip install -e ".[test]"   # 테스트 의존성 설치
python -m pytest -q                   # 전체 테스트

License

Apache License 2.0. See LICENSE and NOTICE.

작성자

고규현 — 광교고등학교 정보·컴퓨터 교사

• 이메일: [e-mail]
• GitHub: @airmang