134 lines
4.0 KiB
Markdown
134 lines
4.0 KiB
Markdown
## 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 过滤器等高级格式控制。
|
||
|
||
### 安装依赖（本机运行）
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
请确保系统已安装 Pandoc（`pandoc --version` 可正常执行）。
|
||
|
||
### 使用方法
|
||
|
||
#### 方式一：本机直接运行
|
||
|
||
运行服务器：
|
||
|
||
```bash
|
||
python mcp_docx_server.py
|
||
```
|
||
|
||
在 MCP 客户端中连接该服务器后，会看到上述三个工具。
|
||
|
||
#### 输出 URL（output_url）
|
||
|
||
如果你希望 `edit_docx` 返回一个可直接访问的 URL，需要：
|
||
|
||
- 在运行服务器前设置环境变量 `MCP_OUTPUT_BASE_URL`，例如：
|
||
|
||
```bash
|
||
set MCP_OUTPUT_BASE_URL=http://localhost:8000/files/
|
||
```
|
||
|
||
或在类 Unix 系统中：
|
||
|
||
```bash
|
||
export MCP_OUTPUT_BASE_URL="http://localhost:8000/files/"
|
||
```
|
||
|
||
然后确保你的 HTTP 服务器能在该前缀下提供生成的 DOCX 文件（默认逻辑是：`output_url = MCP_OUTPUT_BASE_URL + 文件名`）。
|
||
|
||
#### 方式二：使用 Docker 封装运行
|
||
|
||
本项目已提供 `Dockerfile`，可以直接构建镜像并运行：
|
||
|
||
```bash
|
||
# 构建镜像
|
||
docker build -t mcp-docx-server .
|
||
|
||
# 运行容器（前台运行）
|
||
docker run --rm -it mcp-docx-server
|
||
```
|
||
|
||
如果你希望在容器外部自定义 `ref.docx`、`color.lua` 或输出目录，可以通过挂载卷的方式：
|
||
|
||
```bash
|
||
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）中可改为：
|
||
|
||
```bash
|
||
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`，可以一条命令完成构建与运行：
|
||
|
||
```bash
|
||
# 构建并启动（前台）
|
||
docker-compose up --build
|
||
```
|
||
|
||
默认会：
|
||
|
||
- **构建镜像**：使用当前目录下的 `Dockerfile`
|
||
- **挂载当前目录到容器 `/app`**：方便直接访问 `ref.docx`、`color.lua` 和输出文件
|
||
- **在容器内执行**：`python mcp_docx_server.py`
|
||
|
||
如需在后台运行，可使用：
|
||
|
||
```bash
|
||
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 才能运行服务器
|
||
- 确保有足够的权限读取输入文件和写入输出文件
|
||
- 大文件转换可能需要较长时间
|
||
|