hwp-thesis-mcp 0.2.0

한국 대학원 학위논문 HWP 자동 변환 MCP 서버 (숭실대 석사·박사 양식 포함)

hwp-thesis-mcp

한국 대학원 석사학위논문 HWP 자동 변환 MCP 서버. SCHEMA.md 규격의 XML을 입력받아 숭실대학교 일반대학원 석사논문 양식을 정확히 반영한 .hwp 파일을 생성합니다. 다른 대학 양식은 presets/ 에 JSON 추가로 확장 가능.

XML (LLM이 작성) → MCP tool → HWP 자동 생성

• 🎯 숭실대 일반대학원 필수안내서 규격 100% 부합 (인쇄 용지 색상 제외)
• 🤖 순수 HwpCtrl COM 오토메이션 — 파일 포맷 후처리·SendKeys·UIA 없음
• 🔌 MCP 서버 — Claude Desktop / Claude Code / 기타 MCP 클라이언트 호환
• 🏫 다대학 확장 — presets/<school>_<degree>.json으로 양식 추가
• 🔄 XML 스키마 기반 — LLM이 get_schema() 호출로 규격 학습 후 작성

빠른 시작

사전 조건

• Windows 10/11
• 한컴오피스 한/글 (2018 이상 권장)
• Python 3.10+

설치

git clone https://github.com/mobisk/hwp-thesis-mcp.git
cd hwp-thesis-mcp

# HwpCtrl 보안 모듈 레지스트리 등록 (한 번만)
powershell -ExecutionPolicy Bypass -File scripts\setup_hwp.ps1

# Python 패키지
pip install -e .

CLI 변환

hwp-thesis-convert init                                # 샘플 template.xml 생성
hwp-thesis-convert template.xml -o thesis.hwp
hwp-thesis-convert template.xml -o thesis.hwp --pdf
hwp-thesis-convert template.xml -o thesis.hwp --preset ssu_phd
hwp-thesis-convert template.xml --validate

MCP 서버 사용 (Claude Desktop)

~\AppData\Roaming\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "hwp-thesis": {
      "command": "hwp-thesis-mcp"
    }
  }
}

(또는 개발 모드: "command": "python", "args": ["-m", "hwp_thesis_mcp.server"])

MCP Tools

도구	용도
get_schema()	XML 작성 규격(SCHEMA.md) 반환
list_presets()	사용 가능한 학교/학위 프리셋 목록
validate_thesis(xml)	XML 구조 검증
convert_thesis(xml, output, preset, export_pdf)	HWP 생성
preview_thesis_pages(xml, preset, pages)	PDF 렌더 페이지 이미지 경로

자동 반영 서식

• 판종 18.2×25.7cm, 여백 20×25mm
• 폰트 HY신명조 · HY견명조 · HY중고딕
• 크기 11/13/14/16/18pt
• 정렬·줄간격·들여쓰기
• 쪽번호 목차 로마자(- i -) → 본문 아라비아(- 1 -) 구역별 1부터 리셋
• 목차 점선 리더 + 실제 쪽번호 자동 치환
• 초록 소속 우측정렬 블록
• cite[N] 등장순서 자동 번호
• 13단계 문서 구조 (겉표지 → 부록)

프리셋 확장 (다른 대학 추가)

presets/README.md 참조. 새 학교 양식 기여는 환영.

현재 포함된 프리셋:

• ssu_masters — 숭실대학교 일반대학원 석사 ✅
• ssu_phd — 숭실대학교 일반대학원 박사 ✅

아키텍처

hwp_thesis_mcp/
  convert.py         CLI 엔트리 (--preset / --validate / --pdf / --visible)
  server.py          MCP 서버 (FastMCP stdio)
  parser.py          XML → ThesisDoc
  styles.py          presets/*.json 로더
  numbering.py       장/절/항/표/그림/cite 자동번호
  hwp_controller.py  HwpCtrl COM 래퍼 (pyhwpx 공식 패턴)
  frontmatter.py     겉표지/백지/표제지/속표지/인준서
  toc_generator.py   목차 + 표목차 + 그림목차
  renderer_hwp.py    본문/초록/참고문헌/부록 + 2-pass 페이지 매핑
  presets/           학교·학위별 서식 JSON
  SCHEMA.md          XML 작성 규격 (LLM 참조용)
  template.xml       샘플 입력
tests/               단위 테스트 (HWP 없이 실행 가능)
scripts/             setup_hwp.ps1 (HwpCtrl 보안모듈 등록)
examples/            Claude Desktop/Code 설정 예시

라이선스 & 크레딧

MIT License — LICENSE 참조

핵심 참조 및 기여자:

• pyhwpx (MIT) by martiniifun — HwpCtrl 자동화 공식 패턴
• Hancom HwpCtrl — HWP COM 자동화 인터페이스
• 숭실대학교 일반대학원 — 논문 서식 규격 출처

상세 크레딧: ATTRIBUTION.md

알려진 제한

• 겉표지 감청색(석사)/흑색(박사) 용지 + 금색 인쇄: 인쇄소 작업 영역 (코드로 불가능·불필요)

기여

이슈/PR 환영. 학교별 양식 확장이 특히 반가움.

저작권

© 2026 Minisoft, Inc. Licensed under MIT.

---

_{Sponsored by Minisoft. Initial implementation by Minisoft CEO mobisk.}