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 中反馈。