hwpx-mcp-server

[!NOTE] 公开列车：python-hwpx 6.2.1 → python-hwpx-automation 7.0.2 → hwpx-plugin 2.0.1（automation 7.0.2 · plugin 2.0.1 发布于 2026-08-16， Windows 保存修复补丁列车 — 保存修复 #98·上传路径指引 #75，core 与契约 34a91560759dc47a 不变）。 公开坐标仅在观察远程真实状态（core·automation 的 PyPI 与 plugin 的 GitHub Release·marketplace·实际 marketplace 安装）之后才会 提升 — 发布 runbook

在 python-hwpx 引擎之上提供文档编写、 表单填充、试卷排版与安全代理工作流的应用层。 默认安装无需 MCP，可直接使用 Python API 与 hwpx CLI， 模型上下文协议(MCP) 服务器在需要时通过 [mcp] extra 添加。无需 Hancom Office 也无需 Windows，因此在运行 Python 的 ChatGPT 聊天环境中也能直接工作。

Python 自动化快速上手

pip install python-hwpx-automation

from hwpx_automation import create_document_from_plan

document = create_document_from_plan(
    {
        "schemaVersion": "hwpx.document_plan.v1",
        "title": "회의 결과",
        "blocks": [{"type": "paragraph", "text": "결정 사항"}],
    }
)
document.save_to_path("meeting-result.hwpx")

python -m hwpx_automation --help 与 hwpx help 运行相同的 task CLI。

Related MCP server: hwpx-mcp-server

MCP 适配器快速上手

pip install "python-hwpx-automation[mcp]"
hwpx-automation-mcp

在 MCP 客户端配置文件中添加下面一个块即可接入 hwpx 服务器 — Claude Desktop 使用 claude_desktop_config.json，VS Code 使用 .vscode/mcp.json（键为 mcpServers 而非 servers）， Gemini CLI 使用 ~/.gemini/settings.json，Cursor·Windsurf 使用各自编辑器的 MCP 配置文件。

{
  "mcpServers": {
    "hwpx": {
      "command": "uvx",
      "args": [
        "--from",
        "python-hwpx-automation[mcp]==7.0.2",
        "hwpx-automation-mcp"
      ],
      "env": {
        "HWPX_AUTOMATION_WORKSPACE_ROOTS": "[\"~/Documents\"]"
      }
    }
  }
}

在 HWPX_AUTOMATION_WORKSPACE_ROOTS 中指定包含文档的文件夹（绝对路径或 ~）。 Windows 请写成 "[\"C:\\\\hwpx\"]" 的形式。若留空，GUI 客户端会在系统目录中启动服务器，因此所有文档路径都会被 阻止 — 建议从一开始就指定。其余选项请参考 环境变量 表。

若要使用 document_to_markdown 读取非 HWPX 文档（PDF/DOCX/XLSX/HTML/TXT）， 请通过 pip install "python-hwpx-automation[ingest]" 一并安装 MarkItDown adapter。 要求：Python >= 3.10 · python-hwpx >= 5.0.0。

现有的 hwpx-mcp-server 分发、import、控制台与配置键在 6.x 期间继续可用 — 完整列表与维护规则：6.x 兼容表面

功能一览

默认模式提供多种 HWPX 工具，高级模式（HWPX_AUTOMATION_ADVANCED=1）下会额外添加检查、验证用工具。

• 读取·导航 — get_document_info，get_document_map（一次调用获取大纲·表格地图·锚点），find_text（不保存）

• 搜索·替换·编辑 — search_and_replace，apply_document_commands（异构编辑原子应用·dry-run·回滚·幂等键），add_tracked_edit（修订跟踪）

• 表格·表单填充 — analyze_form_fill → apply_form_fill → verify_form_fill 字节保留事务，table_compute（合计·小计）

• 文档生成·公文 — 声明式 create_document_from_plan，inspect_official_document_style（行政规范 lint），mail_merge

• 格式·图片·生成器 — set_paragraph_format·set_page_setup，insert_picture，照片板·名牌·组织结构图

• 预览·提取·修复·诊断 — render_preview（HTML/PNG 自校验），hwpx_to_markdown，repair_hwpx，mcp_server_health

更多详情：使用场景 · 技能优先工作流

安全使用指南

无需一开始就记住所有工具。通常按以下流程进行。

1. 读取 — 通过 get_document_info → get_document_outline/get_document_text → find_text，get_table_map 仅了解所需部分。（不保存）

2. 安全修改 — 用 copy_document 创建副本，应用最小变更（search_and_replace，set_table_cell_text，apply_document_commands）后重新读取确认，最后交付审查完毕的副本。

核心原则是 copy first · smallest edit · re-read after edits。修改工具在 调用时立即保存，因此审查用操作务必在副本中进行。

模型只发送 operation/plan，不直接编辑 raw XML。常规保存 路径通过 python-hwpx 的单一 SavePipeline 门禁，检查完整性·XML·OPC/ID· 打开安全性，门禁失败则不写入任何内容。capability handshake 以 fail-closed 方式阻止 core/automation/plugin 版本+哈希偏差。 安全详情：加固指南 · 与旧名称的兼容 标识符：6.x 兼容表面

位置契约 — paragraph_index 是正文直属段落的 0-based 索引。表格内段落不混入此处， 而是通过 {"kind":"table_cell_paragraph","table_index":0,"row":0,"col":1,"cell_paragraph_index":0} 之类的 location 对象指定，可直接传递 get_table_map/find_text 返回的值。

环境变量

相同后缀的现有 HWPX_MCP_* 键在 6.x 期间作为 fallback 保留，若两个键 同时存在，则 HWPX_AUTOMATION_* 优先。用于 render·workflow·oracle·plugin 联动的保留键完整列表与 workflow DB 路径规则见 6.x 兼容表面。

路径默认拒绝 workspace 之外的 traversal 与 symlink 逃逸，URL 输入仅允许 HTTPS·公网 IP。 不支持原子 rename 的主机上的并发注意事项请参阅 加固指南。

参与贡献

good first issue · 里程碑 · Discussions · CONTRIBUTING · CHANGELOG

python -m pip install -e ".[test]"   # 테스트 의존성
python -m pytest -q                   # 전체 테스트
python scripts/run_conformance.py run \
  --tier structural --check tests/conformance/golden/structural.json

致谢

基于核心库 python-hwpx 运行，并受益于以下公开标准与项目。

• OWPML — 开放式文字处理器标记语言 (KS X 6101) — HWPX 所基于的韩国工业标准

• hancom-io/hwpx-owpml-model — OWPML 元素结构参考模型 · neolord0/hwpxlib — 预言机样本语料库

• edwardkim/rhwp — 幂等性·验证门禁设计灵感

License · Maintainer

Apache-2.0 (LICENSE · NOTICE) — Kohkyuhyun @airmang · kokyuhyun@hotmail.com