HwpForge

HwpForge 🔥

> Rust로 한글(HWP/HWPX) 문서를 프로그래밍 방식으로 제어 > > Hancom 한글 파일 읽기, 쓰기, 변환

---

HwpForge란?

HwpForge는 HWPX 문서(ZIP + XML, KS X 6101)를 다루기 위한 오픈소스 순수 Rust 라이브러리입니다. 한국에서 가장 많이 사용되는 워드프로세서인 Hancom 한글의 최신 포맷을 지원합니다.

지원 버전

| 한글 버전 | 포맷 | 읽기 | 쓰기 | 스타일 세트 | | ----------------- | ------------ | ---- | ---- | ------------------------------ | | 한글 2014 \~ 2020 | HWPX (.hwpx) | ✅ | ✅ | Classic (18 styles) | | 한글 2022 \~ 2024 | HWPX (.hwpx) | ✅ | ✅ | Modern (22 styles, 기본값) | | 한글 2025+ | HWPX (.hwpx) | ✅ | ✅ | Latest (23 styles) | | 한글 97 \~ 2010 | HWP5 (.hwp) | ✅ | — | — |

• HWPX: OWPML 국가표준 (KS X 6101) 기반, ZIP + XML 컨테이너
• HWP5: 구형 바이너리 포맷. 현재는 CLI 중심의 읽기/점검/재출력 경로를 제공합니다 (convert-hwp5, audit-hwp5, census-hwp5)
• 스타일 세트는 HancomStyleSet enum으로 선택 가능 (기본: Modern)

LLM-first 설계 🔥 — AI 친화적인 Markdown과 공식 한글 문서 포맷(HWPX), 두 세계를 자연스럽게 잇습니다. LLM이 Markdown으로 작성한 내용은 공문서 규격의 HWPX로 컴파일되고 📜, 반대로 기존 HWPX 문서는 AI가 쉽게 읽을 수 있는 구조로 꺼낼 수 있습니다 ⚒️.

• 📄  [HWPX 완전 가이드 다운로드](examples/showcase/guides/hwpxcompleteguide/hwpxcompleteguide.hwpx) — HwpForge API로 생성한 4섹션 데모 문서 (한글에서 열어보세요)
• HWPX Reader for AI — 기존 한글 문서(.hwpx)를 Markdown으로 변환하여 LLM이 즉시 이해 가능
• Full HWPX codec — HWPX 파일을 손실 없이 디코딩/인코딩 (lossless roundtrip)
• Markdown bridge — GFM Markdown과 HWPX 간 양방향 변환 (읽기 + 쓰기)
• YAML style template — Figma Design Token처럼 재사용 가능한 스타일 정의 (폰트, 크기, 색상)
• Type-safe API — branded index, typestate validation, zero unsafe code

빠른 시작

설치

# Cargo.toml에 추가
cargo add hwpforge

# Markdown 지원 포함
cargo add hwpforge --features full

또는 Cargo.toml에 직접 추가:

[dependencies]
hwpforge = "0.7"

🔨 Hammer — CLI로 시작하기

CLI 도구 hwpforge(Hammer)를 설치하면 터미널에서 바로 문서를 생성하고 편집할 수 있습니다.

cargo install hwpforge-bindings-cli

# Markdown → HWPX 변환
hwpforge convert report.md -o report.hwpx

# HWPX 구조 확인
hwpforge inspect report.hwpx

# HWPX → Markdown 변환 (AI가 한글 문서 읽기)
hwpforge to-md report.hwpx -o report.md

# HWPX → JSON 추출 (AI 편집용)
hwpforge to-json report.hwpx --section 0 > section0.json

# JSON → HWPX 직접 생성
hwpforge from-json section0.json -o new.hwpx

# JSON으로 섹션 교체
hwpforge patch report.hwpx --section 0  **AI-first 설계**: CLI는 AI agent(Claude Code 등)가 주 사용자입니다.
> Markdown으로 문서를 생성한 뒤, JSON round-trip으로 기존 스타일을 보존하면서
> section 단위로 정밀하게 편집할 수 있습니다. `--json` 플래그로 모든 명령어가
> machine-readable 출력을 지원합니다.

### ⚙️ Anvil — MCP Server (Beta)로 AI가 직접 한글 문서를 다루다

Claude Code, Codex CLI, Claude, ChatGPT, Cursor, Antigravity 등 [MCP](https://modelcontextprotocol.io/) 지원 AI 도구에서 **한글 문서를 직접 생성하고 편집**할 수 있습니다. 현재 MCP surface는 **베타**이며, HWP5 경로는 MCP가 아니라 CLI workflow를 우선합니다. "보고서 만들어줘"라고 말하면, AI가 알아서 `.hwpx` 파일을 뚝딱 만들어냅니다.

#### AI 도구에 등록

한 줄이면 설치 + 등록이 끝납니다. npm은 `npx -y`가 자동으로 바이너리를 다운로드합니다.

Claude Code (터미널)

npm (권장 — Rust 툴체인 불필요)

claude mcp add hwpforge -- npx -y @hwpforge/mcp

Cargo (Rust 개발자용)

cargo install hwpforge-bindings-mcp && claude mcp add hwpforge hwpforge-mcp

모든 프로젝트에서 사용 (글로벌)

claude mcp add --global hwpforge -- npx -y @hwpforge/mcp

Codex CLI (터미널)

`~/.codex/config.toml`에 추가:

[mcp_servers.hwpforge] command = "npx" args = ["-y", "@hwpforge/mcp"]

또는 CLI로:

codex mcp add hwpforge -- npx -y @hwpforge/mcp

Claude Desktop (앱)

설정 파일을 편집합니다:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "hwpforge": {
      "command": "npx",
      "args": ["-y", "@hwpforge/mcp"]
    }
  }
}

ChatGPT Desktop (앱)

Settings → Tools → Add MCP Server에서:

• Name: hwpforge
• Command: npx -y @hwpforge/mcp

또는 설정 파일을 직접 편집:

{
  "mcpServers": {
    "hwpforge": {
      "command": "npx",
      "args": ["-y", "@hwpforge/mcp"]
    }
  }
}

Cursor (에디터)

프로젝트 루트에 .cursor/mcp.json 생성:

{
  "mcpServers": {
    "hwpforge": {
      "command": "npx",
      "args": ["-y", "@hwpforge/mcp"]
    }
  }
}

Antigravity (에디터)

... 드롭다운 → MCP Store → Manage MCP Servers → View raw config (mcp_config.json)에 추가:

{
  "mcpServers": {
    "hwpforge": {
      "command": "npx",
      "args": ["-y", "@hwpforge/mcp"]
    }
  }
}

등록하면 9개 도구를 사용할 수 있습니다

| 도구 | 하는 일 | 한마디 | | -------------------- | ----------------------- | ------------------------------------ | | hwpforge_convert | Markdown → HWPX 변환 | "이 마크다운을 한글 파일로!" | | hwpforge_inspect | HWPX 구조 확인 | "이 문서 뭐가 들어있어?" | | hwpforge_to_json | HWPX → JSON 추출 | "이 섹션 내용 좀 꺼내봐" | | hwpforge_patch | JSON으로 섹션 교체 | "이 부분만 바꿔서 다시 저장해" | | hwpforge_templates | 스타일 프리셋 조회 | "어떤 템플릿 쓸 수 있어?" | | hwpforge_validate | HWPX 구조/무결성 검증 | "이 파일 문제 없는지 확인해" | | hwpforge_restyle | 스타일 프리셋 일괄 적용 | "이 문서 폰트 바꿔줘" | | hwpforge_from_json | JSON → HWPX 직접 생성 | "이 JSON으로 한글 파일 만들어" | | hwpforge_to_md | HWPX → Markdown 변환 | "이 한글 문서를 Markdown으로 꺼내줘" |

업데이트 / 삭제

npm은 npx -y가 항상 최신 버전을 가져오므로 별도 업데이트가 필요 없습니다.

# Cargo 사용자만 해당
cargo install hwpforge-bindings-mcp --force   # 업데이트
cargo uninstall hwpforge-bindings-mcp          # 삭제

> 왜 MCP? CLI(Hammer)는 AI가 bash 명령을 실행해야 하지만, MCP(Anvil)는 AI가 네이티브 도구로 > 직접 호출합니다. 파일 경로 파싱도, stdout 해석도 필요 없습니다. > JSON-RPC로 요청하면 구조화된 JSON으로 응답 — 깔끔합니다.

🔨 문서 생성

use hwpforge::core::{Document, Draft, Paragraph, Run, Section, PageSettings};
use hwpforge::foundation::{CharShapeIndex, ParaShapeIndex};

let mut doc = Document::::new();
doc.add_section(Section::with_paragraphs(
    vec![Paragraph::with_runs(
        vec![Run::text("Hello, 한글!", CharShapeIndex::new(0))],
        ParaShapeIndex::new(0),
    )],
    PageSettings::a4(),
));

⚒️ HWPX로 인코딩

use hwpforge::hwpx::{HwpxEncoder, HwpxStyleStore};
use hwpforge::core::ImageStore;

let validated = doc.validate().unwrap();
let style_store = HwpxStyleStore::with_default_fonts("함초롬바탕");
let image_store = ImageStore::new();
let bytes = HwpxEncoder::encode(&validated, &style_store, &image_store).unwrap();
std::fs::write("output.hwpx", &bytes).unwrap();

⚒️ HWPX 디코딩

use hwpforge::hwpx::HwpxDecoder;

let result = HwpxDecoder::decode_file("input.hwpx").unwrap();
println!("섹션 수: {}", result.document.sections().len());

⚒️ HWPX → Markdown 변환 (AI가 한글 문서 읽기)

📄 한글 원본 (.hwpx) 📝 Markdown 변환 결과

use hwpforge::hwpx::HwpxDecoder;
use hwpforge::md::MdEncoder;

let decoded = HwpxDecoder::decode_file("government_report.hwpx").unwrap();
let validated = decoded.document.validate().unwrap();
let markdown = MdEncoder::encode_lossy(&validated).unwrap();
println!("{}", markdown); // LLM이 바로 이해할 수 있는 Markdown

기존 .hwpx 파일을 Markdown으로 변환하면 Claude, GPT 등 어떤 LLM이든 한글 공문서를 즉시 읽고 분석할 수 있습니다.

⚒️ Markdown → HWPX 변환

use hwpforge::md::MdDecoder;
use hwpforge::hwpx::{HwpxEncoder, HwpxRegistryBridge};

let md_doc = MdDecoder::decode_with_default("# 제목\n\nMarkdown에서 변환!").unwrap();
let bridge = HwpxRegistryBridge::from_registry(&md_doc.style_registry).unwrap();
let rebound = bridge.rebind_draft_document(md_doc.document).unwrap();
let validated = rebound.validate().unwrap();
let image_store = hwpforge::core::ImageStore::new();
let bytes = HwpxEncoder::encode(&validated, bridge.style_store(), &image_store).unwrap();

Feature Flags

| Feature | 기본값 | 설명 | | ------- | ------ | -------------------- | | hwpx | Yes | HWPX encoder/decoder | | md | — | Markdown ↔ Core 변환 | | full | — | 모든 기능 포함 |

# Markdown 지원 포함
hwpforge = { version = "0.7", features = ["full"] }

📜 지원 콘텐츠

| 카테고리 | 요소 | | ------------- | -------------------------------------------------------------------- | | 텍스트 | Run, character shape, paragraph shape, style (22개 한컴 기본 스타일) | | 구조 | Table (중첩), Image (바이너리 + 경로), TextBox, Caption | | 레이아웃 | 다단, 페이지 설정, 가로/세로 방향, 제본 여백, master page | | 머리글/바닥글 | Header, Footer, 쪽번호 (autoNum) | | 각주/미주 | 각주, 미주 | | 도형 | 선, 타원, 다각형, 호, 곡선, 연결선 (채움, 회전, 화살표 지원) | | 수식 | HancomEQN script 형식 | | 차트 | 18종 chart type (OOXML 호환) | | 참조 | 책갈피, 상호 참조, 필드 (날짜/시간/요약), 메모, 색인 | | 덧말/겹침 | 덧말 (dutmal), 글자 겹침 | | Markdown | GFM decode, lossy + lossless encode, YAML frontmatter |

아키텍처

HwpForge는 레이어를 나눠서 생각하는 프로젝트입니다.

• foundation: 공통 primitive, unit, index, error
• core: 포맷 독립 문서 모델과 shared semantics
• blueprint: 스타일 정의와 템플릿 계층
• smithy-*: 포맷별 codec과 bridge (각 크레이트는 단일 포맷만 담당)
• convert: 포맷 간 변환 오케스트레이터 (HWP5 → HWPX, smithy 위에서 두 포맷을 엮음)
• bindings-*: CLI / MCP / Python 진입점

레이어 구조

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#BDBDBD'}}}%%
flowchart TB
    F["foundationprimitive typesunits / indices / errors"]:::foundation
    C["coreshared document modellist / tab / paragraph semantics"]:::core
    B["blueprintstyle registrytemplate authoring"]:::blueprint

    SHX["smithy-hwpxHWPX read/write"]:::smithy
    SH5["smithy-hwp5HWP5 read / audit / re-emission path"]:::smithy
    SMD["smithy-mdMarkdown bridge"]:::smithy

    CONV["convertHWP5 → HWPX orchestrator"]:::convert

    CLI["bindings-cliHammer"]:::binding
    MCP["bindings-mcpAnvil MCP Server"]:::binding
    PY["bindings-pystub"]:::binding

    F --> C
    C --> B
    C --> SHX
    C --> SH5
    C --> SMD
    B --> SHX
    B --> SMD
    C --> CONV
    SHX --> CONV
    SH5 --> CONV
    SHX --> CLI
    SH5 --> CLI
    SMD --> CLI
    CONV --> CLI
    SHX --> MCP
    SMD --> MCP
    SHX --> PY

    classDef file fill:#FFFDE7,stroke:#F9A825,color:#5D4037
    classDef smithy fill:#FFF3E0,stroke:#FB8C00,color:#E65100
    classDef convert fill:#E0F2F1,stroke:#00897B,color:#004D40
    classDef core fill:#E3F2FD,stroke:#42A5F5,color:#0D47A1
    classDef blueprint fill:#F3E5F5,stroke:#AB47BC,color:#4A148C
    classDef foundation fill:#FAFAFA,stroke:#BDBDBD,color:#424242
    classDef binding fill:#E8F5E9,stroke:#43A047,color:#1B5E20

데이터 흐름

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#BDBDBD'}}}%%
flowchart LR
    HWP5[".hwp"]:::file --> SH5["smithy-hwp5"]:::smithy
    MD[".md"]:::file --> SMD["smithy-md"]:::smithy
    HWPX[".hwpx"]:::file  SHX["smithy-hwpx"]:::smithy

    SH5 --> CORE["core document"]:::core
    SHX  CORE
    SMD  CORE
    CORE --> SHX

    CONV["convertHWP5→HWPX 오케스트레이션"]:::convert --> SH5
    CONV --> SHX

    CLI["CLI"]:::binding --> CONV
    CLI --> SH5
    CLI --> SHX
    CLI --> SMD
    MCP["MCP"]:::binding --> SHX
    MCP --> SMD

    classDef file fill:#FFFDE7,stroke:#F9A825,color:#5D4037
    classDef smithy fill:#FFF3E0,stroke:#FB8C00,color:#E65100
    classDef convert fill:#E0F2F1,stroke:#00897B,color:#004D40
    classDef core fill:#E3F2FD,stroke:#42A5F5,color:#0D47A1
    classDef binding fill:#E8F5E9,stroke:#43A047,color:#1B5E20

핵심 원칙: 구조(Structure)와 스타일(Style)을 분리합니다. core는 shared semantics와 스타일 참조를 들고, blueprint는 스타일 정의를 관리합니다. smithy-* 계층이 포맷 surface를 연결합니다.

실전에서 가장 자주 쓰는 경로는 다음 셋입니다.

1. Markdown → HWPX
2. HWPX → Markdown / JSON
3. HWP5 → HWPX → audit / inspect

프로젝트 현황

| 지표 | 값 | | ---------------------- | ----------------------- | | Tracked Rust src LOC | ~112,977 | | 테스트 | 2,647개 (cargo-nextest) | | 소스 파일 | 176 .rs | | Crate 수 | 11개 | | 커버리지 | 90%+ | | Clippy 경고 | 0 | | Unsafe 코드 | 0 |

개발

필수 요구사항

• Rust 1.88+ (MSRV)
• (권장) cargo-nextest — 병렬 테스트 실행
• (선택) pre-commit — git hook 자동화

MSRV 정책

• 현재 MSRV는 Rust 1.88입니다.
• HwpForge는 stable에서 4 릴리스 뒤처진 버전을 기본 MSRV 정책으로 유지합니다.
• Cargo.toml의 rust-version이 단일 진실원이며, CI의 Verify › MSRV job이 이 계약을 검증합니다.
• MSRV 상향이 필요하면 PR에서 이유를 명시하고, Cargo.toml, CI, CHANGELOG를 함께 갱신합니다.
• 개발용 기본 툴체인은 더 최신일 수 있습니다. 호환성 판단 기준은 최신 stable이 아니라 MSRV + CI 통과 여부입니다.

⚒️ 명령어

make ci          # fmt + clippy + test + deny + lint (CI와 동일)
make test        # cargo nextest run
make clippy      # cargo clippy (모든 target, 모든 feature, -D warnings)
make fmt-fix     # rustfmt 자동 포맷
make doc         # rustdoc 생성 (브라우저에서 열림)
make cov         # coverage 리포트 (90% gate)

> 빌드 가속 (선택): sccache가 PATH에 있으면 make 타깃이 자동으로 컴파일 > 캐시로 사용합니다(없으면 그대로 동작 — 아무것도 깨지지 않음). 반복 make ci가 > 크게 빨라집니다. 설치: cargo install sccache 또는 brew install sccache. > (릴리스 파이프라인 release-plz 는 영향받지 않습니다.)

프로젝트 구조

HwpForge/
├── crates/
│   ├── hwpforge/                 # Umbrella crate (re-exports)
│   ├── hwpforge-foundation/      # 기본 타입 (HwpUnit, Color, Index)
│   ├── hwpforge-core/            # 문서 모델 (스타일 참조만)
│   ├── hwpforge-blueprint/       # YAML 템플릿 (Figma 패턴)
│   ├── hwpforge-smithy-hwpx/     # HWPX codec (ZIP+XML ↔ Core)
│   ├── hwpforge-smithy-md/       # Markdown codec (MD ↔ Core)
│   ├── hwpforge-smithy-hwp5/     # HWP5 decode/projection + inspect helpers
│   ├── hwpforge-convert/         # 포맷 간 변환 오케스트레이터 (HWP5 → HWPX)
│   ├── hwpforge-bindings-py/     # Python bindings (stub)
│   ├── hwpforge-bindings-cli/    # CLI 도구 (hwpforge, shipped)
│   └── hwpforge-bindings-mcp/    # MCP Server (hwpforge-mcp)
├── tests/                        # 통합 테스트 + golden fixture
└── examples/                     # curated showcase + interop artifacts
    ├── showcase/
    └── interop/

기여

버그 수정, 포맷 리서치, 테스트 보강, 문서 개선 모두 환영합니다.

• 시작 전 가이드: [CONTRIBUTING.md](CONTRIBUTING.md)
• 특히 확인할 것: release-plz가 쓰는 커밋 prefix (feat, fix, perf, refactor)
• 특히 확인할 것: MSRV 정책과 dependency/MSRV 상승 기준
• 특히 확인할 것: 문서 변경 시 mdbook build와 markdown lint 검증
• 특히 확인할 것: 로컬 docs toolchain은 CI와 같은 pinned 버전(mdbook 0.4.52, mdbook-admonish 1.20.0, mdbook-mermaid 0.16.2)을 쓰는 편이 낫습니다. 가장 쉬운 방법은 make install-tools
• 특히 확인할 것: CI required checks를 깨지 않는 범위에서의 변경 분리

로드맵

현재 상태와 다음 단계

• [x] HWP5 읽기/점검/재출력 경로 — convert-hwp5, audit-hwp5, census-hwp5
• [ ] HWP5 public API 확대 — umbrella crate surface와 broader parity 정리
• [x] MCP 서버 — Claude, Cursor 등 AI 도구가 tool로 직접 HWPX 생성·검증·편집 (9개 도구 + 4 리소스 + 3 프롬프트)
• [x] CLI 도구 — hwpforge convert doc.md doc.hwpx 한 줄 변환 (7개 명령어)
• [ ] HWPX 완전 지원 — 양식 컨트롤, 변경 추적, OLE 객체
• [ ] Python 바인딩 — pip install hwpforge로 설치, PyPI 배포

라이선스

다음 중 하나를 선택할 수 있습니다:

• Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
• MIT license ([LICENSE-MIT](LICENSE-MIT))

Acknowledgements

HwpForge는 거인들의 어깨 위에 서 있습니다.

• Hancom — HWPX 포맷의 공개 문서와 KS X 6101 (OWPML) 국가 표준이 없었다면 이 프로젝트는 시작조차 할 수 없었습니다. 포맷을 공개해 주신 Hancom에 감사드립니다.
• openhwp — Rust로 HWP/HWPX를 다루는 IR 기반 아키텍처 설계에서 큰 영감을 받았습니다. HwpForge의 Core 레이어가 존재할 수 있었던 것은 openhwp이 먼저 그 길을 걸었기 때문입니다.
• hwpxlib — Java로 작성된 가장 성숙한 HWPX 구현체입니다. 스펙과 실제 동작의 차이를 파악하는 데 결정적인 참고가 되었습니다.
• hwp.js — HWP5 포맷의 quirks와 edge case를 꼼꼼히 문서화한 프로젝트입니다. 바이너리 포맷의 어두운 구석을 밝혀 준 덕분에 시행착오를 크게 줄일 수 있었습니다.
• hwpx-owpml-model — Hancom이 직접 공개한 C++ OWPML 모델 구현체

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ai-screams
• Source: ai-screams/HwpForge
• License: Apache-2.0
• Homepage: https://ai-screams.github.io/HwpForge/

Install and usage instructions live in the source repository linked above.