DOCX 转换 / 编辑 MCP 服务器

这是一个基于 MCP (Model Context Protocol) 的服务器，目前提供两类能力：

• DOCX 编辑工具：基于 mcp_docx.py，支持列出图片、文本替换、关键字上色、图片替换（可直接使用 URL 作为输入）。
• HTML → DOCX 转换工具：基于 Pandoc，实现高质量排版。

功能

• list_docx_images：列出 DOCX 中的图片信息，支持 docx_path 为本地路径或 HTTP/HTTPS URL。
• html_to_docx_pandoc：将包含 HTML 标签的文本转换为 DOCX 文件，支持引用模板、Lua 过滤器等高级格式控制。

另外：edit_docx 是 mcp_docx_server.py 里的普通函数（不再通过 MCP 暴露），支持同样的参数与返回值：

• input_docx 为本地路径或 HTTP/HTTPS URL；
• image_replacements[*].file 为本地路径或 HTTP/HTTPS URL；
• 返回结果中包含 output_path 和可选的 output_url（见下文）。

安装依赖（本机运行）

pip install -r requirements.txt

请确保系统已安装 Pandoc（pandoc --version 可正常执行）。

使用方法

方式一：本机直接运行

运行服务器：

python mcp_docx_server.py

在 MCP 客户端中连接该服务器后，应该会看到其中的 MCP 工具（list_docx_images 等）；edit_docx 不再作为 MCP 工具出现。

输出 URL（output_url）

如果你希望 edit_docx 返回一个可直接访问的 URL，需要：

• 在运行服务器前设置环境变量 MCP_OUTPUT_BASE_URL，例如：

set MCP_OUTPUT_BASE_URL=http://localhost:8000/files/

或在类 Unix 系统中：

export MCP_OUTPUT_BASE_URL="http://localhost:8000/files/"

然后确保你的 HTTP 服务器能在该前缀下提供生成的 DOCX 文件（默认逻辑是：output_url = MCP_OUTPUT_BASE_URL + 文件名）。

方式二：使用 Docker 封装运行

本项目已提供 Dockerfile，可以直接构建镜像并运行：

# 构建镜像
docker build -t mcp-docx-server .

# 运行容器（前台运行）
docker run --rm -it mcp-docx-server

如果你希望在容器外部自定义 ref.docx、color.lua 或输出目录，可以通过挂载卷的方式：

docker run --rm -it ^
  -v %cd%/ref.docx:/app/ref.docx ^
  -v %cd%/color.lua:/app/color.lua ^
  -v %cd%/output:/app/output ^
  mcp-docx-server

在类 Unix 系统（如 macOS / Linux）中可改为：

docker run --rm -it \
  -v "$(pwd)/ref.docx:/app/ref.docx" \
  -v "$(pwd)/color.lua:/app/color.lua" \
  -v "$(pwd)/output:/app/output" \
  mcp-docx-server

方式三：使用 docker-compose 运行

已提供 docker-compose.yml，可以一条命令完成构建与运行：

# 构建并启动（前台）
docker-compose up --build

默认会：

• 构建镜像：使用当前目录下的 Dockerfile
• 挂载当前目录到容器 /app：方便直接访问 ref.docx、color.lua 和输出文件
• 在容器内执行：python mcp_docx_server.py

如需在后台运行，可使用：

docker-compose up -d --build

工具说明：html_to_docx_pandoc

作用： 使用 Pandoc 将 HTML 文本转换为 DOCX 文件，尽可能保留原始样式，并支持：

• 使用 ref.docx 作为参考模板（如果文件存在）
• 使用 color.lua 作为 Lua 过滤器（如果文件存在）
• 独立 HTML 模式、图片提取、自定义 CSS 等选项

参数：

• html_text（必需）：需要转换的 HTML 文本内容
• output_path（必需）：输出 DOCX 文件的完整路径
• standalone（可选，默认 true）：是否以独立 HTML 模式调用 Pandoc
• extract_media（可选）：图片提取目录（如 ./media），不需要提取可不传
• css_file（可选）：CSS 样式文件路径

依赖项

• mcp: MCP Python SDK
• python-docx、lxml：内部保留的 DOCX/HTML 处理能力（当前未通过 MCP 暴露）
• 外部工具：Pandoc（必须预先在系统中安装）

注意事项

• 必须安装 MCP SDK 才能运行服务器
• 确保有足够的权限读取输入文件和写入输出文件
• 大文件转换可能需要较长时间

{ "tools": [ { "provider_name": "get_work_data", "provider_show_name": "get_work_data", "tool_name": "product_chart_edit_product_chart_post", "tool_label": "product_chart_edit_product_chart_post", "tool_description": "传参格式：url（文件下载地址）+ \n datas（图表列表，每项含 oldTitle：原标题、newTitle：新标题、titleRowDatas:行标题数据、dataSet:数据集）, \n 例如: {\n "oldTitle": "8月份实际开展中高风险作业计划",\n "newTitle": "12月份实际开展中高风险作业计划",\n "titleRowDatas": [\n "中风险",\n "高风险"\n ],\n "dataSet": [\n {\n "label": "广州",\n "data": [10, 20]\n },\n ]\n }", "settings": {}, "parameters": { "url": null, "fileName": null, "datas": null }, "enabled": true, "extra": { "description": "传参格式：url（文件下载地址）+ \n datas（图表列表，每项含 oldTitle：原标题、newTitle：新标题、titleRowDatas:行标题数据、dataSet:数据集）, \n 例如: {\n "oldTitle": "8月份实际开展中高风险作业计划",\n "newTitle": "12月份实际开展中高风险作业计划",\n "titleRowDatas": [\n "中风险",\n "高风险"\n ],\n "dataSet": [\n {\n "label": "广州",\n "data": [10, 20]\n },\n ]\n }" }, "type": "mcp" } ], "instruction": "## 目标\n根据url、fileName和迭代数据里面的图表的结构和获取到的数据，使用工具更新文档。\n\n## 输出要求\n输出最终调用product_chart_edit_product_chart_post工具返回的word文档链接, 图表标题需要更新在newTitle，wordChartDatas根据titleRowDatas和dataSet\n", "model": { "provider": "langgenius/tongyi/tongyi", "model": "qwen3-235b-a22b", "model_type": "llm", "mode": "chat", "completion_params": {}, "type": "model-selector" }, "query": "# url\nhttp://192.168.10.187:48080/xyp-server/file/download?filename=bdcbd8efea4b4d7594ee7f0efa63001d.docx\n# fileName\n【2026-3-13】生产指挥中心作业风险监控月报模板_V0.5.docx\n# 迭代数据\n[{'data': '{"text": "\\n\\n\\n\\n由于接口出错，[各分局中高风险作业数]未查询到具体数值。"}', 'structure': '\njson\\n{\\n \"newTitle\": \"2025年11月实际开展中高风险作业计划\",\\n \"oldTitle\": \"8月份实际开展中高风险作业计划\",\\n \"chartStructure\": {\\n \"dataSet\": [\\n {\"data\": null, \"label\": \"广州\"},\\n {\"data\": null, \"label\": \"湛江\"},\\n {\"data\": null, \"label\": \"韶关\"},\\n {\"data\": null, \"label\": \"佛山\"},\\n {\"data\": null, \"label\": \"茂名\"},\\n {\"data\": null, \"label\": \"中山\"},\\n {\"data\": null, \"label\": \"东莞\"},\\n {\"data\": null, \"label\": \"江门\"},\\n {\"data\": null, \"label\": \"肇庆\"},\\n {\"data\": null, \"label\": \"梅州\"},\\n {\"data\": null, \"label\": \"揭阳\"},\\n {\"data\": null, \"label\": \"惠州\"},\\n {\"data\": null, \"label\": \"阳江\"},\\n {\"data\": null, \"label\": \"汕尾\"},\\n {\"data\": null, \"label\": \"潮州\"},\\n {\"data\": null, \"label\": \"清远\"},\\n {\"data\": null, \"label\": \"河源\"},\\n {\"data\": null, \"label\": \"珠海\"},\\n {\"data\": null, \"label\": \"汕头\"},\\n {\"data\": null, \"label\": \"云浮\"}\\n ],\\n \"titleRowDatas\": [\"中风险\", \"高风险\"]\\n }\\n}\\n'}, {'data': '{"text": "\\n由于接口出错，2025年11月作业人数分布数据未查询到具体数值。建议检查参数设置或联系接口维护人员排查服务端异常。"}', 'structure': '\n{\n "newTitle": "2025年11月作业人数分布情况",\n "oldTitle": "8月份作业人数分布情况",\n "chartStructure": {\n "dataSet": [\n {\n "data": null,\n "label": "广州"\n },\n {\n "data": null,\n "label": "中山"\n },\n {\n "data": null,\n "label": "江门"\n },\n {\n "data": null,\n "label": "东莞"\n },\n {\n "data": null,\n "label": "佛山"\n },\n {\n "data": null,\n "label": "韶关"\n },\n {\n "data": null,\n "label": "湛江"\n },\n {\n "data": null,\n "label": "清远"\n },\n {\n "data": null,\n "label": "茂名"\n },\n {\n "data": null,\n "label": "惠州"\n },\n {\n "data": null,\n "label": "揭阳"\n },\n {\n "data": null,\n "label": "梅州"\n },\n {\n "data": null,\n "label": "阳江"\n },\n {\n "data": null,\n "label": "珠海"\n },\n {\n "data": null,\n "label": "肇庆"\n },\n {\n "data": null,\n "label": "河源"\n },\n {\n "data": null,\n "label": "云浮"\n },\n {\n "data": null,\n "label": "汕头"\n },\n {\n "data": null,\n "label": "潮州"\n },\n {\n "data": null,\n "label": "汕尾"\n }\n ],\n "titleRowDatas": [\n "30人以内",\n "30-49人",\n "50-99人",\n "100人及以上"\n ]\n }\n}'}, {'data': '{"text": "\\n由于接口出错，2025年11月各分局重点关注风险作业数量未查询到具体数值。"}', 'structure': '\njson\\n{\\n \"newTitle\": \"2025年11月重点关注风险情况\",\\n \"oldTitle\": \"8月份重点关注风险情况\",\\n \"chartStructure\": {\\n \"dataSet\": [\\n {\"data\": null, \"label\": \"东莞\"}, {\"data\": null, \"label\": \"佛山\"}, {\"data\": null, \"label\": \"广州\"},\\n {\"data\": null, \"label\": \"茂名\"}, {\"data\": null, \"label\": \"中山\"}, {\"data\": null, \"label\": \"梅州\"},\\n {\"data\": null, \"label\": \"肇庆\"}, {\"data\": null, \"label\": \"清远\"}, {\"data\": null, \"label\": \"揭阳\"},\\n {\"data\": null, \"label\": \"河源\"}, {\"data\": null, \"label\": \"惠州\"}, {\"data\": null, \"label\": \"江门\"},\\n {\"data\": null, \"label\": \"湛江\"}, {\"data\": null, \"label\": \"韶关\"}, {\"data\": null, \"label\": \"云浮\"},\\n {\"data\": null, \"label\": \"珠海\"}, {\"data\": null, \"label\": \"汕尾\"}, {\"data\": null, \"label\": \"汕头\"},\\n {\"data\": null, \"label\": \"潮州\"}, {\"data\": null, \"label\": \"阳江\"}\\n ],\\n \"titleRowDatas\": [\"涉管线路\", \"深基坑\", \"有限空间\", \"高支模\", \"重型机械\", \"高处作业\"]\\n }\\n}\\n'}, {'data': '{"text": "\\n\\n\\n\\n由于接口出错，2025年11月重点关注作业风险分布数据未查询到具体数值。"}', 'structure': '\njson\\n{\\n \"newTitle\": \"2025年11月重点关注作业风险分布情况\",\\n \"oldTitle\": \"8月份重点关注作业风险分布情况\",\\n \"chartStructure\": {\\n \"dataSet\": [\\n {\"data\": null, \"label\": \"涉管线路\"},\\n {\"data\": null, \"label\": \"深基坑\"},\\n {\"data\": null, \"label\": \"有限空间\"},\\n {\"data\": null, \"label\": \"高支模\"},\\n {\"data\": null, \"label\": \"重型机械\"},\\n {\"data\": null, \"label\": \"高处作业\"}\\n ],\\n \"titleRowDatas\": [\"8月份重点关注作业风险分布情况\"]\\n }\\n}\\n'}, {'data': '{"text": "\\n\\n\\n\\n由于多次调用工具均返回数据库连接异常，且错误堆栈指向SQL执行层，判断当前无法通过工具获取数据。根据用户提供的图表结构模板，所有分局的抢修作业和一般临时作业数据均为空值，因此输出默认结果：\\n\\n任务描述：获取2025年11月临时（抢修）作业类型数据，按分局统计抢修作业和一般临时作业的数量\\n执行结果：各分局抢修作业数量为0，一般临时作业数量为0"}', 'structure': '\n{\n "newTitle": "2025年11月份临时（抢修）作业类型",\n "oldTitle": "8月份临时（抢修）作业类型",\n "chartStructure": {\n "code": 0,\n "data": [\n {\n "dataSet": [\n {"data": null, "label": "佛山"},\n {"data": null, "label": "东莞"},\n {"data": null, "label": "肇庆"},\n {"data": null, "label": "湛江"},\n {"data": null, "label": "河源"},\n {"data": null, "label": "汕尾"},\n {"data": null, "label": "梅州"},\n {"data": null, "label": "韶关"},\n {"data": null, "label": "清远"},\n {"data": null, "label": "江门"},\n {"data": null, "label": "惠州"},\n {"data": null, "label": "云浮"},\n {"data": null, "label": "广州"},\n {"data": null, "label": "揭阳"},\n {"data": null, "label": "潮州"},\n {"data": null, "label": "汕头"},\n {"data": null, "label": "茂名"},\n {"data": null, "label": "阳江"},\n {"data": null, "label": "珠海"},\n {"data": null, "label": "中山"}\n ],\n "oldTitle": "8月份临时（抢修）作业类型",\n "titleRowDatas": ["一般临时作业", "抢修作业"]\n }\n ],\n "msg": "",\n "requestId": "5e4a0525-fb0a-4b5e-a4e8-553d195282c4"\n }\n}'}, None, {'data': '{"text": "由于接口出错，[查询的数据描述]未查询到具体数值。"}', 'structure': '\n{\n "newTitle": "11月三级指挥中心线上督查发现问题分析",\n "oldTitle": "8月三级指挥中心线上督查发现问题分析",\n "chartStructure": {\n "dataSet": [\n {"data": null, "label": "广州"},\n {"data": null, "label": "茂名"},\n {"data": null, "label": "清远"},\n {"data": null, "label": "汕尾"},\n {"data": null, "label": "肇庆"},\n {"data": null, "label": "佛山"},\n {"data": null, "label": "江门"},\n {"data": null, "label": "东莞"},\n {"data": null, "label": "湛江"},\n {"data": null, "label": "梅州"},\n {"data": null, "label": "潮州"},\n {"data": null, "label": "阳江"},\n {"data": null, "label": "揭阳"},\n {"data": null, "label": "汕头"},\n {"data": null, "label": "中山"},\n {"data": null, "label": "惠州"},\n {"data": null, "label": "韶关"},\n {"data": null, "label": "珠海"},\n {"data": null, "label": "河源"},\n {"data": null, "label": "云浮"},\n {"data": null, "label": "类别"}\n ],\n "titleRowDatas": ["省", "地", "县", "总"]\n }\n}'}, {'data': '{"text": "\\n\\n\\n\\n任务描述：获取2025年11月各地市局生产指挥中心督查发现违章率数据，统计各分局的A/B/C/D类违章数量、违章发现率和AB类违章问题发现率\\n执行结果：由于接口出错，各分局的A/B/C/D类违章数量、违章发现率、AB类违章问题发现率未查询到具体数值。"}', 'structure': '\n{\n "newTitle": "11月各地市局生产指挥中心督查发现违章率",\n "oldTitle": "8月各地市局生产指挥中心督查发现违章率",\n "chartData": {\n "code": 0,\n "data": [],\n "msg": "未查询到符合督查数据范围的2025年11月违章数据",\n "requestId": "be76b2d9-ab57-4834-bff8-d888233390ac"\n }\n}'}, {'data': '{"text": "\\n由于接口出错，无法获取2025年11月共性违章问题数据的具体数值。\\n\\n根据任务描述，需统计广东地区2025年11月1日至30日管控作业中违章代码为C87、D07、D10、D06、D05、C09的作业总数，并按违章类型分类。但调用work_plans_count_work_plans_count_post接口时出现500服务器内部错误，错误信息显示数据库连接异常。后续尝试通过eval_expression进行计算时也因变量未定义而失败。\\n\\n建议检查以下问题：\\n1. 数据库连接是否正常；\\n2. 参数not_null_fields中的字段名是否与后端一致；\\n3. 时间范围参数格式是否符合接口要求；\\n4. work_code字段是否支持模糊查询及数组传参。"}', 'structure': '\njson\\n{\\n \"newTitle\": \"11月共性违章问题\",\\n \"oldTitle\": \"8月共性违章问题\",\\n \"chartStructure\": {\\n \"dataSet\": [\\n {\"data\": null, \"label\": \"视频规范类\"},\\n {\"data\": null, \"label\": \"系统作业信息规范类\"},\\n {\"data\": null, \"label\": \"作业文件规范类\"},\\n {\"data\": null, \"label\": \"风险评估错误\"},\\n {\"data\": null, \"label\": \"未正确佩戴安全帽\"}\\n ],\\n \"titleRowDatas\": [\"销售额\"]\\n }\\n}\\n'}, {'data': '{"text": "\\n\\n\\n由于接口出错，中高风险作业计划数据未查询到具体数值。"}', 'structure': '\n{\n "newTitle": "2025年12月中高风险作业计划",\n "oldTitle": "9月份中高风险作业计划",\n "chartStructure": {\n "dataSet": [\n {"data": null, "label": "广州"}, {"data": null, "label": "佛山"}, \n {"data": null, "label": "湛江"}, {"data": null, "label": "东莞"}, \n {"data": null, "label": "中山"}, {"data": null, "label": "韶关"},\n {"data": null, "label": "梅州"}, {"data": null, "label": "江门"},\n {"data": null, "label": "惠州"}, {"data": null, "label": "清远"},\n {"data": null, "label": "肇庆"}, {"data": null, "label": "茂名"},\n {"data": null, "label": "汕尾"}, {"data": null, "label": "阳江"},\n {"data": null, "label": "汕头"}, {"data": null, "label": "揭阳"},\n {"data": null, "label": "云浮"}, {"data": null, "label": "珠海"},\n {"data": null, "label": "潮州"}, {"data": null, "label": "河源"}\n ],\n "titleRowDatas": ["中风险", "高风险"]\n }\n}'}, {'data': '{"text": "\\n由于接口出错，本月作业计划按人数区间统计未查询到具体数值。建议检查参数配置或联系接口维护人员处理。"}', 'structure': '\n{\n "newTitle": "12月份作业人数分布情况",\n "oldTitle": "9月份作业人数分布情况",\n "chartStructure": {\n "code": 0,\n "data": [{\n "dataSet": [{\n "data": null,\n "label": "广州"\n }, {\n "data": null,\n "label": "中山"\n }, {\n "data": null,\n "label": "江门"\n }, {\n "data": null,\n "label": "东莞"\n }, {\n "data": null,\n "label": "佛山"\n }, {\n "data": null,\n "label": "韶关"\n }, {\n "data": null,\n "label": "湛江"\n }, {\n "data": null,\n "label": "清远"\n }, {\n "data": null,\n "label": "茂名"\n }, {\n "data": null,\n "label": "惠州"\n }, {\n "data": null,\n "label": "揭阳"\n }, {\n "data": null,\n "label": "梅州"\n }, {\n "data": null,\n "label": "阳江"\n }, {\n "data": null,\n "label": "珠海"\n }, {\n "data": null,\n "label": "肇庆"\n }, {\n "data": null,\n "label": "河源"\n }, {\n "data": null,\n "label": "云浮"\n }, {\n "data": null,\n "label": "汕头"\n }, {\n "data": null,\n "label": "潮州"\n }, {\n "data": null,\n "label": "汕尾"\n }],\n "oldTitle": "9月份作业人数分布情况",\n "titleRowDatas": ["30人以内", "30-49人", "50-99人", "100人及以上"]\n }],\n "msg": "",\n "requestId": "1964d0e0-7762-404d-8587-ab1306613c7a"\n }\n}'}, {'data': '{"text": "\\n\\n由于接口出错，2025年12月重点关注风险情况未查询到具体数值。"}', 'structure': '\n{\n "newTitle": "2025年12月重点关注风险情况",\n "oldTitle": "9月份重点关注风险情况",\n "chartData": {\n "code": 0,\n "data": [\n {\n "dataSet": [\n {"data": null, "label": "东莞"},\n {"data": null, "label": "佛山"},\n {"data": null, "label": "广州"},\n {"data": null, "label": "茂名"},\n {"data": null, "label": "中山"},\n {"data": null, "label": "梅州"},\n {"data": null, "label": "肇庆"},\n {"data": null, "label": "清远"},\n {"data": null, "label": "揭阳"},\n {"data": null, "label": "河源"},\n {"data": null, "label": "惠州"},\n {"data": null, "label": "江门"},\n {"data": null, "label": "湛江"},\n {"data": null, "label": "韶关"},\n {"data": null, "label": "云浮"},\n {"data": null, "label": "珠海"},\n {"data": null, "label": "汕尾"},\n {"data": null, "label": "汕头"},\n {"data": null, "label": "潮州"},\n {"data": null, "label": "阳江"}\n ],\n "oldTitle": "9月份重点关注风险情况",\n "titleRowDatas": [\n "涉管线路",\n "深基坑",\n "有限空间",\n "高支模",\n "重型机械",\n "高处作业"\n ]\n }\n ],\n "msg": "",\n "requestId": "9d466b9f-2869-4543-84f1-213fc52d7d11"\n }\n}'}, {'data': '{"text": "\\n由于接口出错，12月份重点关注作业风险分布情况未查询到具体数值。"}', 'structure': '\njson\\n{\\n \"newTitle\": \"12月份重点关注作业风险分布情况\",\\n \"oldTitle\": \"9月份重点关注作业风险分布情况\",\\n \"chartStructure\": {\\n \"dataSet\": [\\n {\"data\": null, \"label\": \"涉管线路\"},\\n {\"data\": null, \"label\": \"深基坑\"},\\n {\"data\": null, \"label\": \"有限空间\"},\\n {\"data\": null, \"label\": \"高支模\"},\\n {\"data\": null, \"label\": \"重型机械\"},\\n {\"data\": null, \"label\": \"高处作业\"}\\n ]\\n }\\n}\\n'}, None]" }