HWPX Automation MCP server

Source update: analyzer delegation and the dependent public-style refactors require python-hwpx >= 6.10.0; the 2026-11 audit fixes changed get_table_map and seven mutates flags (source contract 71622c28a07913d1, delta in docs/tool-contract-delta-source-audit-2026-11.json). This source change does not publish or promote a release. The publication status and last observed coherent stack below remain historical release context.

[!NOTE] 발행이 승인된 7.5.0 후보 (release-approved; 원격 발행 대기): python-hwpx 6.12.0 → python-hwpx-automation 7.5.0 → hwpx-plugin 2.4.0 (71622c28a07913d1). 이 좌표는 src/hwpx_automation/identity.json의 releaseState.candidate와 같아야 합니다(tests/test_audit_identity_docs.py). 공개 트레인: python-hwpx 6.6.0 → python-hwpx-automation 7.3.1 → hwpx-plugin 2.4.0. 공개 좌표는 core·automation PyPI와 plugin GitHub Release·marketplace·실제 marketplace 설치 관찰 후에만 승격합니다.

python-hwpx 엔진 위에서 문서 저작· 양식 채움·시험지 조판·안전한 에이전트 워크플로를 제공하는 응용 계층입니다. 기본 설치는 MCP 없이 Python API와 hwpx CLI로 쓰고, 모델 컨텍스트 프로토콜(MCP) 서버는 필요할 때 [mcp] extra로 더합니다. 한컴오피스도 Windows도 필요 없으므로 파이썬이 도는 ChatGPT 채팅 안에서도 그대로 동작합니다.

	저장소	역할
📦	python-hwpx	HWPX 문서를 읽고·고치고·만드는 순수 파이썬 엔진
🔌	python-hwpx-automation	저작·양식 채움 워크플로, hwpx CLI, 선택형 MCP 서버
🎯	hwpx-plugins	에이전트가 알맞은 도구를 고르도록 돕는 플러그인/스킬 번들

Python 자동화 시작하기

pip install python-hwpx-automation

from hwpx_automation import create_document_from_plan

document = create_document_from_plan(
    {
        "schemaVersion": "hwpx.document_plan.v1",
        "title": "회의 결과",
        "blocks": [{"type": "paragraph", "text": "결정 사항"}],
    }
)
document.save_to_path("meeting-result.hwpx")

python -m hwpx_automation --help와 hwpx help는 같은 task CLI를 실행합니다.

MCP 어댑터 시작하기

pip install "python-hwpx-automation[mcp]"
hwpx-automation-mcp

MCP 클라이언트 설정 파일에 아래 블록 하나면 hwpx 서버를 잡습니다 — Claude Desktop은 claude_desktop_config.json, VS Code는 .vscode/mcp.json(키가 mcpServers 대신 servers), Gemini CLI는 ~/.gemini/settings.json, Cursor·Windsurf는 각 에디터의 MCP 설정 파일입니다.

{
  "mcpServers": {
    "hwpx": {
      "command": "uvx",
      "args": [
        "--from",
        "python-hwpx-automation[mcp]==7.3.1",
        "hwpx-automation-mcp"
      ],
      "env": {
        "HWPX_AUTOMATION_WORKSPACE_ROOTS": "[\"~/Documents\"]"
      }
    }
  }
}

HWPX_AUTOMATION_WORKSPACE_ROOTS에는 문서가 있는 폴더(절대경로 또는 ~)를 지정하세요. Windows는 "[\"C:\\\\hwpx\"]"처럼 씁니다. 값을 비워 두면 GUI 클라이언트는 서버를 시스템 디렉터리에서 띄우기 때문에 모든 문서 경로가 막힙니다 — 처음부터 지정하는 것을 권장합니다. 나머지 옵션은 환경 변수 표를 참고하세요.

비-HWPX 문서(PDF/DOCX/XLSX/HTML/TXT)를 document_to_markdown으로 읽으려면 pip install "python-hwpx-automation[ingest]"로 MarkItDown adapter를 함께 설치합니다. 요구 사항: Python >= 3.10 · python-hwpx >= 6.5.0.

기존 hwpx-mcp-server 배포·import·콘솔·설정 키도 그대로 동작합니다 — 전체 목록과 유지 규칙: 호환 표면

작은 로컬 모델용 프로필

Ollama·Open WebUI의 27B급 모델처럼 도구가 많으면 길을 잃는 환경에서는 hwpx-automation-mcp --profile minimal(또는 HWPX_AUTOMATION_PROFILE=minimal)로 굵은 도구 여섯 개만 띄웁니다: read_outline(id 붙은 짧은 목록) → apply_text_changes({id: 새 글}, 서식 유지·칸 넘침 알림), replace_text, stage_text → create_from_markdown, validate_document. 긴 본문은 도구 인수에 한 번에 싣지 않고 stage_text로 1,000자 안팎씩 나눠 보낸 뒤 draft_id로 넘깁니다. 결과에는 문서 본문을 싣지 않고, 수정본은 기본으로 <이름>.edited.hwpx에 저장합니다.

한컴으로 PDF 렌더하기

한컴(macOS 한컴오피스 한글 또는 Windows 한글 COM)이 있는 컴퓨터에서 문서 하나를 PDF와 쪽 PNG로 렌더합니다. 별도 환경에서 실행하므로 호출하는 쪽의 python-hwpx 고정 버전을 건드리지 않습니다.

uvx --from "python-hwpx-automation[oracle]==7.5.0" \
  hwpx render-pdf in.hwpx out.pdf --png out/page --json

JSON 결과·종료 코드·플랫폼 요구 사항: render-pdf

무엇을 하나

기본 모드에서 다수의 HWPX 도구를 제공하며, 고급 모드(HWPX_AUTOMATION_ADVANCED=1)에서 점검·검증용 도구가 추가됩니다.

• 읽기·탐색 — get_document_info, get_document_map(아웃라인·표 지도·앵커를 한 호출로), find_text (저장하지 않음)
• 검색·치환·편집 — search_and_replace, apply_document_commands(이종 편집 원자 적용·dry-run·롤백·멱등키), add_tracked_edit(변경 추적)
• 표·양식 채움 — analyze_form_fill → apply_form_fill → verify_form_fill 바이트 보존 트랜잭션, table_compute(합계·소계)
• 문서 생성·공문 — 선언형 create_document_from_plan, inspect_official_document_style(행정 규정 lint), mail_merge
• 서식·그림·생성기 — set_paragraph_format·set_page_setup, insert_picture, 사진대지·명패·조직도
• 프리뷰·추출·복구·진단 — render_preview(HTML/PNG 자기검증), hwpx_to_markdown, repair_hwpx, mcp_server_health

자세한 내용: 사용 사례 · 스킬 우선 워크플로

안전하게 쓰는 법

처음부터 모든 도구를 외울 필요는 없습니다. 기존 문서 수정은 조회·대상 확정·보존 저장·검증 안내를, 새 문서는 document-plan을 먼저 봅니다. 보통 이렇게 흘러갑니다.

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_document_commands)을 적용한 뒤 다시 읽어 확인하고, 검토가 끝난 사본을 전달합니다.

핵심은 copy first · smallest edit · re-read after edits입니다. 수정 도구는 호출 즉시 저장되므로 검토용 작업은 반드시 사본에서 하세요.

모델은 operation/plan만 보내고 raw XML을 직접 편집하지 않습니다. 일반 저장 경로는 python-hwpx의 단일 SavePipeline 게이트를 통과해 무결성·XML·OPC/ID· 열림안전을 검사하고, 게이트가 실패하면 아무것도 쓰지 않습니다. capability handshake는 core/automation/plugin 버전+해시 skew를 fail-closed로 차단합니다. 보안 상세: 하드닝 가이드 · 옛 이름과의 호환 식별자: 호환 표면

위치 계약 — paragraph_index는 본문 직속 문단의 0-based 인덱스입니다. 표 안 문단은 여기 섞지 않고 {"kind":"table_cell_paragraph","table_index":0,"row":0,"col":1,"cell_paragraph_index":0} 같은 location 객체로 지정하며, find_text가 반환한 값을 그대로 넘길 수 있습니다. get_table_map은 기본(detail="compact")으로 실제 칸만 한 번씩 싣고(병합은 row_span/col_span) 위치는 응답의 cell_paragraph_location 틀에 table_index·row·col을 넣어 만듭니다. 칸마다 location이 든 이전 형태는 detail="full"로 받습니다.

환경 변수

변수	설명	기본값
HWPX_AUTOMATION_WORKSPACE_ROOTS	허용할 workspace 절대경로의 JSON 배열(복수 root 지원). 상대경로는 첫 root 기준	unset → 프로세스 cwd. degenerate cwd는 WORKSPACE_ROOT_INVALID로 거부
HWPX_AUTOMATION_MAX_CHARS	텍스트 반환 도구 기본 최대 길이	10000
HWPX_AUTOMATION_AUTOBACKUP	1이면 저장 전 .bak 백업 생성	1
HWPX_AUTOMATION_ADVANCED	1이면 고급 도구 활성화	0
HWPX_AUTOMATION_PROFILE	minimal이면 작은 로컬 모델용 도구 6개만 제공(--profile과 같음)	full
HWPX_AUTOMATION_FETCH_TIMEOUT_SECONDS	URL 기반 HWPX fetch timeout	20.0
HWPX_AUTOMATION_ALLOW_PRIVATE_NETWORK	1이면 신뢰된 사설/루프백 HTTPS 대상 허용. 링크로컬·metadata·예약 주소는 계속 차단	0
HWPX_AUTOMATION_QUALITY	전역 기본 저장 게이트 정책(transparent/strict). 도구별 quality가 우선	transparent
HWPX_AUTOMATION_REQUIRE_CAPABILITY	0이면 capability skew fail-closed를 끔(진단/전문가용)	1
HWPX_AUTOMATION_WORKFLOW_STORE	durable workflow SQLite 경로. 기존 HWPX_WORKFLOW_STORE보다 우선	기존 6.x 상태 경로
LOG_LEVEL	로그 레벨	INFO

동일 suffix의 기존 HWPX_MCP_* 키는 fallback으로 유지되며, 두 키가 함께 있으면 HWPX_AUTOMATION_*이 우선합니다. render·workflow·oracle·plugin 연동용 보존 키 전체 목록과 workflow DB 경로 규칙은 호환 표면에 있습니다.

경로는 기본적으로 workspace 밖 traversal과 symlink escape를 거부하고, URL 입력은 HTTPS·공개 IP만 허용합니다. 원자 rename을 제공하지 않는 호스트의 동시성 주의사항은 하드닝 가이드를 보세요.

기여하기

good first issue · 마일스톤 · Discussions · CONTRIBUTING · CHANGELOG

python -m pip install -e ".[test]"   # 테스트 의존성
python -m pytest -q                   # 전체 테스트
python scripts/run_conformance.py run \
  --tier structural --check tests/conformance/golden/structural.json

감사의 말

코어 라이브러리 python-hwpx 위에서 동작하며, 아래 공개 표준·프로젝트에 빚지고 있습니다.

• OWPML — 개방형 워드프로세서 마크업 언어 (KS X 6101) — HWPX가 기반하는 한국 산업 표준
• hancom-io/hwpx-owpml-model — OWPML 요소 구조 참조 모델 · neolord0/hwpxlib — 오라클 샘플 코퍼스
• edwardkim/rhwp — 멱등성·검증 게이트 설계 영감

License · Maintainer

Apache-2.0 (LICENSE · NOTICE) — Kohkyuhyun @airmang · kokyuhyun@hotmail.com