jw-hwp-mcp

HWP 5.0 / HWPX 문서를 읽고 쓰는 Rust 기반 MCP (Model Context Protocol) 서버. Claude Desktop, Claude Code 등 MCP 클라이언트에 붙여서 AI가 HWP 파일을 조회하거나 새 HWPX 파일을 생성할 수 있다.

기능

13개 MCP 도구
- 읽기 (7개):
  - hwp_extract_text — 전체/섹션별 순수 텍스트 추출
  - hwp_get_metadata — 제목/작성자/생성·수정일시 등 문서 요약
  - hwp_get_structure — 섹션 → 문단 트리 (paragraph/table/image/... 분류)
  - hwp_list_tables — 표 목록 (id, 행·열 수)
  - hwp_get_table — 표 내용 (셀별 텍스트 + 병합 정보)
  - hwp_get_paragraph — 문단 텍스트 + 정규화된 글자/문단 서식 + 각주/수식/이미지 참조
  - hwp_list_assets — 문서 내 이미지·바이너리 자산 카탈로그 (id, 파일명, 포맷, 크기)
- 쓰기 (6개, HWPX 전용):
  - hwp_create_document — 새 HWPX 문서 생성 (메모리), document_id 반환
  - hwp_add_paragraph — 문단 추가 (굵게/기울임/밑줄/크기/색상/정렬 지원)
  - hwp_set_text — 기존 문단 텍스트 교체
  - hwp_add_table — 표 추가 (행/열 수, 셀 텍스트)
  - hwp_delete_element — 문단 또는 표 삭제
  - hwp_save — 메모리의 문서를 .hwpx 파일로 저장 (한글 Office 호환, v0.1.1+)
폰트/스타일 이름 해석, 각주/미주 본문, 수식 스크립트 추출 지원
배포용(distributed) HWP 복호화 지원 — AES-128-ECB + pyhwp 호환 키 유도
관대 모드 — 알 수 없는 레코드는 스킵하고 warnings 배열로 누적
stdio 전송 — 단일 실행 바이너리, Claude Desktop/Code에 바로 연결

제한 사항

HWPX 쓰기 지원 — hwp_create_document → hwp_add_paragraph / hwp_add_table → hwp_save 워크플로로 새 .hwpx 파일 생성 가능. HWP 5.0 바이너리 쓰기는 미지원.
HWPX (XML 기반) 지원 — 바이너리 HWP 5.0와 동일한 MCP 도구들이 두 포맷 모두에서 동작합니다. jw_hwp_core::open() 이 파일 시그니처를 자동 감지합니다.
이미지/OLE/각주 등 고급 콘텐츠는 structure에서 unsupported 로만 표시.
암호(password) 설정된 HWP는 미지원. 배포용(distribution)은 지원.

설치

세 가지 방법 중 하나를 선택하면 된다.

방법 A. 프리빌드 바이너리 다운로드 (가장 간단)

GitHub Releases 에서 본인 OS/아키텍처용 아카이브를 내려받는다.

플랫폼	아카이브 이름 예시
Linux x86_64	`jw-hwp-mcp-0.1.0-x86_64-unknown-linux-gnu.tar.gz`
macOS Apple Silicon	`jw-hwp-mcp-0.1.0-aarch64-apple-darwin.tar.gz`
macOS Intel	`jw-hwp-mcp-0.1.0-x86_64-apple-darwin.tar.gz`
Windows x86_64	`jw-hwp-mcp-0.1.0-x86_64-pc-windows-msvc.zip`

각 아카이브에는 실행 파일(jw-hwp-mcp 또는 jw-hwp-mcp.exe), README.md, LICENSE, CHANGELOG.md 가 들어 있다. 같이 올라오는 .sha256 파일로 무결성 검증 가능.

# Linux/macOS 예시
tar -xzf jw-hwp-mcp-0.1.0-x86_64-unknown-linux-gnu.tar.gz
cd jw-hwp-mcp-0.1.0-x86_64-unknown-linux-gnu
./jw-hwp-mcp --help    # 동작 확인 (stdio 서버라 바로 종료됨)

방법 B. `cargo install` 로 crates.io 에서 바로 설치

Rust 툴체인이 이미 있으면 한 줄로 끝난다.

cargo install jw-hwp-mcp
# 바이너리는 ~/.cargo/bin/jw-hwp-mcp (Linux/macOS) 또는
#           %USERPROFILE%\.cargo\bin\jw-hwp-mcp.exe (Windows)

방법 C. 소스에서 빌드

# Rust 설치 (이미 있으면 생략)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
. "$HOME/.cargo/env"

# 복제 + 빌드
git clone https://github.com/polka306/jw-hwp-mcp.git
cd jw-hwp-mcp
cargo build --release -p jw-hwp-mcp

# 결과 바이너리: ./target/release/jw-hwp-mcp

Claude Desktop / Claude Code 등록 (Linux/macOS)

MCP 설정에 추가:

{
  "mcpServers": {
    "hwp": {
      "command": "/absolute/path/to/jw-hwp-mcp"
    }
  }
}

command 값은 위 방법 A/B/C 로 얻은 실행 파일의 절대 경로.

설치 (Windows)

가장 간단한 방법 — 프리빌드 `.exe` 다운로드

GitHub Releases 에서 jw-hwp-mcp-<version>-x86_64-pc-windows-msvc.zip 내려받기.
압축 해제. 원하는 경로에 두면 된다. 예: C:\Tools\jw-hwp-mcp\.
Claude Code MCP 설정에 등록 (PowerShell):
```
claude mcp add hwp "C:\Tools\jw-hwp-mcp\jw-hwp-mcp.exe"
```
claude mcp add 가 없으면 설정 파일 (%USERPROFILE%\.claude\mcp.json 또는 Claude Desktop config) 에 직접 추가:
```
{
  "mcpServers": {
    "hwp": {
      "command": "C:\\Tools\\jw-hwp-mcp\\jw-hwp-mcp.exe"
    }
  }
}
```
JSON에서 백슬래시는 \\ 로 이스케이프.
Claude Code / Desktop 재시작.

`cargo install` (Rust 툴체인 있을 때)

cargo install jw-hwp-mcp
# 바이너리: %USERPROFILE%\.cargo\bin\jw-hwp-mcp.exe

소스 빌드 — Claude Code 자동화 프롬프트

Rust 툴체인 설치부터 MCP 등록까지 Claude Code 가 직접 해주도록 하려면, Windows 의 Claude Code 안에서 아래 프롬프트를 통째로 붙여넣으면 된다.

HWP MCP 서버를 설치하고 이 Claude Code에 등록해줘.

## 작업 내용

1. Rust 툴체인 확인 — `rustc --version` 실행. 없으면 https://win.rustup.rs/x86_64 에서 rustup-init.exe 다운로드 후 기본 옵션(toolchain: stable, profile: default)으로 설치. 설치 후 새 셸에서 PATH 반영 확인.

2. 작업 디렉토리 `%USERPROFILE%\dev` 생성(없으면) 후 이동.

3. 저장소 복제:
   git clone https://github.com/polka306/jw-hwp-mcp.git
   cd jw-hwp-mcp

4. 릴리스 빌드:
   cargo build --release -p jw-hwp-mcp

   결과 바이너리: `%USERPROFILE%\dev\jw-hwp-mcp\target\release\jw-hwp-mcp.exe`
   처음 빌드는 수 분 소요 (AES, CFB, flate2 등 의존성 컴파일).

5. Claude Code MCP 설정에 hwp 서버 등록. `claude mcp add` 명령이 있으면:
   claude mcp add hwp "C:\Users\<사용자명>\dev\jw-hwp-mcp\target\release\jw-hwp-mcp.exe"

   없으면 설정 파일 (`%USERPROFILE%\.claude\mcp.json` 또는 Claude Desktop의 config) 에 직접 추가:

   {
     "mcpServers": {
       "hwp": {
         "command": "C:\\Users\\<사용자명>\\dev\\jw-hwp-mcp\\target\\release\\jw-hwp-mcp.exe"
       }
     }
   }

   `<사용자명>`은 실제 Windows 계정명. 백슬래시는 JSON에서 이스케이프(`\\`).

6. Claude Code 재시작 후 사용 가능한 도구 확인. 13개가 보여야 함:
   - hwp_extract_text, hwp_get_metadata, hwp_get_structure
   - hwp_list_tables, hwp_get_table, hwp_get_paragraph, hwp_list_assets
   - hwp_create_document, hwp_add_paragraph, hwp_set_text
   - hwp_add_table, hwp_delete_element, hwp_save

7. 검증: 임의의 .hwp 파일 절대경로로 hwp_get_metadata 호출해서 결과 확인.

## 주의사항

- HWP 파일 경로는 절대경로 사용 (예: C:\Users\me\Documents\test.hwp).
- 빌드 중 "link.exe not found" 에러가 나면 Visual Studio Build Tools (C++ workload) 설치 필요. https://visualstudio.microsoft.com/visual-cpp-build-tools/ 에서 "Desktop development with C++" 설치 후 재시도.

각 단계마다 진행 상황을 간단히 보고하고, 에러 발생 시 즉시 중단하고 알려줘.

Windows 관련 세부 사항(환경 변수, PATH, Visual Studio Build Tools 등) 은 docs/WINDOWS_SETUP.md 참고.

사용 예시

Claude에게:

"C:\Users\me\Documents\report.hwp 파일의 제목과 작성자를 알려줘"

→ Claude가 hwp_get_metadata 호출 → 결과 반환.

"이 HWP 파일에 있는 모든 표를 목록으로 보여주고, 첫 번째 표의 내용을 읽어줘"

→ hwp_list_tables + hwp_get_table 순차 호출.

"새 HWPX 파일을 만들고, 제목 문단(굵게, 16pt)과 본문 2개, 2x3 표를 넣어서 ~/report.hwpx로 저장해줘"

→ hwp_create_document → hwp_add_paragraph x3 → hwp_add_table → hwp_save 순차 호출.

업데이트

설치 방법에 따라:

방법 A (프리빌드 바이너리): 새 릴리스 아카이브 다운로드 → 기존 실행 파일 교체.
방법 B (cargo install): cargo install jw-hwp-mcp --force

방법 C (소스 빌드):

cd jw-hwp-mcp
git pull
cargo build --release -p jw-hwp-mcp

어느 쪽이든 바이너리 교체 후 Claude Code / Desktop 재시작.

개발

cargo test --workspace    # 전체 테스트 (80개)
cargo test -p jw-hwp-core --lib     # 핵심 라이브러리 유닛
cargo test -p jw-hwp-core --test golden   # 실제 .hwp 샘플 스냅샷
cargo clippy --workspace --all-targets -- -D warnings    # CI 동등

기술 스택

Rust 2021, stdio MCP 전송 (rmcp)
cfb — Compound File Binary 컨테이너
flate2 — zlib deflate
aes — 배포용 HWP 복호화
insta — 골든 스냅샷 테스트

구현 상세는 docs/superpowers/plans/ 아래 Plan 1–9 문서 참고. 변경 이력은 CHANGELOG.md.

라이선스

MIT

jw-hwp-core 0.1.2