Skip to main content
Glama

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) 설정은 에이전트별 설정 안내, 문제 해결은 트러블슈팅을 참고하세요.

Related MCP server: HWPX MCP Server

안전한 쓰기(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를 확인하세요.

Available Tools

14 tools
hwp_diff문서 텍스트 비교A
Read-only

두 문서 파일(file_path_a vs file_path_b) 또는 현재 문서와 스냅샷(snapshot_id) 간의 텍스트 unified diff 를 반환합니다. file_path_a는 절대 경로 권장.

Inputs: file_path_a (required), password, file_path_b, snapshot_id.

hwp_fill_cells표 셀 채우기A
Destructive

표의 셀 값을 일괄 채웁니다. 각 항목은 좌표 기준({'row': 0, 'col': 1, 'text': '값'}) 또는 라벨 기준({'label': '성명', 'text': '홍길동', 'direction': 'right'|'below'})을 지원합니다. 라벨 기준에서 표 번호('table' 또는 table_index)를 생략하면 모든 표를 앞에서부터 찾아 첫 일치를 씁니다. 좌표 기준에서 표 번호를 생략하면 0번 표입니다. SafeWriter를 통해 스냅샷 백업 및 무손실 검증 후 원자 교체합니다. file_path는 절대 경로 권장.

Inputs: cells (required), file_path (required), force, password, +3 more.

hwp_fill_fields누름틀 필드 채우기C
Destructive

문서 내 누름틀(필드) 값을 이름 기준으로 채웁니다. SafeWriter를 경유합니다. file_path는 절대 경로 권장.

Inputs: data (required), file_path (required), force, password, +2 more.

hwp_get_text문서 본문 추출B
Read-only

HWP/HWPX 문서의 본문 텍스트를 추출합니다. format='text' 또는 'markdown'을 지원합니다. file_path는 절대 경로 권장.

Inputs: file_path (required), page, format, password, +1 more.

hwp_history스냅샷 히스토리 조회A
Read-only

문서의 SafeWriter 스냅샷 히스토리(.hwp-mcp-history) 목록을 최신순으로 조회합니다. file_path는 절대 경로 권장.

Inputs: file_path (required).

hwp_info문서 정보 조회B
Read-only

HWP/HWPX 문서의 메타데이터(형식, 페이지 수, 문단 수, 글꼴, SHA-256 해시 등)를 조회합니다. file_path는 절대 경로 권장.

Inputs: file_path (required), password.

hwp_insert_text텍스트 삽입C
Destructive

지정한 섹션/문단/문자 오프셋 위치에 텍스트를 삽입합니다. SafeWriter를 경유합니다. file_path는 절대 경로 권장.

Inputs: text (required), file_path (required), force, offset, +4 more.

hwp_render_page페이지 이미지 렌더링A

문서 페이지를 PNG 또는 SVG 이미지 파일로 렌더링하여 저장 경로를 반환합니다(시각 확인용). page는 0부터 시작하며, -1이면 전체 페이지를 렌더합니다. file_path는 절대 경로 권장.

Inputs: file_path (required), page, format, output_dir.

hwp_replace_text텍스트 일괄 치환C
Destructive

문서 본문 및 표 셀 내의 텍스트를 찾아 일괄 치환합니다. SafeWriter를 경유합니다. file_path는 절대 경로 권장.

Inputs: find (required), replace (required), file_path (required), force, +3 more.

hwp_restore스냅샷 복원A
Destructive

hwp_history에서 확인한 snapshot_id 로 문서를 복원합니다. 복원 전 현재 파일도 스냅샷으로 백업한 뒤 원자 교체합니다. file_path는 절대 경로 권장.

Inputs: file_path (required), snapshot_id (required), force, expected_sha256.

hwp_rhwp_callrhwp 도구 직접 호출B
Destructive

rhwp 가 제공하는 180여 개 전체 도구 중 하나를 직접 호출하는 탈출구입니다. output 인자를 받는 쓰기 도구는 SafeWriter를 경유해 임시 파일 출력·검증·원자 교체를 수행합니다. file_path는 절대 경로 권장.

Inputs: file_path (required), tool_name (required), force, is_write, +3 more.

hwp_run_plan편집 계획 실행B
Destructive

rhwp 선언적 편집 계획서(plan JSON)를 일괄 실행합니다. input/output 경로는 SafeWriter가 안전하게 바인딩합니다. file_path는 절대 경로 권장.

Inputs: plan (required), file_path (required), force, allow_loss, +1 more.

hwp_table_view문서 표 조회A
Read-only

문서 내 표(Table)의 행/열 크기, 병합 정보, 각 셀의 좌표(row, col) 및 텍스트를 반환합니다. table_index(0부터 시작)로 특정 표만 조회할 수 있습니다. file_path는 절대 경로 권장.

Inputs: file_path (required), password, table_index.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 14 tools

    Disambiguation4/5

    The core read tools (info, get_text, search, table_view) and write tools (replace_text, insert_text, fill_cells, fill_fields) target clearly distinct resources or actions. However, hwp_rhwp_call and hwp_run_plan are broad meta-tools that can perform any edit, creating some genuine overlap with the individual edit tools (e.g., an agent may wonder whether to replace text directly or via a plan/rhwp call).

    Naming Consistency5/5

    Every tool uses a consistent hwp_ prefix with snake_case naming throughout (hwp_get_text, hwp_fill_cells, hwp_replace_text, etc.). The verb/noun style is uniform and predictable across the whole set.

    Tool Count5/5

    14 tools is well-scoped for a document editing server, with each tool covering a distinct lifecycle operation (read, edit, render, history/restore). No tool feels redundant or padding.

    Completeness4/5

    Covers a strong surface: metadata, text extraction, search, table inspection, cell/field filling, text replace/insert, render, diff, history, and restore. Minor gaps exist (no dedicated table creation or content deletion), but hwp_rhwp_call and hwp_run_plan provide escape-hatch coverage for those cases.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      Not graded
      maintenance
      Enables 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.
      8
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI models to read, create, and edit Korean HWPX documents with advanced support for tables, paragraphs, styles, and images. It features enhanced stability through atomic file writing and smart layout recalculation to prevent document corruption.
      34
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to perform safe, semantic edits on Markdown and DOCX documents through a normalized model with staging, diff review, and stale-edit protection.
      13
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to edit open HWP/HWPX documents through a single async JavaScript API, performing text, paragraph, table, formatting, and structural changes with save verification, and to render page snapshots or PDFs.
      MIT