Skip to main content

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 트랜잭션을 거칩니다.

  1. 해시 충돌 검사: 직전에 읽은 SHA-256 또는 expected_sha256과 현재 파일 해시를 대조해 외부 편집기 수정과의 충돌을 막습니다(force=True로 우회 가능).
  2. 자동 스냅샷: 수정 직전 원본을 문서 폴더의 .hwp-mcp-history/<파일명>/에 최대 50개까지 보관합니다.
  3. 임시 파일 격리 및 재열기 검증: 같은 폴더의 임시 파일에 먼저 쓴 뒤 손실 보고(lossCount)가 없는지 확인하고, rhwp로 다시 열어 페이지 수 급감이나 파손을 검사합니다(allow_loss=True로 허용 가능).
  4. 원자 교체: 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)

Source distribution for hwp-edit-mcp 0.1.0
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)

Table of built distributions (wheels) for hwp-edit-mcp 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page