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 规范可通过以下方式获取：

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

技术栈

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

注意事项

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

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

功能特性

✅ Markdown 到 Word 转换：支持标题、段落、列表、表格、代码块等常见Markdown元素

✅ HTTP API 接口：基于 Starlette 框架，提供 RESTful API

✅ MCP 协议支持：完全兼容 MCP (Model Context Protocol) 规范

✅ 临时文件管理：自动清理过期文件，默认2小时有效期

✅ OpenAPI 规范：提供完整的 API 文档

✅ CORS 支持：允许跨域访问

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_doc_converter/ ├── server.py # 主服务器文件 ├── requirements.txt # Python依赖 ├── README.md # 项目文档 ├── openapi.json # OpenAPI规范（独立文件） └── postman_collection.json # Postman集合