Enables AI agents to programmatically create, read, and edit Korean HWPX documents through Markdown and JSON round-trip conversions.
Also known as ai-screams/HwpForge, @hwpforge/mcp
- Stars
- 20
- Tools
- 19
- Downloads, 30 days
- 1,720
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- Apache-2.0
What is HwpForge MCP?
HwpForge enables AI agents to programmatically create, read, and edit Korean HWPX documents through Markdown and JSON round-trip conversions. It exposes 19 tools, such as hwpforge_convert, hwpforge_delete_para, hwpforge_diff.
Summary generated from the project's README
About HwpForge MCP server
Developers working with Korean word processing formats can use HwpForge to programmatically manage HWPX documents. This MCP server allows AI agents to bridge the gap between Markdown and official Hancom HWPX files through a bidirectional conversion process. By integrating with clients like Claude Desktop, Cursor, or ChatGPT, an AI can directly create, read, and edit documents without requiring manual file handling or complex shell commands.
The server provides 19 specialized tools for deep document manipulation. Users can convert Markdown to HWPX using hwpforge_convert, extract document content into machine-readable formats with hwpforge_to_json, or perform precise edits on specific sections via hwpforge_patch. It also supports advanced features like filling out form fields with hwpforge_fill, managing table cells with hwpforge_set_cell, and applying visual styles using hwpforge_restyle. While it primarily targets the modern HWPX format, it can also read legacy HWP5 files by automatically converting them to HWPX for processing.
Written from the project's README. Every use case is checked against a quote from it.
How to install HwpForge MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall HwpForge MCP in Claude Code
$ claude mcp add hwpforge -- npx -y @hwpforge/mcpInstall HwpForge MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"hwpforge": {
"command": "npx",
"args": [
"-y",
"@hwpforge/mcp"
]
}
}
}Install HwpForge MCP in VS Code
.vscode/mcp.json
{
"servers": {
"hwpforge": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@hwpforge/mcp"
]
}
}
}Install HwpForge MCP in VS Code CLI
$ code --add-mcp '{"name":"hwpforge","type":"stdio","command":"npx","args":["-y","@hwpforge/mcp"]}'Install HwpForge MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"hwpforge": {
"command": "npx",
"args": [
"-y",
"@hwpforge/mcp"
]
}
}
}Install HwpForge MCP in Codex
$ codex mcp add hwpforge -- npx -y @hwpforge/mcpInstall HwpForge MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.hwpforge] command = "npx" args = ["-y", "@hwpforge/mcp"]
Install HwpForge MCP in Gemini CLI
$ gemini mcp add -s user hwpforge npx -- -y @hwpforge/mcpInstall HwpForge MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"hwpforge": {
"command": "npx",
"args": [
"-y",
"@hwpforge/mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @hwpforge/mcp 0.20.1 in an isolated container with no network and no keys. It answered and listed 19 tools.
HwpForge MCP tools 19
Read from the server with tools/listhwpforge_convertConvert Markdown to a Korean HWPX document (KS X 6101 standard). Supports GFM tables, images, headings, and Korean typography. Returns the output file path and document summary. The original package's signature or encryption state is not inherited when rebuilding from Markdown.
hwpforge_delete_paraDelete top-level body paragraphs by index, all-or-nothing, keeping unrelated content. Admission-approved deletion updates affected layout caches. Fail-closed: refuses a paragraph carrying a reference (bookmark/cross-ref/footnote/…), a hard page/column break, the section properties (the first paragraph), or that would empty the section. Delete can also remove verified plain or empty top-level body paragraphs from Hancom-saved HWPX. Indexes refer to positions in the input. The source-preserving path accepts one paragraph per request and removes only that paragraph, preserving surviving line caches, table heights, IDs and unrelated part payloads. It removes Preview and its connections with PREVIEW_REMOVED. Documents whose line widths may depend on position retain their original admission error. Saving again in Hancom rebuilds the preview. Unverifiable inputs retain their original admission error and produce no output. CONTENT_LOST reports information not represented by the input decode. Source-preserving delete succeeds only after separately proving that information survives in the output and does not affect the deletion decision; the original decode warnings remain. This applies only to some losses whose information remains in the source XML (such as per-language character values); all other CONTENT_LOST inputs retain their original refusal. Input-loss refusals for whole-document re-encoding edits remain in force. Verify the result with hwpforge_diff.
hwpforge_diffCompare two HWPX files. semantic channel = decoded Core structure classified into field values, table-cell text {table,row,col}, paragraph text {section,para}, structure counts, and a capped unclassified remainder; package channel = ZIP entries compared by bytes. Run after hwpforge_fill / hwpforge_set_cell / hwpforge_stamp / hwpforge_patch to confirm only the intended delta landed. Wire content inside a changed entry (e.g. layout caches) is not itemized — the report states its comparison levels explicitly.
hwpforge_fieldsList named click-here fields (누름틀) in an HWPX document: name, hint, current value, and whether each is fillable. Use before hwpforge_fill to discover field names.
hwpforge_fillFill named click-here fields by name→value map. When hwpforge_patch or hwpforge_fill changes content in a document with existing Hancom previews (Preview), it removes them and reports PREVIEW_REMOVED. Saving again in Hancom recreates them. Document re-encoding, such as header normalization, is outside this guarantee. All values are validated before writing. Use hwpforge_fields to discover names.
hwpforge_from_jsonCreate an HWPX document directly from a JSON structure (ExportedDocument schema). The original package's signature or encryption state is not inherited. Use when building documents programmatically without Markdown. Get the schema from hwpforge_to_json output. For large documents, prefer hwpforge_to_json + hwpforge_patch workflow with file paths instead of inline JSON.
hwpforge_insert_paraInsert new top-level paragraphs before or after an anchor paragraph, keeping unrelated content and updating affected layout caches: text for one paragraph, or texts for a contiguous block inserted in order in one verified edit. Each new paragraph inherits the anchor's paragraph and character shape (no style is invented); every entry is a single line of plain text. Insert-before the section's first paragraph is refused. Only round-trip-safe inputs are editable: a document whose ZIP entries the encoder cannot all carry — a document saved by Hancom, which adds Preview/* and META-INF/container.rdf — is refused here, while hwpforge_to_json + hwpforge_patch (text) and hwpforge_fill (click-here fields) still accept it. Verify with hwpforge_diff.
hwpforge_inspectInspect an HWPX document structure. Returns section count, paragraph counts, tables, images, charts, headers, footers, page numbers per section, and any decode warnings. A count's prefix names its scope: unprefixed keys are top-level only, `all_*` counts objects anywhere in the section including captions but not master pages, and `deep_*` counts paragraphs recursing into table cells, text boxes, notes and memos. The scopes can disagree on documents with nested content.
hwpforge_outlineShow the document navigation map for an HWPX file: headings (level + text), tables (ordinal + logical grid dims + addressable), named click-here fields, and bookmarks. Name anchors are the primary keys; {section, para} locators are secondary and go stale after structural edits. Fetch this once before targeted reads or edits.
hwpforge_patchReplace a section in an existing HWPX file with edited JSON data. Preserves images and styles from the base file. Use after hwpforge_to_json for surgical edits. Text-only: the edited JSON must keep the section's paragraph structure — a replacement whose semantic text slots differ in count or path is refused. Add or remove paragraphs with hwpforge_insert_para / hwpforge_delete_para, change table cells with hwpforge_set_cell, and rebuild a restructured document with hwpforge_from_json.
hwpforge_readRead a targeted text projection without exporting the whole document. Exactly one target: section (paragraph range via optional paras "A..B") for text with outline/list kinds; table (ordinal) for the logical grid text matrix (merged regions appear once at their anchor with spans); field (name) for a named click-here field. Non-text content surfaces as explicit markers. Read-only: to change what you read, use hwpforge_fill / hwpforge_set_cell / hwpforge_patch.
hwpforge_restyleApply a different style template (preset) to an existing HWPX document. Replaces fonts and paragraph styles while preserving document content and structure. Use hwpforge_templates to discover available presets.
Show all 19 toolsShow fewer tools
hwpforge_set_cellEdit table cells by logical grid address in an HWPX file. Address a cell with a table ordinal (to-json export order) plus at {row,col} (covered positions resolve to their merge anchor), right_of LABEL, or below LABEL (normalized exact match). Empty text clears the cell. All-or-nothing. If every requested cell is in a direct body table with one paragraph and one Text run (including an empty run), and its source location and header can be preserved, only its text slot is changed; paragraph/table properties and source outside the slot are preserved. Changed values remove existing Preview and its connections with PREVIEW_REMOVED; unchanged values return the original bytes. If any cell is outside this subset or its text cannot be spliced, the whole batch uses re-encoding with the existing round-trip and package-preservation admission checks, which can refuse Hancom-saved documents carrying Preview/* or META-INF/container.rdf. Cells containing tables/images/controls are rejected. Address errors and verification failures return errors. For other text edits, use hwpforge_to_json + hwpforge_patch; for click-here fields, use hwpforge_fill.
hwpforge_stampPromote prose placeholders to named click-here fields (누름틀) using the approved spec list from hwpforge_stamp_plan. Fail-closed admission gate (lossless round-trip + ZIP closed-world) + all-or-nothing preflight; writes the stamped HWPX and a manifest. The gate refuses a document whose ZIP entries the encoder cannot all carry — a document saved by Hancom, which adds Preview/* and META-INF/container.rdf — while hwpforge_to_json + hwpforge_patch (text) and hwpforge_fill (click-here fields) still accept it. The output is immediately usable with hwpforge_fields/hwpforge_fill.
hwpforge_stamp_planDiscover class-A placeholder candidates (checkbox/paren-blank/date-blank/standalone-@/seal tokens) in an HWPX for template stamping. Author one spec per candidate (field name or ignore) and pass them to hwpforge_stamp. Guarded candidates (instruction context) are never auto-applied.
hwpforge_templatesList available style presets (templates) for HWPX document generation. Returns preset names, descriptions, fonts, and page sizes. Call before hwpforge_convert to choose a preset.
hwpforge_to_jsonExport HWPX to JSON for editing. Use section parameter (0-based) to extract a single section for token efficiency. Returns JSON inline while the serialized response stays under 1 MB — the document JSON is escaped into a string field, so the effective document-JSON limit is content-dependent and below 1 MB (typically ~750-800 KB); larger exports are rejected with OUTPUT_TOO_LARGE — or writes to file with output_path.
hwpforge_to_mdConvert an HWPX document to Markdown. Extracts text, headings, tables, and images from the HWPX file. Returns the path to the generated Markdown file and any extracted image files.
hwpforge_validateValidate an HWPX file structure and integrity. Returns validation status, section/paragraph counts, any issues found, and any decode warnings (present whether or not the document validated). A file that cannot even be decoded (wrong format, corrupt package — for example a .hwp file) is reported as a DECODE_FAILED error, not as an invalid document. Use to verify files before editing or after generation.
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableai-screams/hwpforge is public and reachablegithub.com/ai-screams/hwpforge ↗Pass
- Package names this repository as its source@hwpforge/mcp names ai-screams/hwpforge as sourcenpmjs.com/package/@hwpforge/mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @hwpforge/mcpnpmjs.com/package/@hwpforge/mcp/v/0.20.0#provenance ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/ai-screams/hwpforge ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @hwpforge/mcpPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubHwpForge 🔥
Rust로 한글(HWP/HWPX) 문서를 프로그래밍 방식으로 제어
Hancom 한글 파일 읽기, 쓰기, 변환
본 제품은 한컴의 HWP 문서 파일(.hwp) 공개 문서를 참고하여 개발하였습니다.
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·Python의 지원 읽기·편집 연산은
.hwp입력을 자동 변환하며, 편집 결과는.hwpx입니다..hwp저장은 지원하지 않습니다. 의미 손실이 있으면 편집을 거부하며, 경고 검토 후 CLI--accept-conversion-loss또는 Pythonaccept_conversion_loss=True로 변환 손실만 허용합니다. 대상 명령과 원본 보호는 CLI 입력 정책을 참고합니다. - 스타일 세트는
HancomStyleSetenum으로 선택 가능 (기본: Modern)
LLM-first 설계 🔥 — AI 친화적인 Markdown과 공식 한글 문서 포맷(HWPX), 두 세계를 자연스럽게 잇습니다. LLM이 Markdown으로 작성한 내용은 공문서 규격의 HWPX로 컴파일되고 📜, 반대로 기존 HWPX 문서는 AI가 쉽게 읽을 수 있는 구조로 꺼낼 수 있습니다 ⚒️.
- 📄 HWPX 완전 가이드 다운로드 — HwpForge API로 생성한 4섹션 데모 문서 (한글에서 열어보세요)
- 📚 문서 사이트 — ai-scream.ai/HwpForge: 시작하기, 사용 가이드(Python·Markdown 변환·스타일 템플릿 등), API 레퍼런스
- 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.20"
🔨 Hammer — CLI로 시작하기
CLI 도구 hwpforge(Hammer)를 설치하면 터미널에서 바로 문서를 생성하고 편집할 수 있습니다. hwpforge-bindings-cli는 crates.io에 배포되지 않으므로(publish = false), git 또는 로컬 경로에서 설치합니다. hwpforge-smithy-pdf(krilla) 의존으로 워크스페이스 MSRV(1.89)보다 높은 Rust 1.92+가 필요합니다.
cargo install --git https://github.com/ai-screams/HwpForge hwpforge-bindings-cli
# 또는 clone 후 로컬 경로에서
git clone https://github.com/ai-screams/HwpForge && cd HwpForge
cargo install --path crates/hwpforge-bindings-cli
# Markdown → HWPX 변환
hwpforge convert report.md -o report.hwpx
# HWPX 구조 확인
hwpforge inspect report.hwpx
# 문서 내비게이션 맵 확인 (제목·표·필드·책갈피)
hwpforge outline report.hwpx
# HWPX → Markdown 변환 (AI가 한글 문서 읽기)
hwpforge to-md report.hwpx -o report.out.md
# HWPX → JSON 추출 (AI 편집용) — -o 는 필수, stdout 내보내기는 없습니다
hwpforge to-json report.hwpx --section 0 -o section0.json # 섹션 하나 (patch 용)
hwpforge to-json report.hwpx -o full.json # 문서 전체 (from-json 용)
# 섹션 JSON을 원본에 되쓰기 (텍스트만 바뀜, 원본이 base)
hwpforge patch report.hwpx --section 0 section0.json -o updated.hwpx
# 문서 전체 JSON으로 새 문서 만들기 (구조 변경까지 가능)
hwpforge from-json full.json -o new.hwpx
# 문서 구조 검증 (Core 불변조건 통과 여부)
hwpforge validate report.hwpx
# JSON Schema 출력 (AI agent용)
hwpforge schema document
두 JSON은 서로 다른 형식입니다. --section 없이 뽑은 문서 전체 JSON은 from-json이 읽고, --section N으로 뽑은 섹션 JSON은 patch가 원본 문서를 base로 삼아 되씁니다. 서로 바꿔 넣으면 스키마 불일치로 거부됩니다.
누름틀 채우기는 누름틀(click-here field)이 들어 있는 서식 문서에서만 동작합니다. 방금 convert로 만든 문서에는 누름틀이 없어 FIELD_NOT_FOUND가 납니다 — fields로 이름을 먼저 확인하세요.
hwpforge fields form.hwpx # 채울 수 있는 필드 이름
hwpforge fill form.hwpx --set 회사명=HwpForge -o filled.hwpx # 나머지 패키지는 바이트 그대로
PDF 내보내기는 문서에 들어 있는 조판 캐시를 재생하는 방식이라, 캐시가 있는 문서만 렌더할 수 있습니다. 캐시의 출처는 둘입니다 — 한컴이 저장한 HWPX, 그리고 HWP5에서 변환한 HWPX(convert-hwp5 는 기본으로 캐시를 싣습니다). to-pdf는 .hwp를 직접 받아 그 변환을 대신해 주기도 합니다. 반면 convert나 from-json이 새로 만든 문서에는 캐시가 없어 PDF_RENDER_FAILED로 거부됩니다. 문서가 쓰는 폰트도 호스트에 있어야 합니다(--font-dir·--discovery로 지정, 없는 폰트를 대체 글꼴로 렌더하려면 --degraded). 조판 캐시가 없는 문단이 하나라도 있으면 거부하려면 --partial-cache-reject를 줍니다(기본은 경고 후 그 문단을 건너뜀).
hwpforge to-pdf hancom-saved.hwpx -o report.pdf # 한컴이 저장한 문서
hwpforge to-pdf legacy.hwp -o legacy.pdf # HWP5 — 캐시를 실어 변환한 뒤 렌더
convert-hwp5는 기본으로 HWP5의 줄 조판 캐시를 싣습니다. 줄 시작 자리를 정확히 옮길 수 없는 문단은 캐시를 버리고 LAYOUT_CACHE_DROPPED로 알리며, 캐시 없이 쓰려면 --no-layout-cache를 줍니다.
AI-first 설계: CLI는 AI agent(Claude Code 등)가 주 사용자입니다. Markdown으로 문서를 생성한 뒤, JSON round-trip으로 기존 스타일을 보존하면서 section 단위로 정밀하게 편집할 수 있습니다.
--json플래그로 모든 명령어가 machine-readable 출력을 지원합니다.
🗜️ Vise — MCP Server (Beta)로 AI가 직접 한글 문서를 다루다
Claude Code, Codex CLI, Claude, ChatGPT, Cursor, Antigravity 등 MCP 지원 AI 도구에서 한글 문서를 직접 생성하고 편집할 수 있습니다. 현재 MCP surface는 베타이며, MCP의 HWP5 입력은 HWP5_INPUT으로 거부합니다. CLI·Python의 지원 연산은 자동 변환하며, MCP에는 명시적으로 변환한 HWPX를 전달합니다. "보고서 만들어줘"라고 말하면, AI가 알아서 .hwpx 파일을 뚝딱 만들어냅니다.
AI 도구에 등록
한 줄이면 설치 + 등록이 끝납니다. npm은 npx -y가 자동으로 바이너리를 다운로드합니다.
# npm (권장 — Rust 툴체인 불필요)
claude mcp add hwpforge -- npx -y @hwpforge/mcp
# Cargo (Rust 개발자용)
cargo install hwpforge-bindings-mcp && claude mcp add hwpforge hwpforge-mcp
# 모든 프로젝트에서 사용 (user 범위)
claude mcp add --scope user hwpforge -- npx -y @hwpforge/mcp
~/.codex/config.toml에 추가:
[mcp_servers.hwpforge]
command = "npx"
args = ["-y", "@hwpforge/mcp"]
또는 CLI로:
codex mcp add hwpforge -- npx -y @hwpforge/mcp
설정 파일을 편집합니다:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"hwpforge": {
"command": "npx",
"args": ["-y", "@hwpforge/mcp"]
}
}
}
Settings → Tools → Add MCP Server에서:
- Name:
hwpforge - Command:
npx -y @hwpforge/mcp
또는 설정 파일을 직접 편집:
{
"mcpServers": {
"hwpforge": {
"command": "npx",
"args": ["-y", "@hwpforge/mcp"]
}
}
}
프로젝트 루트에 .cursor/mcp.json 생성:
{
"mcpServers": {
"hwpforge": {
"command": "npx",
"args": ["-y", "@hwpforge/mcp"]
}
}
}
... 드롭다운 → MCP Store → Manage MCP Servers → View raw config (mcp_config.json)에 추가:
{
"mcpServers": {
"hwpforge": {
"command": "npx",
"args": ["-y", "@hwpforge/mcp"]
}
}
}
등록하면 19개 도구를 사용할 수 있습니다
| 도구 | 하는 일 | 한마디 |
|---|---|---|
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으로 꺼내줘" |
hwpforge_outline |
문서 내비게이션 맵(제목·표·필드·책갈피) 조회 | "이 문서 구조가 어떻게 생겼어?" |
hwpforge_diff |
두 HWPX 파일을 semantic/package 채널로 비교 | "이 편집이 뭘 바꿨는지 확인해줘" |
hwpforge_delete_para |
최상위 문단 삭제 (구조 편집) | "이 문단 지워줘" |
hwpforge_insert_para |
앵커 문단 기준 새 문단 삽입 | "이 문단 다음에 내용 추가해줘" |
hwpforge_read |
문단/표/필드 중 하나를 타겟 읽기 | "이 부분만 딱 읽어줘" |
hwpforge_fields |
누름틀 필드 목록 조회 | "채울 수 있는 칸이 뭐가 있어?" |
hwpforge_fill |
누름틀 필드에 값 채우기 | "이 필드들 채워줘" |
hwpforge_stamp_plan |
문장 속 빈칸 스탬핑 후보 탐색 | "채울 수 있는 빈칸 후보 찾아줘" |
hwpforge_stamp |
후보를 누름틀 필드로 승격 | "이 빈칸들을 필드로 만들어줘" |
hwpforge_set_cell |
표 셀을 그리드 주소로 편집 | "이 표 칸 값 바꿔줘" |
업데이트 / 삭제
npm은 npx -y가 항상 최신 버전을 가져오므로 별도 업데이트가 필요 없습니다.
# Cargo 사용자만 해당
cargo install hwpforge-bindings-mcp --force # 업데이트
cargo uninstall hwpforge-bindings-mcp # 삭제
왜 MCP? CLI(Hammer)는 AI가
bash명령을 실행해야 하지만, MCP(Vise)는 AI가 네이티브 도구로 직접 호출합니다. 파일 경로 파싱도, stdout 해석도 필요 없습니다. JSON-RPC로 요청하면 구조화된 JSON으로 응답 — 깔끔합니다.
🐍 Tongs — Python으로 시작하기
pip install hwpforge
CPython 3.9+ 전용 abi3 wheel을 Linux(manylinux_2_28 x86_64/aarch64)·macOS(11+ arm64, 10.12+ x86_64)·Windows(x64)에 배포하며, 런타임 의존성은 0개입니다. pyproject.toml에 직접 핀할 때는 정확 핀(==)보다 ~=를 권장합니다 — Python 전용 패치(X.Y.Z.N)는 정확 핀으로는 받을 수 없습니다.
import hwpforge
doc = hwpforge.Document.open("proposal.hwpx")
print(doc.outline()["outline"]["title"])
doc = doc.fill({"applicant": "홍길동", "date": "2026-09-17"}).document
doc.save("proposal-filled.hwpx")
Document는 불변 값입니다 — 모든 편집 메서드는 원본을 그대로 둔 채 새 문서와 보고서를 담은 DocumentResult를 반환합니다. 공유 연산 계층을 쓰는 18개 document 메서드 + 5개 모듈 함수를 제공하며, 호출 이름·옵션 표기·호환 에러 코드는 바인딩마다 다를 수 있습니다. 자세한 내용은 hwpforge 패키지 README를 참고하세요.
🔨 문서 생성
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가 한글 문서 읽기)
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 변환 |
ops-hwpx |
— | HWPX 전용 표면(inspect·exchange·read·edit·diff·stamp·style)의 공유 연산 계층 |
ops-md |
— | ops에 Markdown 연산(convert_md, to_md) 추가 (ops-hwpx + md 포함) |
ops |
— | 전체 연산 계층의 별칭 (ops-md와 같음) |
schemars |
— | ops가 소유한 wire DTO와 exchange DTO에 JsonSchema derive 추가 |
full |
— | hwpx + md + ops (schemars는 포함하지 않음) |
# Markdown 지원과 공유 연산 계층 포함 (schemars 제외)
hwpforge = { version = "0.20", features = ["full"] }
📜 지원 콘텐츠
| 카테고리 | 요소 |
|---|---|
| 텍스트 | Run, character shape, paragraph shape, style (한컴 기본 스타일 18/22/23개, 스타일 세트별) |
| 구조 | Table (중첩), Image (바이너리 + 경로), TextBox, Caption |
| 레이아웃 | 다단, 페이지 설정, 가로/세로 방향, 제본 여백, master page |
| 머리글/바닥글 | Header, Footer, 쪽번호 (autoNum) |
| 각주/미주 | 각주, 미주 |
| 도형 | 선, 사각형, 타원, 다각형, 호, 곡선, 연결선, 묶음(Group), 글맵시(TextArt) (채움, 회전, 화살표 지원) |
| 수식 | HancomEQN script 형식 |
| 차트 | 18종 chart type (OOXML 호환) |
| 참조 | 책갈피, 상호 참조, 필드 (날짜/시간/요약), 메모, 색인 |
| 덧말/겹침 | 덧말 (dutmal), 글자 겹침 |
| Markdown | GFM decode, lossy + lossless encode, YAML frontmatter |
| PDF 내보내기 | 한컴 조판 캐시 재생(계산 아님) 렌더 — 표·머리글/바닥글·쪽번호·폰트 파이프라인 |
아키텍처
HwpForge는 레이어를 나눠서 생각하는 프로젝트입니다.
foundation: 공통 primitive, unit, index, errorcore: 포맷 독립 문서 모델과 shared semanticsblueprint: 스타일 정의와 템플릿 계층smithy-*: 포맷별 codec과 bridge (각 크레이트는 단일 포맷만 담당)convert: 포맷 간 변환 오케스트레이터 (HWP5 → HWPX, smithy 위에서 두 포맷을 엮음)와 PDF 렌더 연산(ops::to_pdf)bindings-*: CLI / MCP / Python 진입점
hwpforge(umbrella crate)의 ops 모듈과 hwpforge-convert의 ops 모듈은 세 바인딩이 공유하는 연산 계층입니다 — CLI·MCP·Python 모두 이 계층을 거쳐 호출합니다. 아래 그림의 화살표는 각 크레이트 Cargo.toml의 [dependencies] 직접 의존을 따르며, 모든 크레이트가 의존하는 foundation과 바인딩의 core 직접 의존은 생략했습니다.
레이어 구조
%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#BDBDBD'}}}%%
flowchart TB
F["foundation<br/>primitive types<br/>units / indices / errors"]:::foundation
C["core<br/>shared document model<br/>list / tab / paragraph semantics"]:::core
B["blueprint<br/>style registry<br/>template authoring"]:::blueprint
SHX["smithy-hwpx<br/>HWPX read/write"]:::smithy
SH5["smithy-hwp5<br/>HWP5 read / audit / re-emission path"]:::smithy
SMD["smithy-md<br/>Markdown bridge"]:::smithy
SPDF["smithy-pdf<br/>layout-cache replay renderer"]:::smithy
HWPF["hwpforge<br/>umbrella crate + ops<br/>(feature: hwpx / md / ops)"]:::umbrella
CONV["convert<br/>HWP5 → HWPX + PDF ops"]:::convert
CLI["bindings-cli<br/>Hammer"]:::binding
MCP["bindings-mcp<br/>Vise MCP Server"]:::binding
PY["bindings-py<br/>Tongs (Python)"]:::binding
F --> C
C --> B
C --> SHX
C --> SH5
C --> SMD
C --> SPDF
C --> CONV
C --> HWPF
B --> SHX
B --> SMD
B --> HWPF
SHX --> HWPF
SMD --> HWPF
SHX --> CONV
SH5 --> CONV
SPDF --> CONV
HWPF --> CLI
SHX --> CLI
SH5 --> CLI
SMD --> CLI
SPDF --> CLI
CONV --> CLI
HWPF --> MCP
SHX --> MCP
SMD --> MCP
HWPF --> PY
CONV --> PY
SPDF --> 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 umbrella fill:#FFFFFF,stroke:#6D4C41,color:#3E2723
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["convert<br/>HWP5→HWPX 오케스트레이션 + PDF"]:::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를 연결합니다.
실전에서 가장 자주 쓰는 경로는 다음 셋입니다.
- Markdown → HWPX
- HWPX → Markdown / JSON
- HWP5 → HWPX 자동 변환 → CLI·Python 읽기·편집 (
.hwpx출력)
프로젝트 현황
| 지표 | 값 |
|---|---|
| Crate 수 | 12개 |
| 커버리지 | CI 게이트 90% 이상 (줄 기준) |
| Clippy 경고 | 0 |
| Unsafe 코드 | 0 |
개발
필수 요구사항
- Rust 1.89+ (워크스페이스 MSRV) —
hwpforge-bindings-cliCLI를 직접 빌드/설치하려면 krilla 의존으로 1.92+ 필요 - (권장) cargo-nextest — 병렬 테스트 실행
- (선택) pre-commit — git hook 자동화
MSRV 정책
- 워크스페이스 기본 MSRV는 Rust 1.89이며, stable에서 4 릴리스 뒤처진 버전을 기본 정책으로 유지합니다.
- krilla 의존 경로에 있는 네 크레이트(
hwpforge-smithy-pdf·hwpforge-convert·hwpforge-bindings-cli·hwpforge-bindings-py)는 Rust 1.92+가 필요합니다(rust-version을 크레이트별로 상향 지정). CI의Verify › MSRVjob은 이 넷을 1.89 검증 패스에서는 제외하지만, 같은 job 안에서cargo +1.92 check로 따로 검증합니다 — 검증 대상에서 빠지는 것이 아닙니다. - 각 크레이트의
Cargo.toml의rust-version이 그 크레이트의 실제 MSRV이며, CI의Verify › MSRVjob이 워크스페이스 기본값(1.89)을 검증합니다. - MSRV 상향이 필요하면 PR에서 이유를 명시하고,
Cargo.toml, CI, CHANGELOG를 함께 갱신합니다. - 개발용 기본 툴체인은 더 최신일 수 있습니다. 호환성 판단 기준은 최신 stable이 아니라 MSRV + CI 통과 여부입니다.
⚒️ 명령어
make ci # 빠른 로컬 검증 — fmt + clippy + test + deny + lint-md (ci-fast 별칭)
make ci-full # 위에 coverage + MSRV 추가 (릴리스·큰 변경 전)
make py-all # Python 바인딩 검사 (lint + 타입 + Rust/Python 테스트 + coverage)
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)
make ci는 CI 전체가 아니라 그중 빠른 다섯 레인입니다. CI는 여기에 Coverage·MSRV·Docs Build·Python·Workflow Lint를 더 돌립니다. 릴리스나 큰 변경 전에는 make ci-full과 make py-all을, 문서를 고쳤다면 mdbook build를 함께 돌리세요.
빌드 가속 (선택):
sccache가 PATH에 있으면make타깃이 자동으로 컴파일 캐시로 사용합니다(없으면 그대로 동작 — 아무것도 깨지지 않음). 반복make ci가 크게 빨라집니다. 설치:cargo install sccache또는brew install sccache. (릴리스 파이프라인 release-plz 는 영향받지 않습니다.)
HwpForge MCP questions
How do I add HwpForge MCP to Claude Code?
Run claude mcp add hwpforge -- npx -y @hwpforge/mcp in your terminal. Add --scope user to make it available in every project.
How do I add HwpForge MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does HwpForge MCP provide?
It exposes 19 tools, including hwpforge_convert, hwpforge_delete_para, hwpforge_diff, hwpforge_fields, hwpforge_fill.