Metadata-Version: 2.4
Name: hwp-thesis-mcp
Version: 0.2.0
Summary: 한국 대학원 학위논문 HWP 자동 변환 MCP 서버 (숭실대 석사·박사 양식 포함)
Author: Minisoft, Inc.
License: MIT License
        
        Copyright (c) 2026 Minisoft, Inc.
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/mobisk/hwp-thesis-mcp
Project-URL: Issues, https://github.com/mobisk/hwp-thesis-mcp/issues
Keywords: hwp,thesis,mcp,ssu,soongsil,korean,automation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Korean
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lxml>=5.0.0
Requires-Dist: pywin32>=306; platform_system == "Windows"
Requires-Dist: mcp>=1.0.0
Provides-Extra: preview
Requires-Dist: pymupdf>=1.24; extra == "preview"
Provides-Extra: dev
Requires-Dist: pymupdf>=1.24; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: jsonschema>=4.20; extra == "dev"
Dynamic: license-file

# 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+

### 설치
```powershell
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 변환
```powershell
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`:
```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](https://github.com/martiniifun/pyhwpx) — HwpCtrl 자동화 공식 패턴
- [Hancom HwpCtrl](https://developer.hancom.com/) — HWP COM 자동화 인터페이스
- 숭실대학교 일반대학원 — 논문 서식 규격 출처

상세 크레딧: `ATTRIBUTION.md`

## 알려진 제한

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

## 기여

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

## 저작권

© 2026 Minisoft, Inc. Licensed under MIT.

---

<sub>Sponsored by Minisoft. Initial implementation by Minisoft CEO mobisk.</sub>
