Hwpx MCP

🚀 HWPX MCP Server - Enhanced Edition

This is an enhanced version forked from the original project, significantly improving stability and functionality.

It is an MCP (Model Context Protocol) server that can automatically edit Hangul (HWPX) documents by integrating with AI tools (such as Claude).

🚀 Quick Start

This is an MCP (Model Context Protocol) server that enables seamless integration with AI tools like Claude, allowing for the automatic editing of Hangul (HWPX) documents.

✨ Features

Compared with the original project, the following core issues have been resolved:

🔧 Critical Bug Fixes

🛠 Technical Improvements

1. Atomic File Writing

   • Temporary file → ZIP verification → Atomic move
   • Protects the original file even if an error occurs during saving

2. Smart Lineseg Reset

   • Automatically resets lineseg when text is modified
   • Automatically recalculates line breaks when the Hangul program is opened
   • Completely resolves the text overlapping issue

3. Depth-based XML Parsing

   • Resolves the problem of misinterpreting nested structures in the existing lazy regex
   • Fully supports complex tables (nested tables, subLists, etc.)

4. Complete Style Preservation

   • Maintains 100% of the original styles such as charPr and spacing
   • Ensures data integrity by removing incomplete serialization logic

5. Safe Multi-Cell Updates

   • Safe even when multiple cells in the same row are modified simultaneously
   • Prevents index damage through row-by-row grouping and reverse-order processing

📦 Installation

1. Install the MCP Server

git clone https://github.com/Dayoooun/hwpx-mcp.git
cd hwpx-mcp/mcp-server
npm install
npm run build

2. Configure the MCP Client

Select the client you want to use from the following options.

🖥️ Claude Desktop

Location of the configuration file:

Configuration content:

{
    "mcpServers": {
        "hwpx-mcp": {
            "command": "node",
            "args": ["C:/path/to/hwpx-mcp/mcp-server/dist/index.js"]
        }
    }
}

⚠️ Use \\ or / in the path on Windows (e.g., C:/Users/username/hwpx-mcp/...)

💻 Claude Code (CLI)

Method 1: Project-specific configuration (Create a .mcp.json file in the project root)

{
    "mcpServers": {
        "hwpx-mcp": {
            "command": "node",
            "args": ["/path/to/hwpx-mcp/mcp-server/dist/index.js"]
        }
    }
}

Method 2: Global configuration (~/.claude/settings.json)

{
    "mcpServers": {
        "hwpx-mcp": {
            "command": "node",
            "args": ["/path/to/hwpx-mcp/mcp-server/dist/index.js"]
        }
    }
}

Method 3: Add via CLI command

claude mcp add hwpx-mcp node /path/to/hwpx-mcp/mcp-server/dist/index.js

🔷 Cursor

Configuration file: ~/.cursor/mcp.json (Create it if it doesn't exist)

{
    "mcpServers": {
        "hwpx-mcp": {
            "command": "node",
            "args": ["/path/to/hwpx-mcp/mcp-server/dist/index.js"]
        }
    }
}

Or you can add it directly in Cursor Settings > MCP

🆚 VS Code (When using the MCP extension)

Configuration file: .vscode/mcp.json (Inside the project folder)

{
    "servers": {
        "hwpx-mcp": {
            "command": "node",
            "args": ["${workspaceFolder}/../hwpx-mcp/mcp-server/dist/index.js"]
        }
    }
}

You can specify relative paths using the ${workspaceFolder} variable

🛠️ Other MCP Clients

General MCP configuration format:

{
    "mcpServers": {
        "hwpx-mcp": {
            "command": "node",
            "args": ["/absolute/path/to/hwpx-mcp/mcp-server/dist/index.js"]
        }
    }
}

Path examples:

3. Verify the Installation

After restarting the client, if the hwpx-mcp server and 77 tools are displayed in the MCP tool list, the installation is successful!

💻 Usage Examples

Basic Usage

// Open a document
await mcp.open_document({ file_path: "report.hwpx" })

// Modify a table cell
await mcp.update_table_cell({
    doc_id: "...",
    section_index: 0,
    table_index: 0,
    row: 0,
    col: 1,
    text: "Modified content"
})

// Insert a nested table (table inside a table)
await mcp.insert_nested_table({
    doc_id: "...",
    section_index: 0,
    parent_table_index: 0,
    row: 1,
    col: 2,
    nested_rows: 2,
    nested_cols: 2,
    data: [["A1", "A2"], ["B1", "B2"]]
})

// Insert a Mermaid diagram
await mcp.render_mermaid({
    doc_id: "...",
    mermaid_code: "graph TD; A-->B; B-->C;",
    after_index: 0,
    theme: "default"
})

// Save the document
await mcp.save_document({ doc_id: "..." })

Advanced Usage

Table Cell Search/Replacement Workflow

How to modify only specific locations when the same text appears in multiple places:

// 1. Determine the location by searching including tables
const results = await mcp.search_text({
    doc_id: "...",
    query: "Content to be modified",
    include_tables: true  // Include table cells
})
// Results: [{ text: "Content to be modified", location: { type: "table", tableIndex: 2, row: 3, col: 1 } }, ...]

// 2. Precisely replace only the cell at the desired location
await mcp.replace_text_in_cell({
    doc_id: "...",
    section_index: 0,
    table_index: 2,  // Location confirmed from the search results
    row: 3,
    col: 1,
    old_text: "Content to be modified",
    new_text: "New content"
})

📚 Documentation

🔌 MCP Tools (77 tools in total)

📁 Document Management - 5 tools

📄 Document Info - 5 tools

📝 Paragraphs - 8 tools

🎨 Text Styling - 4 tools

🔍 Search & Replace - 4 tools

📊 Tables - 12 tools

📐 Page Settings - 2 tools

🖼️ Images - 5 tools

✏️ Shapes - 3 tools

📑 Header/Footer - 4 tools

📌 Footnotes/Endnotes - 4 tools

🔗 Bookmarks/Hyperlinks - 4 tools

➗ Equations - 2 tools

💬 Memos/Comments - 3 tools

📚 Sections - 5 tools

🎭 Style Definitions - 4 tools

📰 Column Layout - 2 tools

📤 Export - 2 tools

↩️ Undo/Redo - 2 tools

📋 Supported Format

Note: HWP (binary) files are not supported. Please convert them to HWPX in Hancom Office before use.

📝 Release Notes

v0.4.0 (Enhanced Search & Diagram Support)

• 🆕 New Feature: Added the include_tables option to search_text - Searches for text in table cells as well
• 🆕 New Feature: replace_text_in_cell - Precisely replaces text only in a specific table cell
• 🆕 New Feature: render_mermaid - Inserts a Mermaid diagram as an image into the document
  • Supports all Mermaid grammars such as Flowchart, Sequence, and Class Diagram
  • Allows theme selection (default, dark, forest, neutral)
• 🆕 New Feature: get_section_xml / set_section_xml - Directly manipulates the raw XML of a section
  • Supports advanced AI-based document editing scenarios
• 🔧 Improvement: Completely improved insert_image
  • Automatically saves images in the BinData folder
  • Automatically registers the content.hpf manifest
  • Ensures image insertion without file corruption

v0.3.0 (Nested Table Support)

• 🆕 New Feature: insert_nested_table - Inserts a nested table inside a table cell
  • Inserts a new table into a specific cell of the parent table
  • Allows initial data to be specified (2D array)
  • Fully complies with the HWPX standard structure (treatAsChar, hp:subList)
• 🔧 Improvement: Improved charSpacing parsing (handles regardless of attribute order)

v0.2.1 (Critical Fix)

• 🔥 Critical Fix: Completely resolved the issue of file corruption when multiple cells in the same row are modified simultaneously
  • Prevents index inconsistencies by grouping updates by row
  • Ensures safe XML modification through reverse-order (descending) processing

v0.2.0 (Enhanced Edition)

• 🔥 Major Fix: Completely resolved the overlapping issue by automatically resetting lineseg when text is modified
• 🔧 Bug Fix: Fixed the problem of misinterpreting XML element boundaries in nested table structures
• 🛡️ Stability: Prevented file corruption with atomic file writing
• 📦 Preservation: Completely preserved the original charPr/spacing styles

v0.1.0 (Original)

• Initial release (mjyoo2/hwp-extension)

🙏 Credits

• Original Project: mjyoo2/hwp-extension
• Enhanced by: Dayoooun

📄 License

MIT

🤝 Contributing

Report bugs and request features: GitHub Issues