hwpx-mcp-server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Source update: analyzer delegation and the dependent public-style refactors require
python-hwpx >= 6.10.0; the 2026-11 audit fixes changedget_table_mapand sevenmutatesflags (source contract71622c28a07913d1, delta indocs/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.
발행이 승인된 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 채팅 안에서도 그대로 동작합니다.
저장소 | 역할 | |
📦 | HWPX 문서를 읽고·고치고·만드는 순수 파이썬 엔진 | |
🔌 | 저작·양식 채움 워크플로, | |
🎯 | 에이전트가 알맞은 도구를 고르도록 돕는 플러그인/스킬 번들 |
Python 자동화 시작하기
pip install python-hwpx-automationfrom 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를 실행합니다.
Related MCP server: hwpx-mcp-server
MCP 어댑터 시작하기
pip install "python-hwpx-automation[mcp]"
hwpx-automation-mcpMCP 클라이언트 설정 파일에 아래 블록 하나면 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로 넘깁니다.
create_from_markdown의 byline(200자까지)은 제목 아래 오른쪽에 쓰는 부서·날짜 줄입니다.
from_markdown이 byline을 받지 않는 python-hwpx(6.12.0까지)에서는 문서를 만들지 않고
DEPENDENCY_MISSING으로 답합니다.
결과에는 문서 본문을 싣지 않고, 수정본은 기본으로 <이름>.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 --jsonJSON 결과·종료 코드·플랫폼 요구 사항: 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을 먼저 봅니다. 보통 이렇게 흘러갑니다.
읽기 —
get_document_info→get_document_outline/get_document_text→find_text,get_table_map으로 필요한 부분만 파악합니다. (저장하지 않음)안전 수정 —
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"로 받습니다.
환경 변수
변수 | 설명 | 기본값 |
| 허용할 workspace 절대경로의 JSON 배열(복수 root 지원). 상대경로는 첫 root 기준 | unset → 프로세스 cwd. degenerate cwd는 |
| 텍스트 반환 도구 기본 최대 길이 |
|
|
|
|
|
|
|
|
|
|
| URL 기반 HWPX fetch timeout |
|
|
|
|
| 전역 기본 저장 게이트 정책( |
|
|
|
|
| durable workflow SQLite 경로. 기존 | 기존 6.x 상태 경로 |
| 로그 레벨 |
|
동일 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
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Online office suite for AI agents: edit docs, sheets, slides and PDFs in browser or via MCP.
Convert, create and edit Word, PowerPoint, Excel and PDF documents from any AI agent.
An agent-first office suite Claude & ChatGPT read and write over one MCP URL.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Related MCP Servers
- AlicenseAqualityNot gradedmaintenanceEnables reading, editing, and creating Korean HWPX documents through python-hwpx library. Supports document creation, paragraph/table/image insertion, metadata management, and workspace-restricted file operations with automatic backup functionality.8MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server for reading, editing, and creating Hangul Word Processor (.hwpx) files. It enables users to extract text, perform find-and-replace operations, and modify font styles through automated XML patching.35 npmMIT
- AlicenseAqualityCmaintenanceAn MCP server for reading, writing, and managing Korean Hangul Word Processor (HWP/HWPX) files. It allows users to extract content, fill templates, and create new documents directly through AI assistants.34369 npm108MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for reading and writing HWP/HWPX (Korean Hangul word processor) files, enabling document reading, text extraction, table extraction, image extraction, template filling, text replacement, and creation of new documents.MIT