Content
<div align="center">
# Tool List
**HWPX MCP Server**
**Safely read, edit, and render HWPX documents with AI.**
A [Model Context Protocol](https://modelcontextprotocol.io) server that works with Node.js only, without Hancom Office.
Connect to MCP clients like Claude, Cursor, and more to access 146 tools for HWPX documents.
[](CHANGELOG.md)
[](#-quality-gates)
[](#-tools)
[](#-credits--license)
[](#-installation)
</div>
---
HWPX has a ZIP + XML structure, making it possible to work with without Hancom Office. However, modifying XML directly can easily corrupt the document — this server enables **lossless CST** and **writing gates** to edit and reconstruct documents **structurally**.
```jsonc
// 30-second summary
open_document → search / edit (style inheritance, atomic planning) → save_document // safe editing
render_preview / render_pdf // preview before saving
reconstruct + verify:manipulation // prove reconstruction and structural integrity
```
## ✨ Highlights
- 🔒 **Lossless CST Architecture** — a lossless XML syntax tree as the single source of truth. Unmodified documents remain **byte-identical** when saved, and edits only change bytes within the target element span.
- ✅ **Verified Writing** — save responses are separated into `structural_integrity_verified` (archive/XML invariants) and `intent_verified` (postconditions for edit intentions). **Failed writes do not reach disk.**
- 🧩 **Semantically Safe Editing** — `insert_paragraphs` inherits styles, tabs, and numbering while removing hazardous payloads, and `preview_edit_plan` / `apply_edit_plan` apply multiple edits atomically within a single snapshot/undo boundary (with rollback on failure).
- 🖼️ **Layout Reproduction Engine** — section CST is arranged into a **box tree** (Page→Column→Block→Line) with paragraph margins, character spacing, line spacing, table auto-grow, multi-column, and floating/inline objects. `render_preview` (page-by-page SVG HTML) and `render_pdf` (headless Chrome) provide previews before saving.
- 🎯 **Manipulation Completeness (v2.0)** — reconstructing the original document from tools proves **structural identity** (semantic diff=0) and **pixel identity** (rendered PDF matches original) across the corpus.
- 🛠️ **146 Tools** — paragraph, table, image, shape, equation, header/footer, footnote/endnote, bookmark, hyperlink, memo, section, style, page, multi-column, TOC, rendering, export, undo/redo.
> See the full changelog in [CHANGELOG.md](CHANGELOG.md).
## 📦 Installation
**Requirements:** Node.js ≥ 18. Chrome or Edge (optional) for PDF output.
```bash
git clone https://github.com/h9661/hwpx-mcp.git
cd hwpx-mcp
npm install
npm run build
```
Register the server with MCP clients (using the built `dist/index.js` **absolute path**):
```json
{
"mcpServers": {
"hwpx-mcp": {
"command": "node",
"args": ["/absolute/path/to/hwpx-mcp/dist/index.js"]
}
}
}
```
| Client | Configuration Location |
|--|--|
| **Claude Desktop** | `%APPDATA%\Claude\claude_desktop_config.json` (Win) · `~/Library/Application Support/Claude/claude_desktop_config.json` (mac) · `~/.config/Claude/claude_desktop_config.json` (Linux) |
| **Claude Code** | `.mcp.json`(project) or `claude mcp add hwpx-mcp node /path/to/dist/index.js` |
| **Cursor** | `~/.cursor/mcp.json` |
| **VS Code (MCP)** | `.vscode/mcp.json` (`"servers"` key) |
> Use `/` or `\\` for Windows paths. Restart the client after registration to see `hwpx-mcp` in the tool list.
## 🚀 Quick Start
```typescript
await mcp.open_document({ file_path: "report.hwpx" })
// 1) Insert paragraphs with inherited styles
await mcp.insert_paragraphs({
doc_id, section_index: 0, after_ref: "<current element_ref>",
texts: ["New paragraph 1", "New paragraph 2"],
})
// 2) Precise replacement in specific cells
await mcp.replace_text_in_cell({
doc_id, section_index: 0, table_index: 2, row: 3, col: 1,
old_text: "Target", new_text: "New content",
})
// 3) Preview results as PDF before saving
await mcp.render_pdf({ doc_id, output_path: "preview.pdf" })
await mcp.save_document({ doc_id })
```
## 🔌 Tools
Category-wise overview. See the full list and parameters in the MCP client tool panel.
| Category | Representative Tools |
|--|--|
| **Document Management** | `create_document`, `open_document`, `save_document`, `close_document` |
| **Document Information** | `get_document_text`, `get_document_structure`, `get_word_count`, `get_document_outline` |
| **Paragraph** | `get_paragraphs`, **`insert_paragraphs`**, `update_paragraph_text`, `copy_paragraph`, `move_paragraph`, `set_paragraph_numbering` |
| **Edit Planning** | **`preview_edit_plan`**, **`apply_edit_plan`** |
| **Style** | `set_text_style`, `set_paragraph_style`, `apply_style` |
| **Search/Replace** | `search_text`(including tables), `replace_text`, `replace_text_in_cell`, `batch_replace` |
| **Table** | `insert_table`, `update_table_cell`, `set_cell_paragraphs`, `insert_nested_table`, `merge_cells`/`split_cell`, `set_cell_borders`, `get_table_as_csv` |
| **Image/Shape** | `insert_image`, `render_mermaid`, `insert_line`/`insert_rect`/`insert_ellipse` |
| **Layout/Render** | `get_page_map`, **`render_preview`**, **`render_pdf`**, `set_page_settings`, `set_column_def`, `update_static_toc` |
| **Reference/Annotation** | `insert_footnote`/`insert_endnote`, `insert_bookmark`, `insert_hyperlink`, `insert_memo` |
| **Raw XML** | `get_section_xml`, `set_section_xml`, **`replace_element_xml`** |
| **Runtime/Misc** | **`get_server_info`**, `insert_equation`, `export_to_text`/`export_to_html`, `undo`/`redo` |
## ✅ Quality Gates
This repository ensures quality through **measured gates**, not just "it works".
| Gate | Command | Criteria |
|--|--|--|
| **Test Suite** | `npm test` | 790 passing (106 files) |
| **Layout Accuracy** | `npm run verify:corpus` | 16 real documents with **98.58% accurate pages**, **100% ±1 page** |
| **Manipulation Completeness** | `MANIP_GATE=1 npm test` | reconstruction diff=0 **16/16**, style catalog **16/16**, rendered pixel identity **16/16**, round-trip lossless |
> `LAYOUT_GATE=1` / `MANIP_GATE=1` require a corpus of real documents (not included in commits); default tests run quickly without corpus.
## 📋 Supported Formats & Known Limitations
| Format | Read | Write |
|--|:--:|:--:|
| HWPX (.hwpx) | ✅ | ✅ |
| HWP (.hwp, binary) | ❌ | ❌ |
**Known limitations**
- **Self-verification failure**: documents that fail round-trip verification can only be viewed; use `repair_xml` to recover and save.
- **Render fidelity**: `render_preview`/`render_pdf` may not match 100% with Hancom Office output due to differences in line breaking and rasterization.
- **PDF output requires Chrome/Edge**: `render_pdf` uses headless browsers (`--print-to-pdf`). Specify the path with `CHROME_PATH`.
- **Parallel test flakiness** (`CellMerge`, `SemanticModel.corpus`, etc., ~1/8): stable in solo/partial runs → logic defects, not harness timeout artifacts.
## 🗺️ Roadmap
<details>
<summary><b>✅ Completed in v2.0</b> — layout fidelity and manipulation completeness</summary>
- **Layout Engine v2**: box model layout (table auto-grow, multi-column, floating objects), character-class font metrics, calibration CLI, and regression gates for real documents (98.58% accurate pages).
- **Preview Renderer**: `render_preview`(page-by-page SVG HTML) + `render_pdf`(headless Chrome), including tab stops, alignment, headers/footers, images, and tables.
- **Manipulation Completeness**: reconstructing original documents from tools proves **structural identity** (semantic diff=0) and **pixel identity** (rendered PDF matches original) across the corpus.
</details>
**Next (v2.x+)**
- universal edit plan (insertion, modification, deletion, movement, and tables in one transaction) and document diff/patch
- style library, numbering/bullet extensions, and table presets
- Markdown ⇄ HWPX structural conversion, HWP (binary) reading bridge
- large-scale streaming, incremental saving, and benchmarking
PRs and issues welcome → [GitHub Issues](https://github.com/h9661/hwpx-mcp/issues)
## 🙏 Credits & License
- Heritage: [mjyoo2/hwp-extension](https://github.com/mjyoo2/hwp-extension) → [Dayoooun](https://github.com/Dayoooun) → **[h9661/hwpx-mcp](https://github.com/h9661/hwpx-mcp)**
- License: **MIT** — [LICENSE](LICENSE)
