DOCX 转换 / 编辑 MCP 服务器

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

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

功能

• list_docx_images：列出 DOCX 中的图片信息，支持 docx_path 为本地路径或 HTTP/HTTPS URL。
• edit_docx：对 DOCX 进行编辑，支持：
  • input_docx 为本地路径或 HTTP/HTTPS URL；
  • image_replacements[*].file 为本地路径或 HTTP/HTTPS URL；
  • 返回结果中包含 output_path 和可选的 output_url（见下文）。
• html_to_docx_pandoc：将包含 HTML 标签的文本转换为 DOCX 文件，支持引用模板、Lua 过滤器等高级格式控制。

安装依赖（本机运行）

pip install -r requirements.txt

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

使用方法

方式一：本机直接运行

运行服务器：

python mcp_docx_server.py

在 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 才能运行服务器
• 确保有足够的权限读取输入文件和写入输出文件
• 大文件转换可能需要较长时间