MCP 文档转换服务

基于 Python MCP 框架开发的文档格式转换服务，支持通过 HTTP 方式调用，将 Markdown 文本转换为 Word 文档，并提供临时有效的下载链接（2小时有效期）。

功能特性

• ✅ Markdown 到 Word 转换：支持标题、段落、列表、表格、代码块等常见Markdown元素
• ✅ HTTP API 接口：基于 Starlette 框架，提供 RESTful API
• ✅ MCP 协议支持：完全兼容 MCP (Model Context Protocol) 规范
• ✅ 临时文件管理：自动清理过期文件，默认2小时有效期
• ✅ OpenAPI 规范：提供完整的 API 文档
• ✅ CORS 支持：允许跨域访问

快速开始

1. 安装依赖

pip install -r requirements.txt

2. 启动服务

python server.py

服务将在 http://localhost:8000 启动。

3. 访问 API 文档

打开浏览器访问：

• OpenAPI 规范：http://localhost:8000/openapi.json
• 健康检查：http://localhost:8000/health

API 使用示例

1. 健康检查

curl http://localhost:8000/health

响应：

{
  "status": "healthy",
  "service": "MCP Document Converter",
  "version": "1.0.0",
  "timestamp": "2025-11-05T23:17:01.000000"
}

2. 转换 Markdown 到 Word（通过 MCP）

curl -X POST http://localhost:8000/mcp/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "markdown_to_word",
      "arguments": {
        "markdown_content": "# 标题\n\n这是一个段落。\n\n## 子标题\n\n- 列表项1\n- 列表项2",
        "filename": "my_document"
      }
    }
  }'

3. 列出所有文件

curl http://localhost:8000/files

响应：

{
  "files": [
    {
      "file_id": "uuid-here",
      "filename": "my_document_uuid.docx",
      "download_url": "/download/uuid-here",
      "created_at": "2025-11-05T23:17:01.000000",
      "expiry_time": "2025-11-06T01:17:01.000000"
    }
  ],
  "count": 1
}

4. 下载文件

curl -O http://localhost:8000/download/{file_id}

MCP 工具说明

markdown_to_word

将 Markdown 文本转换为 Word 文档。

输入参数：

• markdown_content (必需): Markdown 格式的文本内容
• filename (可选): 输出文件名，默认为 "document"

返回：

• 成功消息，包含文件ID、下载链接、过期时间等信息

支持的 Markdown 元素

• 标题 (H1-H6)
• 段落
• 无序列表
• 有序列表
• 代码块
• 表格
• 粗体、斜体等文本格式

配置说明

可以在 server.py 中修改以下配置：

FILE_EXPIRY_HOURS = 2  # 文件有效期（小时）
TEMP_DIR = Path(tempfile.gettempdir()) / "mcp_doc_converter"  # 临时文件目录

项目结构

mcp_doc_converter/
├── server.py           # 主服务器文件
├── requirements.txt    # Python依赖
├── README.md          # 项目文档
├── openapi.json       # OpenAPI规范（独立文件）
└── postman_collection.json  # Postman集合

OpenAPI 规范

完整的 OpenAPI 3.0 规范可通过以下方式获取：

1. 在线访问：http://localhost:8000/openapi.json
2. 独立文件：查看项目根目录的 openapi.json

技术栈

• MCP Framework: Model Context Protocol 服务器框架
• Starlette: 轻量级 ASGI 框架
• Uvicorn: ASGI 服务器
• python-docx: Word 文档生成
• markdown: Markdown 解析
• BeautifulSoup: HTML 解析

注意事项

1. 文件默认2小时后自动删除
2. 临时文件存储在系统临时目录
3. 服务重启后，之前生成的文件链接将失效
4. 建议在生产环境中配置持久化存储和认证机制

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！