jw-hwp-core 0.1.2

# 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](https://github.com/polka306/jw-hwp-mcp/releases/latest) 에서 본인 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` 파일로 무결성 검증 가능.

```bash
# 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 툴체인이 이미 있으면 한 줄로 끝난다.

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

### 방법 C. 소스에서 빌드

```bash
# 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 설정에 추가:

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

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

## 설치 (Windows)

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

1. [GitHub Releases](https://github.com/polka306/jw-hwp-mcp/releases/latest) 에서 `jw-hwp-mcp-<version>-x86_64-pc-windows-msvc.zip` 내려받기.
2. 압축 해제. 원하는 경로에 두면 된다. 예: `C:\Tools\jw-hwp-mcp\`.
3. Claude Code MCP 설정에 등록 (PowerShell):

   ```powershell
   claude mcp add hwp "C:\Tools\jw-hwp-mcp\jw-hwp-mcp.exe"
   ```

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

   ```json
   {
     "mcpServers": {
       "hwp": {
         "command": "C:\\Tools\\jw-hwp-mcp\\jw-hwp-mcp.exe"
       }
     }
   }
   ```

   JSON에서 백슬래시는 `\\` 로 이스케이프.

4. Claude Code / Desktop 재시작.

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

```powershell
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`](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 (소스 빌드)**:
  ```bash
  cd jw-hwp-mcp
  git pull
  cargo build --release -p jw-hwp-mcp
  ```

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

## 개발

```bash
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`](CHANGELOG.md).

## 라이선스

MIT