hwp-edit-mcp
AI 에이전트가 HWP·HWPX 문서를 고칠 때 원본을 지키는 안전한 쓰기(해시 충돌 검사, 자동 스냅샷, 재열기 검증, 원자 교체), 라벨 기반 표 채우기, 히스토리·복원·비교를 제공하는 MCP 서버입니다.
빠른 시작
uvx hwp-edit-mcp
첫 실행 시 rhwp 실행 파일을 캐시에 자동으로 내려받습니다. Claude Code 등록 예:
claude mcp add -s user hwp -- uvx hwp-edit-mcp
다른 에이전트(Claude Desktop, Codex, Grok CLI, Antigravity, Gemini CLI, OpenCode, Cursor, VS Code) 설정은 에이전트별 설정 안내, 문제 해결은 트러블슈팅을 참고하세요.
안전한 쓰기(SafeWriter)
모든 쓰기 도구는 SafeWriter 트랜잭션을 거칩니다.
- 해시 충돌 검사: 직전에 읽은 SHA-256 또는
expected_sha256과 현재 파일 해시를 대조해 외부 편집기 수정과의 충돌을 막습니다(force=True로 우회 가능). - 자동 스냅샷: 수정 직전 원본을 문서 폴더의
.hwp-mcp-history/<파일명>/에 최대 50개까지 보관합니다. - 임시 파일 격리 및 재열기 검증: 같은 폴더의 임시 파일에 먼저 쓴 뒤 손실 보고(
lossCount)가 없는지 확인하고,rhwp로 다시 열어 페이지 수 급감이나 파손을 검사합니다(allow_loss=True로 허용 가능). - 원자 교체:
os.replace로 원본을 교체하며, Windows 파일 잠금(PermissionError) 시 짧게 대기하며 재시도합니다.
제공 도구 (14개)
| 이름 | 하는 일 | 구분 |
|---|---|---|
hwp_info |
문서 메타데이터(형식, 페이지 수, 문단 수, 글꼴, SHA-256) 조회 | 읽기 |
hwp_get_text |
본문 텍스트 추출 (text / markdown, 페이지·길이 지정) |
읽기 |
hwp_search |
문자열 검색 및 페이지·문맥·표 셀 좌표 반환 | 읽기 |
hwp_table_view |
표 크기, 병합 정보, 셀 좌표·텍스트 조회 (table_index) |
읽기 |
hwp_fill_cells |
좌표(row, col) 또는 라벨(label, right/below)로 표 셀 채우기 |
쓰기 |
hwp_replace_text |
본문·표 셀 텍스트 일괄 치환 | 쓰기 |
hwp_fill_fields |
누름틀(필드) 이름 기준 값 채우기 | 쓰기 |
hwp_insert_text |
지정한 섹션·문단·오프셋 위치에 텍스트 삽입 | 쓰기 |
hwp_run_plan |
rhwp 선언적 편집 계획서(plan JSON) 일괄 실행 | 쓰기 |
hwp_render_page |
페이지를 PNG 또는 SVG 이미지로 렌더링 | 읽기 |
hwp_history |
.hwp-mcp-history 스냅샷 목록 최신순 조회 |
읽기 |
hwp_restore |
snapshot_id로 문서 복원 (현재 파일 백업 후 원자 교체) |
쓰기 |
hwp_diff |
두 파일 또는 현재 문서와 스냅샷 간 텍스트 unified diff 비교 | 읽기 |
hwp_rhwp_call |
rhwp 내장 180여 개 도구 직접 호출 (쓰기 도구는 SafeWriter 경유) | 읽기/쓰기 |
CLI 옵션 및 환경변수
| CLI 옵션 | 환경변수 | 기본값 | 설명 |
|---|---|---|---|
--read-only |
HWP_EDIT_READ_ONLY |
비활성 | 쓰기 도구를 등록하지 않고 읽기·검사 도구만 노출 |
--root DIR (반복) |
HWP_EDIT_ROOTS |
제한 없음 | 접근 허용 폴더 지정 (Windows ;, 그 외 : 구분) |
--rhwp-path EXE |
RHWP_EXE |
자동 탐색/다운로드 | 사용할 rhwp 실행 파일 경로 지정 |
install-rhwp |
— | — | rhwp 실행 파일을 미리 내려받아 캐시에 저장 |
| — | HWP_EDIT_MAX_CHARS |
20000 |
도구 응답 최대 문자 수 상한 |
| — | HWP_EDIT_NO_DOWNLOAD |
비활성 | rhwp 자동 내려받기 비활성화 (오프라인 환경용) |
| — | HWP_EDIT_CACHE_DIR |
OS 기본 캐시 | rhwp 캐시 저장 경로 덮어쓰기 |
| — | HWP_EDIT_LOG_FILE |
stderr만 출력 | 서버 로그를 파일에도 기록 |
rhwp와의 관계
rhwp는 mcp-serve 명령으로 저수준 HWP/HWPX 파싱·편집 도구를 제공합니다. hwp-edit-mcp는 rhwp mcp-serve를 상주 하위 프로세스로 감싸면서, 에이전트 실수나 덮어쓰기로부터 문서를 보호하는 SafeWriter(해시 충돌 검사, 스냅샷 백업·복원·diff, 재열기 무손실 검증, 원자 교체), 라벨 기반 표 셀 채우기, 허용 폴더(--root) 및 읽기 전용(--read-only) 가드, 응답 길이 제한(max_chars), 자동 rhwp 설치·캐싱을 더합니다.
감사의 말
jkf87/hwp-mcp를 포크해 시작했고, rhwp 엔진 기반으로 다시 작성했습니다.
라이선스
hwp-edit-mcp는 MIT License로 배포됩니다. 런타임에 사용하는 rhwp의 MIT 라이선스 고지는 NOTICE를 확인하세요.
Metadata
Release files for hwp-edit-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hwp_edit_mcp-0.1.0.tar.gz | 122.2 kB | With provenance | Details for hwp_edit_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hwp_edit_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for hwp_edit_mcp-0.1.0-py3-none-any.whl |
Total release size: 147.7 kB
Release files / hwp_edit_mcp-0.1.0.tar.gz
| Download URL | hwp_edit_mcp-0.1.0.tar.gz |
|---|---|
| Size | 122.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1972cb89c5ab5d41529005fccb4a16bad2559301f8f2c03ca55d145ae7639093
|
|
BLAKE2b-256 checksum How to use checksums |
66f32c7793f26d3e3660c1e1244918ed5ac808f1153a507b899b5311fe7e5761
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logRelease files / hwp_edit_mcp-0.1.0-py3-none-any.whl
| Download URL | hwp_edit_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 25.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2e66ab01ce182485a145a936fab911214b1ac662d62b3e1c8c01b8a4032aba29
|
|
BLAKE2b-256 checksum How to use checksums |
9333447a49b6d71b13fb3950f315d784bcaa3ab347c59d51282ed0afaf169228
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logSecurity for hwp-edit-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for hwp_edit_mcp-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.