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修复
| 问题 | 原始状态 | 改善后 |
|---|---|---|
| 无法保存表格 | 修改单元格后保存更改也会消失 | 完整保存 |
| 文本重叠 保存后在韩文中打开,文字重叠显示
文件损坏 · 保存时偶尔会损坏文件 · 通过原子写入100%安全
多芯损坏 · 在同一行修改多个单元格时XML损坏 · 安全使用索引管理
字距/行距损失 · 保存后丢失样式信息 · 保留所有样式
🛠 技术改进
- 原子文件写入(Atomic File Writing)
- 临时文件→ZIP验证→原子移动
- 保存时发生错误时保护源文件
- Smart Lineseg Reset(初始化智能行布局)
- 修改文本时
lineseg自动初始化 - 韩文程序打开时自动重新计算换行
- 完全消除文本重叠
- 基于深度的XML解析(Depth-based XML Parsing)
- 解决现有lazy regex的嵌套结构错误识别问题
- 完全支持复杂表(嵌套表、subList等)
- Complete Style Preservation(完全保留样式)
charPr,spacing等原始样式保持100%- 通过不完整的串行化逻辑消除确保数据完整性
- 安全多芯更新(Safe Multi-Cell Updates)
- 同时修改同一行的多个单元格也是安全的
- 按行分组+逆序处理,防止索引损坏
📦 安装
1.安装MCP服务器```bash
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`
**设置内容:**```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 在项目根目录中创建文件)```json
{
"mcpServers": {
"hwpx-mcp": {
"command": "node",
"args": ["/path/to/hwpx-mcp/mcp-server/dist/index.js"]
}
}
}
**方法2:全局设置** (`~/.claude/settings.json`)```json
{
"mcpServers": {
"hwpx-mcp": {
"command": "node",
"args": ["/path/to/hwpx-mcp/mcp-server/dist/index.js"]
}
}
}
方法3:通过CLI命令添加```bash
claude mcp add hwpx-mcp node /path/to/hwpx-mcp/mcp-server/dist/index.js
______________________________________________________________________
#### 🔷 光标
**配置文件:** `~/.cursor/mcp.json` (如果没有,则创建)```json
{
"mcpServers": {
"hwpx-mcp": {
"command": "node",
"args": ["/path/to/hwpx-mcp/mcp-server/dist/index.js"]
}
}
}
或者 光标设置>MCP 可以直接从中添加
🆚 VS Code(使用MCP扩展时)
配置文件:
.vscode/mcp.json (在项目文件夹中)```json
{
"servers": {
"hwpx-mcp": {
"command": "node",
"args": ["${workspaceFolder}/../hwpx-mcp/mcp-server/dist/index.js"]
}
}
}
> `${workspaceFolder}` 利用变量可以指定相对路径
______________________________________________________________________
#### 🛠️ 其他MCP客户端
典型的MCP设置格式:```json
{
"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个
Tool · 说明 · 主要参数
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 查询当前打开的文档列表-
📄 文档信息(Document Info)-5个
Tool · 说明 · 主要参数
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
📝 段落(Paragraphs)-8个
| Tool | 说明 | 主要参数 |
|---|---|---|
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 |
🎨 文本样式(Text Styling)-4
Tool · 说明 · 主要参数
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?
🔍 搜索/替换(Search&Replace)-4个
| Tool | 说明 | 主要参数 |
|---|---|---|
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[] (旧文本,新文本쌍 배열) |
📊 表(Tables)-12个
| Tool | 说明 | 主要参数 |
|---|---|---|
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? |
📐 页面设置(Page Settings)-2个
| Tool | 说明 | 主要参数 |
|---|---|---|
get_page_settings |
浏览页面设置(纸张大小/边距) | doc_id, section_index? |
set_page_settings |
更改页面设置 | doc_id, section_index?, width?, height?, margin_*?, orientation? |
🖼️ 图像(Images)-5个
| Tool | 说明 | 主要参数 |
|---|---|---|
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? |
图形(Shapes)-3个
| Tool | 说明 | 主要参数 |
|---|---|---|
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? |
📑 标题/页脚(Header/Footer)-4个
| Tool | 说明 | 主要参数 |
|---|---|---|
get_header |
查询标题内容 | doc_id, section_index? |
set_header |
标题设置 | doc_id, text, section_index?, apply_page_type? (双/偶/奇) |
get_footer |
查看页脚内容 | doc_id, section_index? |
set_footer |
页脚设置 | doc_id, text, section_index?, apply_page_type? (双/偶/奇) |
📌 脚注/美洲(Footnotes/Endnotes)-4个
| Tool | 说明 | 主要参数 |
|---|---|---|
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 |
🔗 书签/超链接(Bookmarks/Hyperlinks)-4个
| Tool | 说明 | 主要参数 |
|---|---|---|
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 |
➗公式(Equations)-2个
| Tool | 说明 | 主要参数 |
|---|---|---|
get_equations |
文档中的所有公式列表 | doc_id |
insert_equation |
插入公式(HWP公式脚本格式) | doc_id, section_index, after_index, script |
💬 注释(Memos/Comments)-3个
| Tool | 说明 | 主要参数 |
|---|---|---|
get_memos |
文档中的所有注释/注释列表 | doc_id |
insert_memo |
插入注释/注释 | doc_id, section_index, paragraph_index, content, author? |
delete_memo |
删除注释/注释 | doc_id, memo_id |
📚 节(Sections)-5个
| Tool | 说明 | 主要参数 |
|---|---|---|
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? |
🎭 样式定义(Style Definitions)-4
| Tool | 说明 | 主要参数 |
|---|---|---|
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 |
📰 单设置(Column Layout)-2个
| Tool | 说明 | 主要参数 |
|---|---|---|
get_column_def |
查看“段”(Column)设置 | doc_id, section_index? |
set_column_def |
更改段落设置(多段编辑) | doc_id, count, section_index?, type?, same_size?, gap? |
📤 导出(Export)-2
| Tool | 说明 | 主要参数 |
|---|---|---|
export_to_text |
将文档导出为文本文件 | doc_id, output_path |
export_to_html |
将文档导出为HTML文件 | doc_id, output_path |
取消执行(Undo/Redo)-2个
| Tool | 说明 | 主要参数 |
|---|---|---|
undo |
撤消上次更改 | doc_id |
redo |
重新运行撤消的更改 | doc_id |
使用示例```typescript
// 문서 열기
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: "..." })
#### 表格单元搜索/替换工作流
当同一文本在多个位置时 **特定位置**只修改:```typescript
// 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
📄 许可证
麻省理工学院
🤝 贡献
错误报告和功能请求: GitHub问题
