hwp-com-mcp
README.md
# hwp-com-mcp — 한글(HWP) 문서 작성·수정 MCP 서버 + Claude 스킬
한글 프로그램을 **화면 없이 직접 조종**(COM)해서 문서를 만들고 고칩니다. 파일을 따로 해석해서 다시 쓰는 방식이 아니라 한글이 직접 저장하므로 표가 찌그러지거나 쪽 배치가 어긋나지 않습니다.
(한글 2010 에서 179개 항목 시험, 176개 통과 — `selftest/` 참고)
## 필요한 것
- Windows PC, **한컴오피스 한글**이 설치돼 있을 것 (한글 2010 에서 검증, 다른 버전은 `selftest` 로 확인)
- Python 3.9 이상 (https://www.python.org/downloads/ — 설치 때 "Add python.exe to PATH" 체크)
- Claude Code 또는 Claude 데스크톱 앱
## 설치 (새 PC)
1. 이 폴더를 통째로 복사한다(예: `C:\hwp_com_mcp`). `.venv` 폴더는 복사하지 말 것(PC마다 새로 만듦).
2. `setup.bat` 더블클릭 — 가상환경(.venv)을 만들고 필요한 패키지를 설치한다.
3. 점검: 명령 프롬프트에서
```
.venv\Scripts\python.exe server\doctor.py
```
`"ok": true` 가 나오면 이 PC 에서 한글 자동화가 됩니다. (한글이 잠깐 떴다 사라지는 것이 정상)
4. Claude 에 연결 — 아래 중 하나.
### A. Claude Code — 가장 쉬움
`install_user.bat` 실행(MCP 서버 등록 + 스킬 설치). 이후 Claude Code 를 다시 시작.
### B. Claude Code — 플러그인으로
```
claude --plugin-dir C:\hwp_com_mcp
```
(`.claude-plugin/plugin.json`, `.mcp.json`, `skills/` 를 그대로 읽습니다. 회사 저장소에 올려 마켓플레이스로 배포할 수도 있습니다.)
### C. Claude 데스크톱 앱
`%APPDATA%\Claude\claude_desktop_config.json` 의 `mcpServers` 에 추가:
```json
{"mcpServers": {"hwp-com": {"command": "C:\\hwp_com_mcp\\.venv\\Scripts\\python.exe", "args": ["C:\\hwp_com_mcp\\server\\server.py"]}}}
```
스킬은 `skills\hwp-report` 폴더를 앱의 스킬 업로드(설정 → 기능)에 올립니다.
## 도구
| 도구 | 하는 일 |
|---|---|
| `hwp_doctor` | 이 PC 에서 되는지 점검 |
| `hwp_build` | 선언형 명세(JSON)로 새 문서 작성 + PDF + 배치 점검 |
| `hwp_edit_cells` | 기존 문서 표 칸 글 수정(서식 유지) |
| `hwp_fill_fields` | 누름틀 양식 템플릿에 값 채우기 |
| `hwp_replace_text` | 본문·표 칸 글자 찾아 바꾸기 |
| `hwp_read` | 글·쪽수·필드 이름 읽기 |
| `hwp_export` | PDF·쪽 그림(PNG)으로 내보내기(눈으로 확인용) |
| `hwp_check_pdf` | 빈 쪽·고아 제목·쪽 밖 글자 점검 |
명세 형식과 예시: `skills/hwp-report/references/spec.md`
## 안전 장치
- 한글은 **임시 폴더(%TEMP%) 밖 파일을 열면 "접근 허용" 창**을 띄워 멈춥니다. 모든 도구는 원본을 임시 폴더로 복사해 작업하고 결과만 일반 복사로 돌려놓으므로 이 창이 뜨지 않습니다. (창이 뜨면 이 도구가 아닌 다른 경로로 한글을 연 것입니다. 승인 DLL 은 등록하지 않습니다.)
- 원본을 덮어쓰기 전에 `%USERPROFILE%\hwp_com_backup`(환경변수 `HWP_COM_BACKUP` 로 변경)에 백업합니다.
- 한글이 멈추면 시간 제한 뒤 **이 도구가 띄운 한글 프로세스만** 종료합니다(사용자가 쓰던 한글은 건드리지 않음).
## 알려진 한계
꼬리말 글자·글상자·자동 차례 불가, HWPX(한글 2010) 불가, 장평 글자 PDF 변환 누락 — 자세히는 `skills/hwp-report/SKILL.md`.
## 다른 버전 한글에서 확인하려면
```
.venv\Scripts\python.exe selftest\run_all.py
```
(약 12분, 한글이 화면 없이 반복해서 뜹니다. 결과는 `selftest\out\res_*.json`.) 통과/실패 목록을 보고 쓸 수 있는 기능을 판단하세요.
## 구성
```
server/server.py MCP 서버(도구 정의)
server/hwp_com/ 한글 조종 코드 (hwp_toolkit·hwp_fmt·render·hwp_qa, pyhwpx 복사본 — pyhwpx_license.txt 참고. 안 쓰는 승인 DLL 은 뺐음)
skills/hwp-report/ Claude 용 사용 지침 + 명세 문서
selftest/ 기능 시험 일체
```
## 라이선스
MIT (`LICENSE`). `server/hwp_com/pyhwpx` 는 pyhwpx(MIT) 복사본이며 자체 라이선스를 따릅니다.
## 개발 메모 (시행착오)
- MCP 서버 안에서 한글 호출 스레드가 `pyhwpx` 를 처음 import 하면 멈춤 → `server.py` 가 시작할 때 미리 import.
- `mcp` 패키지는 2.x 에서 `FastMCP` 이름이 바뀌어 `requirements.txt` 에서 `<2` 로 고정.
- 디버그: 환경변수 `HWP_COM_DEBUG=1` 이면 서버가 stderr 로 진행 단계를 찍는다.
## 안내
비공식 도구입니다. "한글", "한컴오피스"는 주식회사 한글과컴퓨터의 상표이며 이 프로젝트와 제휴·후원 관계가 없습니다. 한글 프로그램은 별도로 설치(라이선스 보유)해야 하고, 이 도구는 설치된 한글을 자동화(COM)할 뿐 한글 프로그램을 포함하지 않습니다.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data