Jun Skills Hwpx V2

Unified HWPX (Hangul Word Processor) MCP Server

Markdown 문서를 HWPX로 변환하거나, 기존 HWPX 템플릿을 분석하여 서식을 유지하면서 새로운 내용으로 문서를 생성하는 통합 MCP 서버입니다.

Copyright (c) 2026 이창준, (주)파워솔루션 | MIT License

---

두 가지 워크플로우

1. Markdown → HWPX (템플릿 불필요)

Markdown 파일을 바로 HWPX 문서로 변환합니다. 표지, 머리글/바닥글, 자동 번호 매기기를 지원합니다.

"report.md를 한글 문서로 변환해줘"

사용 도구: convert_md_to_hwpx

2. HWPX 템플릿 → HWPX (서식 유지)

기존 HWPX 문서의 서식(글꼴, 여백, 스타일)을 그대로 유지하면서 내용만 교체합니다. 공문, 보고서, 회의록 등 정해진 양식이 있을 때 사용합니다.

"이 공문 양식에 맞춰서 새 문서를 만들어줘"

사용 도구: analyze_hwpx → extract_hwpx_xml → build_hwpx → validate_hwpx → page_guard_hwpx

---

설치

자동 설치 (권장)

macOS / Linux:

curl -LsSf https://raw.githubusercontent.com/cjLee-cmd/jun-skills-hwpx-v2/main/install.sh | bash

Windows (PowerShell):

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/cjLee-cmd/jun-skills-hwpx-v2/main/install.bat" -OutFile "$env:TEMP\install.bat"; & "$env:TEMP\install.bat"

설치 스크립트가 자동으로 수행하는 작업:

• uv 설치 (없는 경우)
• 소스 다운로드 (~/jun-skills-hwpx-v2)
• 의존성 설치 (uv sync)
• MCP 서버 자동 등록:
  • Claude Code (~/.claude.json)
  • Claude Desktop (claude_desktop_config.json)
  • Gemini CLI (~/.gemini/settings.json)

수동 설치

git clone https://github.com/cjLee-cmd/jun-skills-hwpx-v2.git ~/jun-skills-hwpx-v2
cd ~/jun-skills-hwpx-v2
uv sync

MCP 설정 파일에 다음을 추가:

{
  "mcpServers": {
    "hwpx": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/jun-skills-hwpx-v2", "python", "scripts/mcp_server.py"]
    }
  }
}

클라이언트	설정 파일 경로
Claude Code	~/.claude.json
Claude Desktop (macOS)	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows)	%APPDATA%\Claude\claude_desktop_config.json
Gemini CLI	~/.gemini/settings.json

---

MCP 도구 목록

도구	설명
convert_md_to_hwpx	Markdown → HWPX 변환 (표, 코드블록, 리스트, 인용문, 표지, 머리글/바닥글 지원)
analyze_hwpx	HWPX 문서 구조 분석 (글꼴, 스타일, 레이아웃 추출)
extract_hwpx_xml	HWPX에서 header.xml / section0.xml 추출
build_hwpx	템플릿 + XML → HWPX 조립
validate_hwpx	HWPX 구조 무결성 검증
page_guard_hwpx	레퍼런스 대비 페이지 수 드리프트 검사
extract_text_hwpx	HWPX에서 텍스트 추출

---

CLI 직접 실행

cd ~/jun-skills-hwpx-v2

# Markdown → HWPX
uv run python scripts/md2hwpx.py input.md output.hwpx --title "보고서 제목"

# HWPX 분석
uv run python scripts/analyze_template.py template.hwpx

---

사용 예시

Claude / Gemini에서 사용

# Markdown → HWPX (템플릿 없이)
"이 마크다운 파일을 한글 문서로 변환해줘"
"report.md를 HWPX로 만들어줘. 제목은 '월간 보고서'"

# HWPX 템플릿 기반
"이 한글 문서를 분석해줘" (analyze_hwpx)
"이 양식에 맞춰 새 문서를 만들어줘" (전체 워크플로우)
"공문 양식으로 문서를 작성해줘" (내장 템플릿 사용)

---

내장 템플릿

templates/ 폴더에 다음 양식이 포함되어 있습니다:

템플릿	설명
base/	기본 스켈레톤
gonmun/	공문
report/	보고서
minutes/	회의록
proposal/	제안서

---

요구 사항

• Python 3.10+
• uv (설치 스크립트가 자동 설치)
• git

---

라이선스

MIT License - 자유롭게 사용, 수정, 배포할 수 있습니다.