MCP - DOCX/PDF文档生成服务

1. 项目简介

项目背景

在与大语言模型（LLM）进行交互时，我们常常会得到包含复杂格式（如数学公式、代码块、表格等）的 Markdown 文本。这些内容在网页上显示精美，但一旦被复制粘贴到本地编辑器（如 Microsoft Word），格式往往会变得混乱不堪。

解决方案

本MCP服务是一个旨在解决此问题的后端服务。它提供了一个核心功能：将标准 Markdown 文本高保真地转换为 DOCX 或 PDF 格式的文档。

该服务专为集成而设计。设想一个场景：用户在与一个大模型进行多轮对话后，要求模型将对话内容或最终结论整理成一份正式的文档。此时，大模型可以将整理好的 Markdown 文本发送给 MCP 服务，MCP 生成相应的 DOCX 或 PDF 文件，并返回一个可供用户直接下载的文件链接。

核心特性

高质量转换：基于强大的 Pandoc 和 LaTeX (xelatex) 引擎，确保 Markdown 中的各种元素（标题、列表、代码、表格、数学公式等）都能被正确转换。
格式支持：支持生成通用的 .docx 文件和高质量的 .pdf 文件。
中英文字体自定义：允许用户为文档内容分别指定中文字体和英文字体，解决了混合语言排版中的常见问题。
自动化依赖管理：服务启动时会自动检查并安装所需的系统级依赖（如 Pandoc, LaTeX, 字体库），简化了部署流程。
Web 界面与 API：提供一个简单的 Gradio Web 界面用于快速测试和手动转换，同时其架构也易于作为 API 服务被其他程序调用。

2. 部署指南

环境要求

操作系统: Debian 或基于 Debian 的 Linux 发行版 (如 Ubuntu)。这是因为脚本使用 apt-get 来安装系统依赖。
Python: Python 3.x
权限: 需要 root 或 sudo 权限来安装系统依赖。

安装步骤

克隆或下载项目 将项目文件（mcp_service.py 和 example.md）下载到您的服务器上。
准备 requirements.txt 在项目根目录下创建一个名为 requirements.txt 的文件，并填入以下内容：
```
gradio
pypandoc
python-docx
path.py
```
安装 Python 依赖 使用 pip 安装所有必要的 Python 库：
```
pip install -r requirements.txt
```
安装系统依赖（自动） 无需手动安装！脚本首次启动时会自动调用 apt-get 来安装所有必需的系统级软件包，包括：
- 核心工具: pandoc
- LaTeX 套件: texlive-full (或脚本中指定的精简组件)
- 字体库: 文泉驿微米黑、文鼎楷体、文鼎宋体、Liberation 字体家族等。
注意：由于需要安装系统软件包，请确保以 root 用户身份运行此脚本，或者运行的用户拥有无密码执行 sudo apt-get 的权限。

启动服务

直接运行 Python 脚本即可启动服务：

python mcp_service.py

服务启动后，您会在终端看到类似如下的输出：

🚀 [环境检查] 开始检查并安装系统依赖...
✅ [环境检查] 系统依赖已成功安装或已存在。
Running on local URL:  [http://127.0.0.1:7860](http://127.0.0.1:7860)

现在，您可以通过浏览器访问 http://127.0.0.1:7860 来使用该服务。

3. 使用方式

方式一：通过 Web 界面进行手动转换

对于需要手动转换文档的场景，可以直接使用服务提供的 Web UI。

打开浏览器：访问服务地址（例如 http://your-server-ip:7860）。
粘贴内容：在左侧的 "粘贴原始 Markdown 在此进行测试" 文本框中，输入或粘贴您的 Markdown 全文。
选择字体：根据需要，在下拉菜单中选择文档的 "中文字体" 和 "英文字体"。
选择格式：在 "选择输出格式" 中，点选 DOCX 或 PDF。
生成文档：点击蓝色的 "生成文档" 按钮。
下载文件：稍等片刻，右侧的 "下载生成的文档" 区域会显示可供下载的文件链接。同时，下方会显示处理状态和模拟的 JSON 返回报告。

方式二：作为 API 被大模型或其他服务调用

MCP 的核心价值在于其 API 能力。其他服务（如 LLM 应用后端）可以通过向 Gradio 的 API 端点发送 POST 请求来调用它。

API 端点: http://your-server-ip:7860/api/predict 请求方法: POST 请求体 (Body): JSON 格式

{
  "data": [
    "这里是完整的 Markdown **文本** 内容。\\n\\n# 这是一个标题\\n\\n一个公式：$E=mc^2$",
    "PDF",
    "文泉驿微米黑 (WenQuanYi Micro Hei)",
    "Liberation Serif"
  ]
}

参数说明 (data 数组中的元素按顺序对应):

markdown_content (string): 完整的 Markdown 字符串。
output_format (string): 输出格式，"DOCX" 或 "PDF"。
chinese_font (string): 中文字体选项，从支持的列表中选择。
english_font (string): 英文字体选项，从支持的列表中选择。

成功响应 (Response):

服务会返回一个 JSON 对象，其中 data 数组的第一个元素是文件下载链接，第二个元素为否生成成功，第三个元素是一些其他信息。

[
  {
    "type": "text",
    "text": "https://kun03036-doc-pdf.ms.show/gradio_api/file=/tmp/gradio/f01721dd797570dd2ea18aab4fed500430c98d90cafe0d919d5c0a14e2a5e651/f027b119-aee1-448c-94c6-cec7d45620b3.docx"
  },
  {
    "type": "text",
    "text": "文件已成功生成！"
  },
  {
    "type": "text",
    "text": "root={'status': 'success', 'file_url': 'downloads/f027b119-aee1-448c-94c6-cec7d45620b3.docx', 'message': '文件已成功生成！'}"
  }
]

调用方可以解析此 JSON，提取第一个元素的text字段，并将其返回给最终用户。

4. 示例

假设大模型为用户总结了技术报告内容如下：

# 综合技术报告：从傅里叶变换到神经网络

## 第一部分：信号处理基础

### 1.1 傅里叶变换简介

傅里叶变换（Fourier Transform）是一种将信号从时域转换到频域的重要工具。其连续形式定义为：

$$ \hat{f}(\xi) = \int_{-\infty}^{\infty} f(x)\ e^{-2\pi i x \xi} \,dx $$

这个公式展示了信号 $f(x)$ 如何分解为不同频率 $\xi$ 的复指数函数的叠加。其中 `$i$` 是虚数单位，满足 `$i^2 = -1$`。

### 1.2 关键属性

傅里叶变换具有多种**重要属性**，例如*线性*、*时移*和*频移*等。

> “数学是宇宙的语言。” - 伽利略

---

## 第二部分：机器学习核心

### 2.1 梯度下降算法

梯度下降是一种优化算法，用于寻找函数的局部最小值。其核心迭代步骤可以表示为：

$θ_{new} = θ_{old} - η * ∇J(θ)$

其中 `∇J(θ)` 是损失函数 `J` 对参数 `θ` 的梯度。

### 2.2 决策树与随机森林

下面是一个展示不同算法性能的表格，其中包含了对齐测试：

| 算法名称 | 准确率 (Accuracy) | 召回率 (Recall) | 备注 |
|:---:|:---|---:|
| 决策树 (Decision Tree) | 85.2% | 84.1% | 容易过拟合 |
| 随机森林 (Random Forest) | **92.5%** | **91.8%** | 性能更稳健 |
| `支持向量机 (SVM)` | 89.7% | 88.5% | 对高维数据有效 |

这是一个任务列表：
- [x] 完成数据预处理
- [ ] 训练模型
- [ ] 评估并撰写报告

---

## 第三部分：深度学习实践

### 3.1 卷积神经网络 (CNN)

CNN 在图像识别领域取得了巨大成功。一个典型的 CNN 层级结构如下：

1.  输入层 (Input Layer)
2.  卷积层 (Convolutional Layer)
    - 使用激活函数，如 ReLU: $f(x) = \max(0, x)$
3.  池化层 (Pooling Layer)
4.  全连接层 (Fully Connected Layer)
5.  输出层 (Output Layer)

![CNN 结构示意图](https://pic.rmb.bdstatic.com/bjh/cms/231215/ea07c51b84b7d4379eab1271c08bc94a_1702648348.5498_956.png)

### 3.2 Python 代码示例

以下是使用 `PyTorch` 构建一个简单神经网络的代码片段：

```python
import torch
import torch.nn as nn

class SimpleNet(nn.Module):
    def __init__(self):
        super(SimpleNet, self).__init__()
        self.layer1 = nn.Linear(784, 128)
        self.activation = nn.ReLU()
        self.layer2 = nn.Linear(128, 10)

    def forward(self, x):
        x = self.layer1(x)
        x = self.activation(x)
        x = self.layer2(x)
        return x
```

中间包含了编号、图片、代码块、latex公式等复杂信息，如果直接复制到docx中会损失部分信息，还需要手动整理混乱的格式。而本mcp服务可以直接返回一个下载链接，下载的docx示例见本项目中example.docx文件。

5. 改进方向

markdown格式矫正

现在v1.0版本生成DOCX和PDF的效果依赖于大模型的指令遵循，要求大模型返回规范的markdown文本作为输入。但实际上由于大模型很多时候返回的内容要用于浏览器渲染，所以不能保证严格的markdown格式。相信大家都见过大模型返回的一段代码，前一半在代码块中，后一半在文本中。或者在输出复杂公式的时候，成为一片乱码。

期望能够通过python包+分段检查+llm矫正的方式，修正markdown文本，从而生成高质量DOCX和PDF。

工具列表

markdown_to_document: 接收 Markdown 文本，使用 Pandoc 将其转换为指定格式的文档，并应用字体设置。

服务配置

[{'mcpServers': {'gradio': {'args': ['mcp-remote', 'https://kun03036-doc-pdf.ms.show/gradio_api/mcp/sse', '--transport', 'sse-only'], 'command': 'npx'}}}]

来源

来源：ModelScope
链接：https://modelscope.cn/studios/KUN03036/doc_pdf/

DOCX/PDF文档生成服务-MCP（MCP&Agent挑战赛）