HWPX MCP Server

HWPX MCP服务器-增强版

🚀 通过Fork Original项目大幅提高了稳定性和功能。

模型上下文协议（MCP）服务器，可与AI工具（Claude等）集成，自动编辑韩文（HWPX）文档。

______________________________________________________________________

🌍 与跨平台支持

适用于所有操作系统！

温温妮丝·温妮丝·温妮丝·温妮丝·温妮丝·温妮丝·温妮丝·温妮丝·温妮丝·温妮 | 2017.0MacOS 2017.0MacomOffice Mac | Linux |宣传片Linux/LibreOffice\*|

为什么可能？ HWPX文件 ZIP+XML结构是。即使没有韩文程序，也可以用Node.js完全读写。 \*LibreOffice对HWPX的支持有限。为了完全兼容，建议使用Hancom Office。

______________________________________________________________________

增强功能

与原始项目相比： 解决关键问题完成了：

🔧 关键Bug修复

🛠 技术改进

1. 原子文件写入（Atomic File Writing）

- 临时文件→ZIP验证→原子移动 - 保存时发生错误时保护源文件

1. Smart Lineseg Reset（初始化智能行布局）

- 修改文本时 lineseg 自动初始化 - 韩文程序打开时自动重新计算换行 - 完全消除文本重叠

1. 基于深度的XML解析（Depth-based XML Parsing）

- 解决现有lazy regex的嵌套结构错误识别问题 - 完全支持复杂表（嵌套表、subList等）

1. Complete Style Preservation（完全保留样式）

- charPr, spacing 等原始样式保持100% - 通过不完整的串行化逻辑消除确保数据完整性

1. 安全多芯更新（Safe Multi-Cell Updates）

- 同时修改同一行的多个单元格也是安全的 - 按行分组+逆序处理，防止索引损坏

______________________________________________________________________

📦 安装

1.安装MCP服务器

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

2.MCP客户端设置

请选择下面使用的客户端。

______________________________________________________________________

🖥️ 克劳德桌面版

设置文件位置： 操作系统路径 |----|------| |窗户| %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/...)

______________________________________________________________________

💻 克劳德代码（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/mcp.json （如果没有，则创建）

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

或者 光标设置>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"]
    }
  }
}

路径示例： 操作系统路径示例 |----|----------| |窗户| 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个工具时成功！

______________________________________________________________________

🔌 MCP Tools（77个）

📁 文档管理（Document Management）-5个

📄 文档信息（Document Info）-5个

📝 段落（Paragraphs）-8个

🎨 文本样式（Text Styling）-4

🔍 搜索/替换（Search&Replace）-4个

📊 表（Tables）-12个

📐 页面设置（Page Settings）-2个

🖼️ 图像（Images）-5个

图形（Shapes）-3个

📑 标题/页脚（Header/Footer）-4个

📌 脚注/美洲（Footnotes/Endnotes）-4个

🔗 书签/超链接（Bookmarks/Hyperlinks）-4个

➗公式（Equations）-2个

💬 注释（Memos/Comments）-3个

📚 节（Sections）-5个

🎭 样式定义（Style Definitions）-4

📰 单设置（Column Layout）-2个

📤 导出（Export）-2

取消执行（Undo/Redo）-2个

______________________________________________________________________

使用示例

// 문서 열기
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: "새로운내용"
})

______________________________________________________________________

📋 支持的格式

格式扩展名读写 |------|--------|:----:|:----:| |HWPX|.HWPX|✅ | ✅ | |HWP|.HWP|❌ | ❌ |

备注：不支持二进制文件。从Hancom Office转换为HWPX后使用。

______________________________________________________________________

📝 发布说明

v0.4.0（增强的搜索和图表支持）

• 🆕 新功能: search_text呃 include_tables 添加选项-在表格单元格中搜索文本
• 🆕 新功能: replace_text_in_cell -仅精确替换特定表格单元中的文本
• 🆕 新功能: render_mermaid -将Mermaid图表作为图像插入文档

- 支持Flowchart、Sequence、Class Diagram等所有Mermaid语法 - 可选择主题（default，dark，forest，neutral）

• 🆕 新功能: get_section_xml / set_section_xml -直接操作部分Raw XML

- 支持基于AI的高级文档编辑方案

• 🔧 改进: insert_image 完全改善

- 自动将图像保存到BinData文件夹 - content.hpf清单自动注册 - 确保在不损坏文件的情况下插入图像

v0.3.0（嵌套表支持）

• 🆕 新功能: insert_nested_table -在表格单元格中插入嵌套表格的功能

- 在父表的特定单元格中插入新表 - 可指定初始数据（2D阵列） - HWPX标准结构（treatAsChar, hp:subList）完全遵守

• 🔧 改进：改进charSpacing解析（不按属性顺序处理）

v0.2.1（关键修复）

• 🔥 关键修复：在同一行同时修改多个单元格时完全解决文件损坏问题

- 按行分组更新以避免索引不一致 - 通过降序处理确保安全的XML修改

v0.2.0（增强版）

• 🔥 主要修复：修改文本时自动初始化lineseg，完全消除重叠现象
• 🔧 Bug修复：修复嵌套表格结构中的XML元素边界错误识别问题
• 🛡️ 稳定性：通过原子文件写入防止文件损坏
• 📦 保存：完全保留原始charPr/spacing样式

v0.1.0（原始）

• 初始版本（mjyoo2/hwp-extension）

______________________________________________________________________

🙏 学分

• 原始项目： mjyoo2/hwp扩展
• 通过以下方式增强： Dayoooun

______________________________________________________________________

📄 许可证

麻省理工学院

______________________________________________________________________

🤝 贡献

错误报告和功能请求：