Hwpx MCP

🚀 HWPX MCP 服務器 - 增強版

這是一個可與 AI 工具（如 Claude 等）集成，實現自動編輯韓文字處理軟件（HWPX）文檔的 MCP（模型上下文協議）服務器。它基於原項目進行了復刻，並大幅改進了穩定性和功能。

🚀 快速開始

本項目支持所有操作系統！

為什麼能實現跨平臺？ HWPX 文件採用 ZIP + XML 結構，僅使用 Node.js 就能完美讀寫，無需安裝韓文字處理軟件。

*LibreOffice 對 HWPX 的支持有限，為確保完全兼容，建議使用漢松辦公軟件。

✨ 主要特性

本項目對比原項目，解決了以下核心問題：

🔧 關鍵 bug 修復

🛠 技術改進

1. 原子文件寫入
   • 臨時文件 → ZIP 驗證 → 原子移動
   • 即使保存過程中出現錯誤，也能保護原始文件
2. 智能行佈局重置
   • 文本修改時自動重置 lineseg
   • 韓文字處理軟件打開時自動重新計算換行
   • 徹底解決文本重疊現象
3. 基於深度的 XML 解析
   • 解決了現有惰性正則表達式對嵌套結構的誤識別問題
   • 完美支持複雜表格（嵌套表格、子列表等）
4. 完整樣式保留
   • 100% 保留 charPr、spacing 等原始樣式
   • 去除不完整的序列化邏輯，確保數據完整性
5. 安全的多單元格更新
   • 即使同時修改同一行的多個單元格也很安全
   • 通過按行分組和逆序處理，防止索引損壞

📦 安裝指南

1. 安裝 MCP 服務器

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

2. 配置 MCP 客戶端

你可以選擇以下客戶端進行配置：

🖥️ Claude Desktop

配置文件位置：

配置內容：

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

⚠️ 在 Windows 系統中，路徑需使用 \\ 或 /（例如：C:/Users/username/hwpx-mcp/...）

💻 Claude Code (CLI)

方法 1：按項目配置（在項目根目錄創建 .mcp.json 文件）

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

方法 2：全局配置（~/.claude/settings.json）

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

方法 3：通過 CLI 命令添加

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

🔷 Cursor

配置文件：~/.cursor/mcp.json（若不存在則創建）

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

或者你也可以在 Cursor Settings > MCP 中直接添加。

🆚 VS Code（使用 MCP 擴展時）

配置文件：.vscode/mcp.json（項目文件夾內）

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

可以使用 ${workspaceFolder} 變量指定相對路徑。

🛠️ 其他 MCP 客戶端

通用的 MCP 配置格式如下：

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

路徑示例：

3. 安裝驗證

重啟客戶端後，若 MCP 工具列表中顯示 hwpx-mcp 服務器和 77 個工具，則安裝成功！

💻 使用示例

基礎用法

// 打開文檔
await mcp.open_document({ file_path: "report.hwpx" })

// 修改表格單元格
await mcp.update_table_cell({
  doc_id: "...",
  section_index: 0,
  table_index: 0,
  row: 0,
  col: 1,
  text: "修改後的內容"
})

// 插入嵌套表格（表中表）
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"]]
})

// 插入 Mermaid 圖表
await mcp.render_mermaid({
  doc_id: "...",
  mermaid_code: "graph TD; A-->B; B-->C;",
  after_index: 0,
  theme: "default"
})

// 保存文檔
await mcp.save_document({ doc_id: "..." })

高級用法

表格單元格搜索/替換工作流程

當同一文本出現在多個位置時，可按以下方法僅修改 特定位置：

// 1. 包含表格搜索以確定位置
const results = await mcp.search_text({
  doc_id: "...",
  query: "待修改內容",
  include_tables: true  // 包含表格單元格
})
// 結果: [{ text: "待修改內容", location: { type: "table", tableIndex: 2, row: 3, col: 1 } }, ...]

// 2. 精確替換所需位置的單元格
await mcp.replace_text_in_cell({
  doc_id: "...",
  section_index: 0,
  table_index: 2,  // 從搜索結果中確認的位置
  row: 3,
  col: 1,
  old_text: "待修改內容",
  new_text: "新內容"
})

📚 詳細文檔

🔌 MCP 工具（77 個）

📁 文檔管理 - 5 個

📄 文檔信息 - 5 個

📝 段落 - 8 個

🎨 文本樣式 - 4 個

🔍 搜索/替換 - 4 個

📊 表格 - 12 個

📐 頁面設置 - 2 個

🖼️ 圖像 - 5 個

✏️ 圖形 - 3 個

📑 頁眉/頁腳 - 4 個

📌 腳註/尾註 - 4 個

🔗 書籤/超鏈接 - 4 個

➗ 公式 - 2 個

💬 備註 - 3 個

📚 章節 - 5 個

🎭 樣式定義 - 4 個

📰 分欄設置 - 2 個

📤 導出 - 2 個

↩️ 撤銷/重做 - 2 個

🔧 技術細節

📋 支持的格式

注意：不支持 HWP（二進制）文件，請先在漢松辦公軟件中將其轉換為 HWPX 格式後再使用。

📝 版本說明

v0.4.0（增強搜索和圖表支持）

• 🆕 新功能：為 search_text 添加 include_tables 選項，可搜索表格單元格內的文本
• 🆕 新功能：replace_text_in_cell 可精確替換特定表格單元格內的文本
• 🆕 新功能：render_mermaid 可將 Mermaid 圖表作為圖像插入文檔
  • 支持所有 Mermaid 語法，如流程圖、序列圖、類圖等
  • 可選擇主題（默認、深色、森林、中性）
• 🆕 新功能：get_section_xml / set_section_xml 可直接操作章節原始 XML
  • 支持基於 AI 的高級文檔編輯場景
• 🔧 改進：全面改進 insert_image 功能
  • 自動將圖像保存到 BinData 文件夾
  • 自動註冊 content.hpf 清單
  • 確保插入圖像時文件不會損壞

v0.3.0（嵌套表格支持）

• 🆕 新功能：insert_nested_table 可在表格單元格中插入嵌套表格
  • 在父表格的特定單元格中插入新表格
  • 可指定初始數據（二維數組）
  • 完全遵循 HWPX 標準結構（treatAsChar, hp:subList）
• 🔧 改進：改進 charSpacing 解析（處理屬性順序無關）

v0.2.1（關鍵修復）

• 🔥 關鍵修復：徹底解決同一行中多個單元格同時修改時文件損壞的問題
  • 通過按行分組更新，防止索引不一致
  • 通過逆序處理確保安全的 XML 修改

v0.2.0（增強版）

• 🔥 重大修復：通過在文本修改時自動重置 lineseg，徹底解決文本重疊問題
• 🔧 錯誤修復：修復嵌套表格結構中 XML 元素邊界誤識別問題
• 🛡️ 穩定性提升：通過原子文件寫入防止文件損壞
• 📦 樣式保留：完全保留原始 charPr/spacing 樣式

v0.1.0（原始版本）

• 首次發佈（mjyoo2/hwp-extension）

📄 許可證

本項目採用 MIT 許可證。

🤝 貢獻

如果你發現了 bug 或有功能需求，請在 GitHub Issues 中反饋。