# hwp-mcp-v2

`pyhwpx` 기반 한글(HWP) 자동화 MCP 서버입니다.

## 1) 현재 지원 도구

### 기본 문서 작업

- `hwp_connect`: 한글 연결
- `hwp_status`: 연결/활성 문서 상태 조회
- `hwp_open`: 문서 열기
- `hwp_insert_text`: 텍스트 입력
- `hwp_save_as`: 다른 이름으로 저장
- `hwp_quit`: 한글 종료

### 문서 탭/창 관리 (1차 확장)

- `hwp_list_docs`: 열린 문서 목록 조회(0-based index)
- `hwp_switch_doc(index)`: 활성 문서 전환
- `hwp_add_tab`: 현재 창에 새 탭 문서 추가
- `hwp_add_doc`: 새 문서 창 추가
- `hwp_close_current(save=False)`: 현재 문서 닫기(기본 저장 안 함)

## 2) 요구사항

- Windows
- 한글(HWP) 설치
- Python 3.10+

## 3) 설치

```bash
pip install -r requirements.txt
```

## 4) 실행

```bash
python hwp_mcp_stdio_server.py
```

## 5) Claude/Codex MCP 등록 예시

```json
{
  "mcpServers": {
    "hwp-v2": {
      "command": "python",
      "args": [
        "C:/path/to/hwp-mcp-v2/hwp_mcp_stdio_server.py"
      ]
    }
  }
}
```

## 6) 문서 탭 관리 호출 예시

1. `hwp_connect`
2. `hwp_list_docs`
3. `hwp_add_tab`
4. `hwp_add_doc`
5. `hwp_switch_doc(index=1)`
6. `hwp_close_current(save=false)`

## 7) 응답 포맷

모든 도구는 아래 공통 포맷으로 반환합니다.

```json
{
  "ok": true,
  "message": "작업 결과 메시지",
  "data": {}
}
```

`hwp_list_docs`의 `data` 예시:

```json
{
  "docs": [
    {
      "index": 0,
      "document_id": 123456,
      "full_name": "C:/work/a.hwp",
      "modified": false,
      "is_active": true
    }
  ],
  "count": 1
}
```

## 8) 구조

```text
hwp-mcp-v2/
├─ hwp_mcp_stdio_server.py  # MCP 서버 엔트리포인트
├─ requirements.txt
├─ src/
│  ├─ __init__.py
│  └─ service.py            # pyhwpx 래퍼 서비스
└─ tests/
   └─ test_service_doc_tools.py
```