Python Hwpx Automation

python-hwpx-automation

<strong>HWPX 저작·양식 채움·업무 워크플로를 위한 Python 자동화 계층</strong>

[!NOTE] 발행이 승인된 7.3.4 후보 (release-approved; 원격 발행 대기): python-hwpx 6.6.0 → python-hwpx-automation 7.3.4 → hwpx-plugin 2.4.0 (5e5c23651f92785a). 공개 트레인: 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·콘솔·설정 키도 그대로 동작합니다 — 전체 목록과 유지 규칙: 호환 표면

한컴으로 PDF 렌더하기

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

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

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

무엇을 하나

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