Skip to content
Projects

airmang/python-hwpx-automation

View on GitHub

airmang/python-hwpx-automation has 69 GitHub stars and 21 forks. Star changes are not measured yet. Last checked 2026-11-18 07:05 UTC. Last push 2026-11-11.

How these counts are measured

Measured star growth

in 24h
Update delayed
in 7 days
Collecting history
in 15 days
Collecting history
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

MCP server for AI agents to read, edit, inspect, and validate local HWPX documents.

AI

README.md

Original

python-hwpx-automation

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

PyPI Downloads Python Tests License

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 위에서 동작하며, 아래 공개 표준·프로젝트에 빚지고 있습니다.

License · Maintainer

Apache-2.0 (LICENSE · NOTICE) — Kohkyuhyun @airmang · [email protected]