HWPX MCP Server - Enhanced Edition
🚀 Original 프로젝트를 Fork하여 안정성과 기능을 대폭 개선한 버전입니다.
AI 도구(Claude 등)와 연동하여 한글(HWPX) 문서를 자동으로 편집할 수 있는 MCP(Model Context Protocol) 서버입니다.
🌍 Cross-Platform Support
모든 운영체제에서 작동합니다!
| OS | MCP 서버 | HWPX 편집 | 결과물 확인 |
|:---:|:---:|:---:|:---|
| ✅ Windows | ✅ | ✅ | 한컴오피스 |
| ✅ macOS | ✅ | ✅ | 한컴오피스 Mac |
| ✅ Linux | ✅ | ✅ | 한컴오피스 Linux / LibreOffice* |
왜 가능한가요?
HWPX 파일은 ZIP + XML 구조입니다. 한글 프로그램 없이도 Node.js만으로 완벽하게 읽고 쓸 수 있습니다.
*LibreOffice는 HWPX를 제한적으로 지원합니다. 완벽한 호환을 위해 한컴오피스 사용을 권장합니다.
✨ Enhanced Features (개선된 기능)
원본 프로젝트 대비 다음과 같은 핵심 문제들을 해결했습니다:
🔧 Critical Bug Fixes
| 문제 | 원본 상태 | 개선 후 |
|------|----------|---------|
| 테이블 저장 실패 | 셀 수정 후 저장해도 변경사항 사라짐 | ✅ 완벽하게 저장됨 |
| 텍스트 겹침 현상 | 저장 후 한글에서 열면 글자가 겹쳐 표시 | ✅ 정상 표시 |
| 파일 손상 | 저장 시 가끔 파일이 손상됨 | ✅ 원자적 쓰기로 100% 안전 |
| 다중 셀 손상 | 같은 행에 여러 셀 수정 시 XML 손상 | ✅ 인덱스 관리로 안전 |
| 자간/줄간격 손실 | 저장 후 스타일 정보 유실 | ✅ 모든 스타일 보존 |
🛠 Technical Improvements
-
Atomic File Writing (원자적 파일 쓰기)
- 임시 파일 → ZIP 검증 → 원자적 이동
- 저장 중 오류 발생해도 원본 파일 보호
-
Smart Lineseg Reset (스마트 줄 레이아웃 초기화)
- 텍스트 수정 시
lineseg 자동 초기화
- 한글 프로그램이 열 때 자동으로 줄바꿈 재계산
- 텍스트 겹침 현상 완전 해결
-
Depth-based XML Parsing (깊이 기반 XML 파싱)
- 기존 lazy regex의 중첩 구조 오인식 문제 해결
- 복잡한 테이블(중첩 테이블, subList 등) 완벽 지원
-
Complete Style Preservation (스타일 완전 보존)
charPr, spacing 등 원본 스타일 100% 유지- 불완전한 직렬화 로직 제거로 데이터 무결성 보장
-
Safe Multi-Cell Updates (안전한 다중 셀 업데이트)
- 같은 행(row)의 여러 셀을 동시에 수정해도 안전
- 행별 그룹화 + 역순 처리로 인덱스 손상 방지
📦 Installation
1. MCP 서버 설치
git clone https://github.com/Dayoooun/hwpx-mcp.git
cd hwpx-mcp/mcp-server
npm install
npm run build
2. MCP 클라이언트 설정
아래에서 사용하는 클라이언트를 선택하세요.
🖥️ Claude Desktop
설정 파일 위치:
| OS | 경로 |
|----|------|
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Linux | ~/.config/Claude/claude_desktop_config.json |
설정 내용:
{
"mcpServers": {
"hwpx-mcp": {
"command": "node",
"args": ["C:/path/to/hwpx-mcp/mcp-server/dist/index.js"]
}
}
}
⚠️ Windows에서는 경로에 \\ 또는 / 사용 (예: C:/Users/username/hwpx-mcp/...)
💻 Claude Code (CLI)
방법 1: 프로젝트별 설정 (.mcp.json 파일을 프로젝트 루트에 생성)
{
"mcpServers": {
"hwpx-mcp": {
"command": "node",
"args": ["/path/to/hwpx-mcp/mcp-server/dist/index.js"]
}
}
}
방법 2: 전역 설정 (~/.claude/settings.json)
{
"mcpServers": {
"hwpx-mcp": {
"command": "node",
"args": ["/path/to/hwpx-mcp/mcp-server/dist/index.js"]
}
}
}
방법 3: CLI 명령어로 추가
claude mcp add hwpx-mcp node /path/to/hwpx-mcp/mcp-server/dist/index.js
🔷 Cursor
설정 파일: ~/.cursor/mcp.json (없으면 생성)
{
"mcpServers": {
"hwpx-mcp": {
"command": "node",
"args": ["/path/to/hwpx-mcp/mcp-server/dist/index.js"]
}
}
}
또는 Cursor Settings > MCP 에서 직접 추가 가능
🆚 VS Code (MCP 확장 사용 시)
설정 파일: .vscode/mcp.json (프로젝트 폴더 내)
{
"servers": {
"hwpx-mcp": {
"command": "node",
"args": ["${workspaceFolder}/../hwpx-mcp/mcp-server/dist/index.js"]
}
}
}
${workspaceFolder} 변수를 활용하면 상대 경로 지정 가능
🛠️ 기타 MCP 클라이언트
일반적인 MCP 설정 형식:
{
"mcpServers": {
"hwpx-mcp": {
"command": "node",
"args": ["/absolute/path/to/hwpx-mcp/mcp-server/dist/index.js"]
}
}
}
경로 예시:
| OS | 경로 예시 |
|----|----------|
| Windows | C:/Users/username/hwpx-mcp/mcp-server/dist/index.js |
| macOS | `/Users/username/hwpx-mcp/mcp-server/dist/in
... View full README on GitHub
