Metadata-Version: 2.4
Name: hwpx-mcp-server
Version: 2.15.0
Summary: MCP server for reading, editing, inspecting, and validating local HWPX documents with AI agents.
Author: Kohkyuhyun
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/airmang/hwpx-mcp-server
Project-URL: Issues, https://github.com/airmang/hwpx-mcp-server/issues
Keywords: hwpx,hancom,mcp,model-context-protocol,document-automation,ai-agent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: python-hwpx>=2.23.0
Requires-Dist: pydantic>=2.7
Requires-Dist: anyio>=4.0
Requires-Dist: mcp>=1.14.1
Requires-Dist: modelcontextprotocol>=0.1.0
Provides-Extra: hwp
Requires-Dist: olefile>=0.47; extra == "hwp"
Provides-Extra: http
Requires-Dist: uvicorn>=0.30; extra == "http"
Provides-Extra: oracle
Requires-Dist: python-hwpx[visual]>=2.23.0; extra == "oracle"
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: olefile>=0.47; extra == "test"
Requires-Dist: uvicorn>=0.30; extra == "test"
Dynamic: license-file

<p align="center">
  <h1 align="center">📄 hwpx-mcp-server</h1>
  <p align="center">
    <strong>AI 에이전트가 HWPX 문서를 바로 읽고, 찾고, 채우고, 만들게 하는 MCP 서버</strong>
  </p>
  <p align="center">
    한글 워드프로세서 없이 · 순수 파이썬 · 크로스 플랫폼
  </p>
  <p align="center">
    <a href="https://pypi.org/project/hwpx-mcp-server/"><img src="https://img.shields.io/pypi/v/hwpx-mcp-server?style=flat-square&color=blue" alt="PyPI"></a>
    <a href="https://pypi.org/project/hwpx-mcp-server/"><img src="https://img.shields.io/pypi/pyversions/hwpx-mcp-server?style=flat-square" alt="Python"></a>
    <a href="https://github.com/airmang/hwpx-mcp-server/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License"></a>
    <a href="https://github.com/airmang/hwpx-mcp-server/actions"><img src="https://img.shields.io/github/actions/workflow/status/airmang/hwpx-mcp-server/test.yml?style=flat-square&label=tests" alt="Tests"></a>
  </p>
</p>

---

## 🧩 HWPX Stack (3종)

| 계층 | 레포 | 역할 |
|---|---|---|
| 📦 라이브러리 | [`python-hwpx`](https://github.com/airmang/python-hwpx) | 순수 파이썬 HWPX 파싱·편집·생성 코어 |
| 🔌 MCP 서버 | **[`hwpx-mcp-server`](https://github.com/airmang/hwpx-mcp-server)** | MCP 클라이언트(Claude Desktop, VS Code 등)에서 HWPX 조작 |
| 🎯 에이전트 스킬 | [`hwpx-plugins`](https://github.com/airmang/hwpx-plugins) | 에이전트가 HWPX를 바로 쓰게 해주는 공식 스킬/플러그인 번들 |

---

## 왜 / 무엇을 하나

**hwpx-mcp-server**는 [모델 컨텍스트 프로토콜(MCP)](https://modelcontextprotocol.io) 표준 서버로, [python-hwpx](https://github.com/airmang/python-hwpx) 위에서 HWPX 문서의 **열람·검색·편집·양식채움·생성·추출**을 AI 클라이언트에서 직접 수행하게 합니다.

- **운영체제 무관** — Windows, macOS, Linux에서 동작
- **한글 워드프로세서 불필요** — 순수 파이썬 처리, 서버·CI·로컬 어디서나 같은 흐름
- **AI 연동 중심** — Claude Desktop, VS Code, Gemini CLI 등 MCP 클라이언트와 직접 연결
- **문서 조작을 도구 호출로 표준화** — 읽기·편집·복제·양식채움·검증을 하나의 도구 집합으로 노출
- **stateless 호출** — 도구마다 `filename`을 명시하는 일관된 방식

> **참고** 이 서버는 Open XML 기반 `.hwpx` 포맷을 지원합니다. 바이너리 `.hwp`는 직접 편집 대상이 아닙니다.

## 빠른 시작

### 설치 및 실행

[uv](https://docs.astral.sh/uv/getting-started/installation/) 기준:

```bash
uvx hwpx-mcp-server
```

또는 `pip` 설치 후 실행:

```bash
pip install hwpx-mcp-server
hwpx-mcp-server
```

요구 사항: `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 설정 파일

```json
{
  "mcpServers": {
    "hwpx": {
      "command": "uvx",
      "args": ["hwpx-mcp-server"]
    }
  }
}
```

환경 변수를 넘길 때는 `env` 블록을 추가합니다.

```json
{
  "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/use-cases.md)와 [`docs/skill-first-workflows.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`은 아웃라인·표 지도·누름틀·앵커를 한 호출로 반환(왕복 최소화). (저장하지 않음)
- **🔎 검색·치환** — `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/use-cases.md)
- 스킬 기반 워크플로: [`docs/skill-first-workflows.md`](docs/skill-first-workflows.md)
- 보안·하드닝 가이드: [`docs/hardening_guide_ko.md`](docs/hardening_guide_ko.md)
- 종합 테스트 리포트: [`tests/hwpx_mcp_report_updated.md`](tests/hwpx_mcp_report_updated.md)
- 변경 이력: [`CHANGELOG.md`](CHANGELOG.md)

### 테스트

```bash
python -m pip install -e ".[test]"   # 테스트 의존성 설치
python -m pytest -q                   # 전체 테스트
```

## License

Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

## 작성자

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

- 이메일: [kokyuhyun@hotmail.com](mailto:kokyuhyun@hotmail.com)
- GitHub: [@airmang](https://github.com/airmang)
