DOCX/PDF文档生成服务-MCP（MCP&Agent挑战赛）
MCP 服务配置
复制以下 JSON 到 OPClaw 或其他 MCP 客户端的配置文件中即可使用
{
"mcpServers": {
"gradio": {
"args": [
"mcp-remote",
"https://kun03036-doc-pdf.ms.show/gradio_api/mcp/sse",
"--transport",
"sse-only"
],
"command": "npx"
}
}
}可用工具 （1 个）
该服务在 MCP 协议中暴露的工具，AI 可按需调用
markdown_to_document 4 个参数
接收 Markdown 文本，使用 Pandoc 将其转换为指定格式的文档，并应用字体设置。
该工具无需必填参数，直接调用即可
服务介绍
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)
### 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。
