master-of-hwp 0.2.4

Read Korean HWP/HWPX documents in Python; edit paragraphs and table cells in HWPX; natural-language edits via Claude Code CLI, Codex CLI, or Anthropic/OpenAI API. AI-friendly API.

한글의 달인 · 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

---

✨ 주요 기능

기능	상세
문서 열기	.hwp / .hwpx 파일을 네이티브 포맷 그대로 로드
구조 분석	섹션·문단·표·셀을 JSON으로 반환 (summary(), section_tables 등)
문단/셀 편집	replace_paragraph, replace_table_cell_paragraph 불변 API
AI 자연어 편집	doc.ai_edit("내용을 공식체로") — Claude/Codex/API 모두 지원
멀티모달	이미지·PDF 첨부 → Claude Code CLI/Codex CLI가 Read/인식
템플릿 라이브러리	자주 쓰는 양식 저장/불러오기 (~/.mohwp/templates/)
왕복 재현율	fidelity.harness 로 바이트 레벨 검증
MCP 서버	Claude Desktop 에서 open_document, find_paragraphs, replace_paragraph 등 도구 호출

---

🧠 AI 제공자

제공자	사용 방식	우선순위
Claude Code CLI	claude -p "prompt" (구독 사용, API 키 불필요)	🥇 1순위
Claude API	ANTHROPIC_API_KEY 환경변수	🥈 2순위
Codex CLI	codex exec (ChatGPT Plus/Pro 구독)	🥇 1순위
OpenAI API	OPENAI_API_KEY 환경변수	🥈 2순위
Rule-based	위 어떤 것도 없을 때 폴백	🥉 항상 가능

---

🏗 아키텍처

┌──────────────────────────────────────────┐
│  사용자 (교사 · 공무원 · 개발자)         │
└────────────┬─────────────────────────────┘
             │
    ┌────────┴────────┐
    ▼                 ▼
┌──────────┐    ┌──────────────────┐
│ 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)

---

📦 패키지

이름	용도	설치
master-of-hwp	Python Core API	pip install master-of-hwp
master-of-hwp[ai]	+ AI provider SDK	pip install "master-of-hwp[ai]"
master-of-hwp-studio	GUI + MCP + rhwp 번들	pip install master-of-hwp-studio

---

🛣 로드맵

• 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 참고.

---

만든 사람 — 배움의 달인

📺 YouTube  ·  𝕏 @reallygood83  ·  GitHub

도움이 되셨다면 ⭐ 한 번 눌러주시면 큰 힘이 됩니다.