Hwpx Mcp Server

Hwpx Mcp Server

What is Hwpx Mcp Server about?

Hwpx Mcp Server provides a standard MCP endpoint that exposes a rich set of tools for manipulating HWPX (Hancom Word Processor) documents. It sits on top of the python‑hwpx core library and lets AI‑driven clients perform reading, searching, editing, form‑filling, validation, and document generation in a stateless, file‑based workflow.

How to use Hwpx Mcp Server?

1. Install – pip install hwpx-mcp-server (or use the uvx installer: uvx hwpx-mcp-server).
2. Start the server – simply run the hwpx-mcp-server command.
3. Configure an MCP client – add a block like the example below to the client’s configuration file (Claude Desktop, VS Code, Gemini CLI, etc.):

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

4. Call tools – use the MCP‑defined methods such as get_document_text, search_and_replace, add_table, apply_edits, etc., passing the target file name in each request.

Key features of Hwpx Mcp Server

• Cross‑platform pure‑Python execution – no Hancom software required.
• Stateless tool calls – every operation includes the filename parameter, making it safe for concurrent use.
• Rich toolset covering:
  • Document inspection (get_document_info, get_document_outline, get_table_map).
  • Text search & replace (find_text, search_and_replace).
  • Structured editing (add_heading, add_paragraph, apply_edits with atomic rollback).
  • Form‑filling and table manipulation with byte‑preserving guarantees.
  • Declarative document creation from OWPML‑based plans.
  • Bulk operations (mail‑merge, diff, official‑document linting).
  • Preview & extraction (render_preview, hwpx_to_markdown).
  • Advanced inspection tools when HWPX_MCP_ADVANCED=1 is set.
• Safety mechanisms – automatic backups, idempotency keys, concurrency guards, and visual‑complete quality gates that reject unsafe writes.
• Extensible via plugins – official hwpx-plugins bundle can launch the server in development mode.

Use cases of Hwpx Mcp Server

• AI‑assisted document drafting – Claude Desktop or VS Code agents generate contracts, reports, or exam papers directly in HWPX format.
• Batch form filling – populate large numbers of standardized HWPX templates from CSV/JSON data.
• Document audit & compliance – run linting tools (inspect_official_document_style, inspect_reference_consistency) on government or corporate paperwork.
• Legacy document migration – ingest PDFs/DOCX and convert to markdown or JSON for further processing via the [ingest] extra.
• Automated proofreading – retrieve document text, let LLMs suggest edits, then apply them atomically with apply_edits.
• Continuous integration – include hwpx-mcp-server in CI pipelines to validate generated HWPX assets before publishing.

FAQ

Q: Do I need Hancom Word Processor installed? A: No. All operations are performed by the pure‑Python python‑hwpx engine.

Q: Which operating systems are supported? A: Windows, macOS, and Linux.

Q: How are changes persisted? A: Mutating tools write directly to the supplied file. Use copy_document first to work on a safe copy, and rely on the built‑in backup (.bak) for undo.

Q: Can I limit the server to a specific directory? A: Yes. Set HWPX_MCP_SANDBOX_ROOT to restrict file access to that path.

Q: What if I need advanced validation? A: Enable the advanced mode by setting HWPX_MCP_ADVANCED=1; additional inspection and edit‑planning tools become available.

Q: How do I control the amount of text returned? A: Adjust HWPX_MCP_MAX_CHARS; the default is 10 000 characters per call.

Q: Is there a health check endpoint? A: Yes. Call mcp_server_health to get version, capability handshake, and self‑diagnostics.

---

🧩 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                   # 전체 테스트

감사의 말

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

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

License

Apache License 2.0. See LICENSE and NOTICE.

작성자

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

• 이메일: kokyuhyun@hotmail.com
• GitHub: @airmang