# 한글 MCP (HWPX) 서버 - 한글 자동화 HWPX 문서 자동 생성·편집·검증mcp #

이 프로젝트는 **한글 MCP(HWPX) 서버**로, HWPX 문서를 한글 워드프로세서 없이 직접 열고 자동화할 수 있도록 설계되었습니다.  
Gemini CLI, Claude Desktop과 같은 MCP 클라이언트에 연결하여 문서 생성·편집·탐색 기능을 제공합니다.

[](https://www.google.com/search?q=https://pypi.org/project/hwpx-mcp-server/)
[](https://opensource.org/licenses/MIT)
[](https://www.google.com/search?q=https://github.com/your-repo/hwpx-mcp-server/actions/workflows/ci.yml)

**순수 파이썬으로 HWPX 문서를 자유롭게 다루는 가장 강력한 방법.**


`hwpx-mcp-server`는 [Model Context Protocol](https://github.com/modelcontextprotocol/specification) 표준을 따르는 서버로, 강력한 [`python-hwpx`](https://www.google.com/search?q=%5Bhttps://github.com/airmang/python-hwpx%5D\(https://github.com/airmang/python-hwpx\)) 라이브러리를 기반으로 합니다. Gemini, Claude와 같은 최신 AI 클라이언트와 완벽하게 연동하여 한글 워드 프로세서 로컬 HWPX 문서를 열람, 검색, 편집, 저장하는 풍부한 기능을 제공합니다.

-----

## ✨ 주요 기능

  * **✅ 표준 MCP 서버 구현**: 공식 `mcp` SDK를 사용하여 안정적인 표준 입/출력 기반 서버를 제공합니다.
  * **📂 제로 설정**: 별도 설정 없이 현재 작업 디렉터리를 기준으로 즉시 경로를 처리합니다.
  * **📄 강력한 문서 편집**: 텍스트 추출, 페이지네이션부터 스타일, 표, 메모, 개체 편집까지 모두 가능합니다.
  * **🛡️ 안전한 저장**: 자동 백업(`*.bak`) 옵션으로 예기치 않은 데이터 손실을 방지합니다.
  * **🚀 즉시 실행**: `uv`만 있으면 `uvx hwpx-mcp-server` 한 줄로 바로 시작할 수 있습니다.

## 🚀 빠른 시작

### 1\. `uv` 설치

가장 먼저 파이썬 패키지 설치 도구인 `uv`를 설치하세요.
[👉 Astral uv 설치 가이드](https://docs.astral.sh/uv/getting-started/installation/)


### 2\. MCP 클라이언트 설정

#### 방법 1: 로컬 설치 (uvx 사용)

사용 중인 MCP 클라이언트 설정에 아래와 같이 서버 정보를 추가하세요.

```json
{
  "mcpServers": {
    "hwpx": {
      "command": "uvx",
      "args": ["hwpx-mcp-server"],
      "env": {
        "HWPX_MCP_PAGING_PARA_LIMIT": "200",
        "HWPX_MCP_AUTOBACKUP": "1",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}
```

터미널에서 직접 실행:
```bash
uvx hwpx-mcp-server
```

> `uvx` 명령은 첫 실행 시 필요한 종속성을 자동으로 설치하며, 반드시 `python-hwpx 1.9` 이상의 버전이 준비되어야 합니다.

#### 방법 2: HTTP 스토리지 모드

원격 문서 서버와 연동하려면 HTTP 백엔드 설정을 추가하세요.

```json
{
  "mcpServers": {
    "hwpx-http": {
      "command": "uvx",
      "args": ["hwpx-mcp-server"],
      "env": {
        "HWPX_STORAGE_BACKEND": "http",
        "HWPX_HTTP_BASE_URL": "https://your-server.com/documents",
        "HWPX_MCP_PAGING_PARA_LIMIT": "200",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}
```

> HTTP 모드에서는 `uri` 필드를 사용하여 원격 문서를 지정할 수 있습니다.
> 서버는 실행된 현재 디렉터리를 기준으로 경로를 해석하므로, 별도의 작업 디렉터리 설정 없이 바로 사용할 수 있습니다.

## ⚙️ 환경 변수

| 변수 | 설명 | 기본값 |
| --- | --- | --- |
| `HWPX_MCP_PAGING_PARA_LIMIT` | 페이지네이션 최대 문단 수 | `200` |
| `HWPX_MCP_AUTOBACKUP` | 저장 전 `.bak` 백업 생성 (`1`/`0`) | `0` |
| `LOG_LEVEL` | 로그 레벨 (INFO/DEBUG 등) | `INFO` |
| `HWPX_MCP_HARDENING` | 하드닝 파이프라인 활성화 (`1`/`0`) | `0` |
| `HWPX_STORAGE_BACKEND` | 스토리지 백엔드 (`local`/`http`) | `local` |
| `HWPX_HTTP_BASE_URL` | HTTP 모드 시 베이스 URL | - |

## 🛠️ 제공 도구

다양한 문서 편집 및 관리 도구를 제공합니다. 주요 도구는 다음과 같습니다:

- **문서 조회**: `open_info`, `read_text`, `read_paragraphs`, `find`
- **문서 편집**: `replace_text_in_runs`, `add_paragraph`, `add_table`, `set_table_cell_text`
- **스타일 관리**: `ensure_run_style`, `apply_style_to_text_ranges`
- **파일 저장**: `save`, `save_as`, `make_blank`
- **하드닝 모드** *(HWPX_MCP_HARDENING=1)*: `hwpx.plan_edit`, `hwpx.preview_edit`, `hwpx.apply_edit`, `hwpx.search`, `hwpx.get_context`

> 📖 전체 도구 목록과 상세 파라미터는 `ListTools` 응답의 JSON 스키마를 참고하세요.

## 🧪 테스트

```bash
python -m pip install -e .[test]
python -m pytest
```

## 🧑‍💻 개발 참고

- `python-hwpx>=1.9`, `mcp`, `pydantic` 등 순수 파이썬으로 구성
- 모든 편집 작업은 `dryRun` 플래그 지원
- 자동 백업(`.bak`) 옵션으로 데이터 보호
- JSON 스키마는 draft-07 호환 형태로 제공

## 📜 라이선스

이 프로젝트는 [MIT 라이선스](https://www.google.com/search?q=LICENSE)로 배포됩니다. 자세한 내용은 라이선스 파일을 확인하세요.

## 이메일

광교고등학교 교사 고규현 : kokyuhyun@hotmail.com
