한글의 달인 · master-of-hwp

AI가 한컴오피스 문서(.hwp / .hwpx)를 읽고, 이해하고, 편집하는 오픈소스 플랫폼

   

English · CHANGELOG · 로드맵 · 아키텍처 · 기여하기

🎯 왜 이 프로젝트인가

한국의 공공·교육·업무 현장은 아직도 한글 문서(.hwp / .hwpx)를 표준으로 씁니다. 하지만 대부분의 AI 도구는 HWP를 직접 다루지 못하고, DOCX로 변환해 편집한 뒤 돌려놓는 과정에서 서식·표·문단 속성이 망가집니다.

한글의 달인(master-of-hwp) 은 이 문제를 해결합니다:

• ✅ 진짜 포맷 유지 — 변환 없이 원본 HWP/HWPX를 그대로 열고 저장
• ✅ 구조 이해 — 섹션·문단·표의 구조를 AI에 그대로 노출
• ✅ AI-네이티브 편집 — "3번째 문단을 공식 문체로 바꿔줘" 같은 자연어 지시로 수정
• ✅ 라운드트립 보장 — 편집 → 저장 → 재로딩 후에도 구조 훼손 없음

🚀 30초 시작

📘 개발자용 — Python 라이브러리

pip install master-of-hwp

from master_of_hwp import HwpDocument

doc = HwpDocument.open("보도자료.hwpx")
print(doc.summary())                         # 구조 요약 (AI 컨텍스트용)

for s, p, text in doc.find_paragraphs("보도"):
    print(f"§{s}.{p}: {text}")

edited = doc.replace_paragraph(0, 0, "새 문단 내용")
edited.path.with_suffix(".edited.hwpx").write_bytes(edited.raw_bytes)

🎨 일반 사용자용 — Studio (WYSIWYG GUI)

macOS / Linux:

pip install master-of-hwp-studio
mohwp studio

Windows (PowerShell):

py -m pip install master-of-hwp-studio
mohwp studio

→ 브라우저 자동 실행 → rhwp WYSIWYG 에디터 + AI 작업 패널 한 화면에서 사용.

mohwp mcp-config   # OS별 Claude Desktop 설정 경로 자동 감지해 스니펫 출력

Windows 사용 시 AI provider 3가지 경로

🔑 경로 A — API 키 (가장 쉬움)

setx ANTHROPIC_API_KEY "sk-ant-..."
# 또는
setx OPENAI_API_KEY "sk-..."
# 새 터미널에서
mohwp studio

• Claude Pro/Max 구독 따로 + API 크레딧 따로 충전 (별도 과금)
• 설정 간단, 즉시 동작

🐧 경로 B — WSL 전체 통합

wsl --install                                 # 1회 설치 (관리자 PowerShell)

# Ubuntu 안에서
sudo apt install -y python3-pip nodejs npm
npm install -g @anthropic-ai/claude-code
pip install master-of-hwp-studio
claude login                                   # 구독 로그인
mohwp studio

→ Windows 브라우저에서 localhost:<port> 접속 (WSL2 자동 포워딩)

• 구독 그대로 사용 (API 크레딧 불필요)

🔗 경로 C — 하이브리드 (Studio 는 Windows native, CLI 는 WSL)

• Windows 에서 py -m pip install master-of-hwp-studio
• WSL 안에 claude / codex 만 설치
• Studio 가 자동으로 wsl -e claude ... 로 호출 (v0.2.4+)
• Windows 경로 C:\...\file.png → 자동으로 /mnt/c/.../file.png 변환

Windows 기타 참고

• 최초 실행 시 Windows 방화벽 허용 팝업 → "액세스 허용" (localhost 용)
• Python 3.11+ 필요. Python 설치 시 "Add Python to PATH" 체크 권장
• mohwp 명령어가 안 보이면 새 터미널 열거나 py -m master_of_hwp_studio studio

✨ 주요 기능

🧠 AI 제공자

🏗 아키텍처

┌──────────────────────────────────────────┐
│  사용자 (교사 · 공무원 · 개발자)         │
└────────────┬─────────────────────────────┘
             │
    ┌────────┴────────┐
    ▼                 ▼
┌──────────┐    ┌──────────────────┐
│ Claude   │    │ 한글의 달인 Studio│
│ Desktop  │    │ (mohwp studio)   │
└────┬─────┘    └────────┬─────────┘
     │ MCP              │ HTTP
     ▼                   ▼
┌────────────────────────────────┐
│  master-of-hwp Core API        │
│  (HwpDocument, ai_edit, ...)   │
└────────────┬───────────────────┘
             │
   ┌─────────┴─────────┐
   ▼                   ▼
┌────────────┐   ┌──────────────────┐
│ olefile +  │   │ rhwp (Rust+WASM) │
│ zipfile    │   │ WYSIWYG 에디터   │
└────────────┘   └──────────────────┘

• Python Core — HWP 5.0 (CFBF) + HWPX (OOXML) 파싱, 편집 프리미티브
• rhwp — edwardkim/rhwp 의 Rust + WebAssembly WYSIWYG 편집 엔진 (번들 포함)
• Studio — 웹 GUI + MCP 서버 통합 (mohwp CLI)

📦 패키지

🛣 로드맵

• v0.1 ✅ — 읽기 API + HWPX 문단 편집 + fidelity
• v0.2 ✅ — 표 셀 편집 · 자연어 편집 루프 · CLI provider · Studio GUI · rhwp 번들 · 템플릿 라이브러리 · 멀티모달 첨부
• v0.3 — HWP 5.0 완전 쓰기 (CFBF resize writer) · 문단 삽입/삭제 · 표 추가/삭제
• v0.4 — Agentic edit loop (intent → locate → apply → verify → rollback)
• v1.0 — API 호환성 계약 고정

세부: docs/ROADMAP.md

🤝 기여하기

이 프로젝트는 커뮤니티 기여를 환영합니다.

• 🐛 버그 리포트 / 기능 요청: Issues
• 💻 코드 기여: fork → branch → PR (CONTRIBUTING.md)
• 💬 질문 / 토론: Discussions

도움 주시면 좋은 영역:

• HWP 5.0 CFBF 쓰기 엔진 (v0.3)
• 문단/표 삽입·삭제 연산
• 추가 LLM provider (Gemini, 로컬 Ollama)
• Windows/Linux 인스톨러
• 접근성(a11y) 개선

작은 기여도 환영합니다 — 문서 오탈자, 번역, 샘플 파일 모두 가치 있습니다.

🙏 감사의 말

이 프로젝트는 edwardkim/rhwp (by @edwardkim) 의 Rust + WebAssembly HWP 파싱/렌더링 엔진을 기반으로 합니다. master-of-hwp-studio 의 WYSIWYG 에디터는 rhwp 가 있기에 가능합니다. rhwp 도 같이 ⭐ 눌러주세요.

📄 라이선스

MIT — LICENSE 참고.