# hwpx-mcp

한글 문서(.hwpx)를 만들고 고치고, .hwp를 읽는 MCP 서버입니다. Claude 데스크톱이나 VS Code(Claude Code)에 명령 하나를 등록하면 그 PC에서 바로 씁니다.
네트워크나 다른 컴퓨터는 필요 없습니다.

- 문서 읽기·쓰기: 한글 프로그램 없이 됩니다(Windows·macOS·Linux).
- PDF 변환·쪽 그림·.hwp → .hwpx 변환·실시간 보기 창: 그 PC에 깔린 한글을 씁니다(Windows).

## 할 수 있는 일

| 분야 | 도구 |
|---|---|
| 문서 | `document`(새로 만들기·열기·저장·닫기), `read`(개요·본문·서식·찾기), `xml` |
| 글과 서식 | `text`, `char_format`, `para_format`, `style`, `numbering` |
| 쪽 | `page`(용지·여백·단·머리말/꼬리말·쪽 번호·구역) |
| 개체 | `table`(만들기·병합·나누기·셀 서식·계산식·표 마당), `image`, `shape`, `chart`, `equation`(한글 수식·LaTeX) |
| 참조·양식 | `note`(각주·미주), `link`(하이퍼링크·책갈피·상호 참조), `toc`(차례), `field`(누름틀), `memo`, `track`(변경 추적) |
| 한글 엔진 | `render`(PDF·쪽 그림·검사·쪽 번호 갱신·보기 창), `convert`(.hwp → .hwpx) |

도구 22개의 인자와 동작은 [docs/api-spec.md](docs/api-spec.md)에 있습니다. 파일 경로 인자는 절대 경로로 씁니다.

## 설치

1. [uv](https://docs.astral.sh/uv/)를 한 번 깝니다. Python은 uv가 알아서 받습니다.

   ```
   winget install astral-sh.uv
   ```

   macOS·Linux는 `curl -LsSf https://astral.sh/uv/install.sh | sh`.

2. 쓰는 클라이언트에 등록합니다. 처음 실행할 때 서버가 자동으로 받아 깔립니다(Windows에서는 pywin32 포함).

   **Claude 데스크톱**: 설정 → 개발자 → 설정 편집으로 `claude_desktop_config.json`을 열어 아래를 넣고 앱을 다시 켭니다.

   ```json
   {
     "mcpServers": {
       "hwpx": {
         "command": "uvx",
         "args": ["--from", "git+https://github.com/jun-Bridge/hwpx-mcp", "hwpx-mcp"]
       }
     }
   }
   ```

   **Claude Code(VS Code 확장·터미널)**:

   ```
   claude mcp add hwpx -- uvx --from git+https://github.com/jun-Bridge/hwpx-mcp hwpx-mcp
   ```

3. Claude에게 "바탕화면에 보고서.hwpx를 만들고 제목과 표 하나를 넣어 줘"처럼 말하면 됩니다.

## 한글 엔진

서버는 시작할 때 엔진을 고릅니다.

| 서버가 도는 PC | 엔진 |
|---|---|
| 한글이 깔린 Windows | 로컬: 그 PC의 한글을 씁니다 |
| 그 밖(macOS·Linux·한글 없는 Windows) | 없음: `render`·`convert`만 `E_ENGINE_UNAVAILABLE`, 나머지는 모두 됩니다 |

한글이 깔려 있는데 엔진이 없다고 나오면 한글 COM 등록이 안 된 것입니다. 관리자 명령 프롬프트에서 `Hwp.exe /regserver`를 한 번 실행합니다.
한글이 파일을 열 때마다 접근 허용 창을 띄우면 [windows/README.md](windows/README.md)의 보안 모듈 등록을 따릅니다.

## 설정(선택)

전부 비워 둬도 됩니다. 쓰려면 클라이언트 설정의 `env`에 넣습니다.

| 이름 | 뜻 | 기본값 |
|---|---|---|
| `HWPX_TRACK_AUTHOR` | 변경 추적 작성자 | `Claude` |
| `HWPX_DEFAULT_PROFILE` | 새 문서의 한글 버전 프로필 | 들어 있는 기본 프로필 |
| `HWPX_TABLE_PRESET_DIR` | 표 마당(.tbl) 폴더 | 설치된 한글의 폴더 |

```json
"hwpx": {"command": "uvx", "args": ["--from", "git+https://github.com/jun-Bridge/hwpx-mcp", "hwpx-mcp"],
         "env": {"HWPX_TRACK_AUTHOR": "홍길동"}}
```

## .hwp 읽기

.hwp(HWP 5.0)는 열어 읽기만 합니다. 글·문단·표·글자와 문단 모양·그림·도형·수식·각주·머리말·필드·메모·변경 추적을 읽습니다.
.hwp 안의 OLE 차트는 아직 옮기지 않아 경고로 알립니다. 암호·배포용·DRM 문서는 열지 않습니다(`E_UNSUPPORTED`).
고쳐서 저장하려면 `convert`로 .hwpx를 만들어 엽니다(한글 필요).

본 제품은 한글과컴퓨터의 한/글 문서 파일(.hwp) 공개 문서를 참고하여 개발하였습니다.

## 개발

```
uv run --extra dev pytest -q
```

설계는 [docs/architecture.md](docs/architecture.md), 요구사항은 [docs/requirements.md](docs/requirements.md), 서식 매핑 근거는 [docs/mapping-sources.md](docs/mapping-sources.md).
정답 파일 생성·게이트 검수 스크립트(한글이 깔린 Windows에서)는 [windows/](windows/README.md).

## 라이선스

MIT. [LICENSE](LICENSE)