HwpForge 🔥

Rust로 한글(HWP/HWPX) 문서를 프로그래밍 방식으로 제어

Hancom 한글 파일 읽기, 쓰기, 변환

<div align="center">

</div> <div align="center"> <img src="https://raw.githubusercontent.com/ai-screams/HwpForge/main/assets/banner-main.png" alt="HwpForge Banner" width="600"> </div>

---

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 완전 가이드 다운로드 — 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.5"

🔨 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 < modified.json -o updated.hwpx

# JSON Schema 출력 (AI agent용)
hwpforge schema document

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 지원 AI 도구에서 한글 문서를 직접 생성하고 편집할 수 있습니다. 현재 MCP surface는 베타이며, HWP5 경로는 MCP가 아니라 CLI workflow를 우선합니다. "보고서 만들어줘"라고 말하면, AI가 알아서 .hwpx 파일을 뚝딱 만들어냅니다.

AI 도구에 등록

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

<details> <summary><strong>Claude Code</strong> (터미널)</summary>

# 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

</details> <details> <summary><strong>Codex CLI</strong> (터미널)</summary>

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

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

또는 CLI로:

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

</details> <details> <summary><strong>Claude Desktop</strong> (앱)</summary>

설정 파일을 편집합니다:

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

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

</details> <details> <summary><strong>ChatGPT Desktop</strong> (앱)</summary>

Settings → Tools → Add MCP Server에서:

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

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

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

</details> <details> <summary><strong>Cursor</strong> (에디터)</summary>

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

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

</details> <details> <summary><strong>Antigravity</strong> (에디터)</summary>

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

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

</details>

등록하면 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::<Draft>::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가 한글 문서 읽기)

<div align="center"> <table> <tr> <td align="center"><strong>📄 한글 원본 (.hwpx)</strong></td> <td align="center"><strong>📝 Markdown 변환 결과</strong></td> </tr> <tr> <td><img src="https://raw.githubusercontent.com/ai-screams/HwpForge/main/assets/hwpx-original.png" width="400" alt="한글 원본 문서"></td> <td><img src="https://raw.githubusercontent.com/ai-screams/HwpForge/main/assets/hwpx-to-md-result.png" width="400" alt="Markdown 변환 결과"></td> </tr> </table> </div>

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 =