hwpx-mcp

🚀 HWPX MCP 服务器 - 增强版

这是一个可与 AI 工具（如 Claude 等）集成，实现自动编辑韩文字处理软件（HWPX）文档的 MCP（模型上下文协议）服务器。它基于原项目进行了复刻，并大幅改进了稳定性和功能。

🚀 快速开始

本项目支持所有操作系统！ | 操作系统 | MCP 服务器 | HWPX 编辑 | 结果查看 | |:---:|:---:|:---:|:---| | ✅ Windows | ✅ | ✅ | 汉松办公软件 | | ✅ macOS | ✅ | ✅ | 汉松办公软件 Mac 版 | | ✅ Linux | ✅ | ✅ | 汉松办公软件 Linux 版 / LibreOffice* |

为什么能实现跨平台？ HWPX 文件采用 ZIP + XML 结构，仅使用 Node.js 就能完美读写，无需安装韩文字处理软件。

*LibreOffice 对 HWPX 的支持有限，为确保完全兼容，建议使用汉松办公软件。

✨ 主要特性

本项目对比原项目，解决了以下核心问题：

🔧 关键 bug 修复

| 问题 | 原项目状态 | 改进后 | |------|----------|---------| | 表格保存失败 | 单元格修改后保存，更改内容消失 | ✅ 完美保存 | | 文本重叠现象 | 保存后在韩文字处理软件中打开，文字重叠显示 | ✅ 正常显示 | | 文件损坏 | 保存时偶尔文件损坏 | ✅ 通过原子写入确保 100% 安全 | | 多单元格损坏 | 同一行中多个单元格修改时，XML 损坏 | ✅ 通过索引管理确保安全 | | 字间距/行间距丢失 | 保存后样式信息丢失 | ✅ 保留所有样式 |

🛠 技术改进

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

配置文件位置： | 操作系统 | 路径 | |----|------| | Windows | %APPDATA%\Claude\claude_desktop_config.json | | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Linux | ~/.config/Claude/claude_desktop_config.json |

配置内容：

{
  "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"]
    }
  }
}

路径示例： | 操作系统 | 路径示例 | |----|----------| | Windows | C:/Users/username/hwpx-mcp/mcp-server/dist/index.js | | macOS | /Users/username/hwpx-mcp/mcp-server/dist/index.js | | Linux | /home/username/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 个

| 工具 | 说明 | 主要参数 | |------|------|--------------| | create_document | 创建新的空白 HWPX 文档 | title?, creator? | | open_document | 打开 HWPX 文档 | file_path | | close_document | 关闭打开的文档 | doc_id | | save_document | 保存文档（支持备份/完整性验证） | doc_id, output_path?, create_backup?, verify_integrity? | | list_open_documents | 查看当前打开的文档列表 | - |

📄 文档信息 - 5 个

| 工具 | 说明 | 主要参数 | |------|------|--------------| | get_document_text | 提取文档的全部文本 | doc_id | | get_document_structure | 查看文档结构（章节/段落/表格/图像数量） | doc_id | | get_document_metadata | 查看元数据（标题、作者、日期等） | doc_id | | set_document_metadata | 修改元数据 | doc_id, title?, creator?, subject?, description? | | get_word_count | 统计字符数/单词数 | doc_id |

📝 段落 - 8 个

| 工具 | 说明 | 主要参数 | |------|------|--------------| | get_paragraphs | 查看段落列表（包含文本/样式） | doc_id, section_index? | | get_paragraph | 获取特定段落的详细信息 | doc_id, section_index, paragraph_index | | insert_paragraph | 插入新段落 | doc_id, section_index, after_index, text | | delete_paragraph | 删除段落 | doc_id, section_index, paragraph_index | | update_paragraph_text | 修改段落文本内容 | doc_id, section_index, paragraph_index, text, run_index? | | append_text_to_paragraph | 在现有段落中添加文本 | doc_id, section_index, paragraph_index, text | | copy_paragraph | 将段落复制到其他位置 | doc_id, source_section, source_paragraph, target_section, target_after | | move_paragraph | 将段落移动到其他位置 | doc_id, source_section, source_paragraph, target_section, target_after |

🎨 文本样式 - 4 个

| 工具 | 说明 | 主要参数 | |------|------|--------------| | get_text_style | 查看字体格式（字体/大小/颜色等） | doc_id, section_index, paragraph_index, run_index? | | set_text_style | 设置字体格式 | doc_id, section_index, paragraph_index, bold?, italic?, underline?, strikethrough?, font_name?, font_size?, font_color?, background_color? | | get_paragraph_style | 查看段落格式（对齐方式/行间距/边距等） | doc_id, section_index, paragraph_index | | set_paragraph_style | 设置段落格式 | doc_id, section_index, paragraph_index, align?, line_spacing?, margin_*?, first_line_indent? |

🔍 搜索/替换 - 4 个

| 工具 | 说明 | 主要参数 | |------|------|--------------| | search_text | 在文档中搜索文本（支持正则表达式，包含表格单元格） | doc_id, query, case_sensitive?, regex?, include_tables? | | replace_text | 查找并替换文本 | doc_id, old_text, new_text, case_sensitive?, regex?, replace_all? | | replace_text_in_cell | 替换特定表格单元格内的文本 | doc_id, section_index, table_index, row, col, old_text, new_text | | batch_replace | 批量替换多个文本 | doc_id, replacements[]（old_text, new_text 对数组） |

📊 表格 - 12 个

| 工具 | 说明 | 主要参数 | |------|------|--------------| | get_tables | 获取文档中所有表格的列表 | doc_id | | get_table | 查看特定表格的全部数据 | doc_id, section_index, table_index | | get_table_cell | 查看特定单元格的内容 | doc_id, section_index, table_index, row, col | | update_table_cell | 修改单元格内容（保留样式） | doc_id, section_index, table_index, row, col, text, char_shape_id? | | set_cell_properties | 设置单元格属性（大小/背景颜色/对齐方式） | doc_id, section_index, table_index, row, col, width?, height?, background_color?, vertical_align? | | insert_table | 插入新表格 | doc_id, section_index, after_index, rows, cols, width? | | insert_table_row | 在表格中插入行 | doc_id, section_index, table_index, after_row, cell_texts? | | delete_table_row | 删除表格中的行 | doc_id, section_index, table_index, row_index | | insert_table_column | 在表格中插入列 | doc_id, section_index, table_index, after_col | | delete_table_column | 删除表格中的列 | doc_id, section_index, table_index, col_index | | insert_nested_table | 在单元格中插入嵌套表格（表中表） | doc_id, section_index, parent_table_index, row, col, nested_rows, nested_cols, data? | | get_table_as_csv | 将表格导出为 CSV 格式 | doc_id, section_index, table_index, delimiter? |

📐 页面设置 - 2 个

| 工具 | 说明 | 主要参数 | |------|------|--------------| | get_page_settings | 查看页面设置（纸张大小/边距） | doc_id, section_index? | | set_page_settings | 修改页面设置 | doc_id, section_index?, width?, height?, margin_*?, orientation? |

🖼️ 图像 - 5 个

| 工具 | 说明 | 主要参数 | |------|------|--------------| | get_images | 获取文档中所有图像的列表 | doc_id | | insert_image | 插入图像文件（自动注册 BinData） | doc_id, section_index, after_index, image_path, width?, height? | | update_image_size | 修改现有图像的大小 | doc_id, section_index, image_index, width, height | | delete_image | 删除图像 | doc_id, section_index, image_index | | render_mermaid | 将 Mermaid 图表作为图像插入 | doc_id, mermaid_code, after_index, section_index?, width?, height?, theme?, background_color? |

✏️ 图形 - 3 个

| 工具 | 说明 | 主要参数 | |------|------|--------------| | insert_line | 插入线条图形 | doc_id, section_index, after_index, x1, y1, x2, y2, stroke_color?, stroke_width? | | insert_rect | 插入矩形图形 | doc_id, section_index, after_index, x, y, width, height, fill_color?, stroke_color? | | insert_ellipse | 插入椭圆图形 | doc_id, section_index, after_index, cx, cy, rx, ry, fill_color?, stroke_color? |

📑 页眉/页脚 - 4 个

| 工具 | 说明 | 主要参数 | |------|------|--------------| | get_header | 查看页眉内容 | doc_id, section_index? | | set_header | 设置页眉 | doc_id, text, section_index?, apply_page_type? (both/even/odd) | | get_footer | 查看页脚内容 | doc_id, section_index? | | set_footer | 设置页脚 | doc_id, text, section_index?, apply_page_type? (both/even/odd) |

📌 脚注/尾注 - 4 个

| 工具 | 说明 | 主要参数 | |------|------|--------------| | get_footnotes | 获取文档中所有脚注的列表 | doc_id | | insert_footnote | 在特定位置插入脚注 | doc_id, section_index, paragraph_index, text | | get_endnotes | 获取文档中所有尾注的列表 | doc_id | | insert_endnote | 在特定位置插入尾注 | doc_id, section_index, paragraph_index, text |

🔗 书签/超链接 - 4 个

| 工具 | 说明 | 主要参数 | |------|------|--------------| | get_bookmarks | 获取文档中所有书签的列表 | doc_id | | insert_bookmark | 在特定位置插入书签 | doc_id, section_index, paragraph_index, name | | get_hyperlinks | 获取文档中所有超链接的列表 | doc_id | | insert_hyperlink | 插入超链接 | doc_id, section_index, paragraph_index, url, text |

➗ 公式 - 2 个

| 工具 | 说明 | 主要参数 | |------|------|--------------| | get_equations | 获取文档中所有公式的列表 | doc_id | | insert_equation | 插入公式（HWP 公式脚本格式） | doc_id, section_index, after_index, script |

💬 备注 - 3 个

| 工具 | 说明 | 主要参数 | |------|------|--------------| | get_memos | 获取文档中所有备注/注释的列表 | doc_id | | insert_memo | 插入备注/注释 | doc_id, section_index, paragraph_index, content, author? | | delete_memo | 删除备注/注释 | doc_id, memo_id |

📚 章节 - 5 个

| 工具 | 说明 | 主要参数 | |------|------|--------------| | get_sections | 获取文档中所有章节的列表 | doc_id | | insert_section | 插入新章节 | doc_id, after_index | | delete_section | 删除章节 | doc_id, section_index | | get_section_xml | 查看章节原始 XML（用于 AI 文档操作） | doc_id, section_index? | | set_section_xml | 替换章节原始 XML（必须为 HWPML 格式） | doc_id, xml, section_index?, validate? |

🎭 样式定义 - 4 个

| 工具 | 说明 | 主要参数 | |------|------|--------------| | get_styles | 获取文档中定义的样式列表 | doc_id | | get_char_shapes | 获取字符形状（CharShape）定义列表 | doc_id | | get_para_shapes | 获取段落形状（ParaShape）定义列表 | doc_id | | apply_style | 将样式应用于段落 | doc_id, section_index, paragraph_index, style_id |

📰 分栏设置 - 2 个

| 工具 | 说明 | 主要参数 | |------|------|--------------| | get_column_def | 查看分栏（Column）设置 | doc_id, section_index? | | set_column_def | 修改分栏设置（多栏编辑） | doc_id, count, section_index?, type?, same_size?, gap? |

📤 导出 - 2 个

| 工具 | 说明 | 主要参数 | |------|------|--------------| | export_to_text | 将文档导出为文本文件 | doc_id, output_path | | export_to_html | 将文档导出为 HTML 文件 | doc_id, output_path |

↩️ 撤销/重做 - 2 个

| 工具 | 说明 | 主要参数 | |------|------|--------------| | undo | 撤销最后一次更改 | doc_id | | redo | 恢复撤销的更改 | doc_id |

🔧 技术细节

📋 支持的格式

| 格式 | 扩展名 | 读取 | 写入 | |------|--------|:----:|:----:| | HWPX | .hwpx | ✅ | ✅ | | HWP | .hwp | ❌ | ❌ |

注意：不支持 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 中反馈。