MCP HWPX 서버

mcp-hwpx는 python-hwpx를 이용해 한글 HWPX 문서를 읽고 편집하는 Model Context Protocol(MCP) STDIO 서버입니다. Smithery 레지스트리를 통해 한 줄 설치와 클라이언트 등록을 지원하며, 로컬 워크스페이스 내부의 문서를 안전하게 다룰 수 있도록 설계되었습니다.

주요 기능

• HWPX 문서 생성, 열기, 저장, 메타데이터 조회
• 문단/표/이미지 삽입과 기본 미리보기 지원
• 워크스페이스 경로 검증 및 자동 백업(.bak) 파일 생성
• hwpx:list, hwpx:preview(path) 리소스를 통한 파일 인벤토리/미리보기 제공
• Windows, macOS, Linux에서 Python 3.10 이상 지원

요구 사항

• Python 3.10 이상
• Node.js 환경( Smithery CLI 설치용 )
• 로컬에 HWPX 문서를 저장할 디렉터리 권한

Smithery를 통한 한 줄 설치

사전에 Smithery CLI가 설치되어 있지 않다면 아래 명령으로 설치합니다.

npm install -g @smithery/cli

그 다음 아래 명령 한 줄로 서버 설치와 클라이언트 등록을 동시에 수행할 수 있습니다.

npx @smithery/cli install mcp-hwpx --client claude

Gemini CLI를 사용하는 경우:

npx @smithery/cli install mcp-hwpx --client gemini

설치가 완료되면 Claude Desktop 또는 Gemini CLI에서 "mcp-hwpx"를 서버로 추가하고, 워크스페이스 디렉터리를 지정하면 준비가 끝납니다.

도구 및 리소스 목록

이름	유형	설명
set_workspace	Tool	워크스페이스 디렉터리를 설정합니다.
open_document	Tool	기존 HWPX 파일을 열고 메타데이터를 로드합니다.
create_document	Tool	새 HWPX 파일을 생성합니다.
insert_paragraph	Tool	문단을 추가합니다.
insert_table	Tool	행/열 수를 지정하여 표를 추가합니다.
insert_image	Tool	워크스페이스 내 이미지를 문서에 삽입합니다.
get_metadata	Tool	현재 열린 문서의 메타데이터를 반환합니다.
save_as	Tool	다른 이름으로 문서를 저장합니다.
hwpx:list	Resource	워크스페이스 내 HWPX 파일 목록(JSON).
hwpx:preview(path)	Resource	지정한 문서의 앞부분 문단 미리보기(JSON).

로컬 설치 (대체 옵션)

Smithery 없이 직접 설치하고 실행할 수 있습니다.

pip install mcp-hwpx
mcp-hwpx  # STDIO 서버 실행

소스에서 개발 모드로 설치할 경우:

git clone https://github.com/example/mcp-hwpx.git
cd mcp-hwpx
pip install -e .[dev]

로컬에서 서버를 실행하려면 다음 명령을 사용합니다.

python -m mcp_hwpx.server

ZIP 패키지 배포

scripts/build_zip_unix.sh 또는 scripts/build_zip_win.ps1를 실행하면 의존성(requirements.txt)과 함께 동작 가능한 ZIP 패키지가 dist/mcp-hwpx-zip.zip으로 생성됩니다. 이 파일에는 서버 실행을 위한 스크립트와 문서가 포함되어 있어 오프라인 환경에서도 설치할 수 있습니다.

보안 및 워크스페이스 정책

• 모든 파일 경로는 지정한 워크스페이스 내부로 제한됩니다. 워크스페이스 밖의 경로를 요청하면 SecurityError로 거부됩니다.
• 기존 문서를 수정하기 전 자동으로 .bak 백업 파일을 생성합니다.
• 네트워크 접근은 사용하지 않으며 STDIO를 통해서만 통신합니다.

작동 확인 예시

1. set_workspace 도구를 호출해 로컬 디렉터리를 설정합니다.
2. create_document로 새 문서를 만들고 insert_paragraph, insert_table, insert_image를 이용해 내용을 추가합니다.
3. get_metadata를 호출해 문단/표 개수를 확인합니다.
4. save_as로 결과물을 다른 이름으로 저장합니다.
5. hwpx:list 리소스를 읽어 새로 저장된 문서가 목록에 있는지 확인합니다.

테스트

개발 환경에서 다음 명령으로 테스트를 실행할 수 있습니다.

pip install -e .[dev]
pytest

라이선스

이 프로젝트는 MIT 라이선스로 배포됩니다.