Any2Markdown MCP 服务器

一个高性能的文档转换服务器，同时支持 Model Context Protocol (MCP 模型上下文协议) 和 RESTful API 接口。将 PDF、Word 和 Excel 文档转换为 Markdown 格式，具备图片提取、页眉页脚移除和批量处理等高级功能。

📚 语言版本: English README | 中文说明

✨ 核心特性

🔄 双协议支持

• MCP 协议：原生支持模型上下文协议和流式 HTTP 传输
• RESTful API：传统 HTTP API，配备 OpenAPI/Swagger 文档
• 统一后端：两种协议共享相同的转换逻辑

📄 文档转换

• PDF 转 Markdown：基于 marker-pdf 的高质量文本提取
• Word 转 Markdown：支持 .docx/.doc 格式，保持格式化
• Excel 转 Markdown：支持 .xlsx/.xls 格式，表格转换
• 批量处理：并发处理多个文档

🖼️ 高级功能

• 图片提取：从文档中提取图片并通过静态 URL 提供服务
• 页眉页脚移除：智能移除重复的页面元素
• 多格式输出：Markdown、HTML 和 JSON 输出格式
• 结构分析：文档结构分析和验证
• 并发处理：高性能异步处理和速率限制

🚀 快速开始

系统要求

• Python 3.10 - 3.13（已验证 Python 3.13，暂不建议 3.14）
• 4GB+ 内存（用于 AI 模型）
• 10GB+ 磁盘空间（用于模型缓存）

安装

# 克隆仓库
git clone https://github.com/WW-AI-Lab/any2markdown.git
cd any2markdown

# 创建虚拟环境（推荐使用 Python 3.13）
python3.13 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 准备环境变量文件
cp env.example .env

# 安装依赖（默认使用华为镜像）
PIP_CONFIG_FILE=.pip/pip.conf pip install -r requirements.txt

# 或一键安装
./scripts/setup_venv.sh

快速启动

方式一：Docker 部署（推荐，开箱即用）

# 使用预构建镜像直接启动服务
docker run -d \
  -p 3000:3000 \
  --name any2markdown-mcp-server \
  --restart unless-stopped \
  -v $(pwd)/uploads:/app/uploads \
  -v $(pwd)/temp_images:/app/temp_images \
  -v $(pwd)/logs:/app/logs \
  -v $(pwd)/models:/root/.cache/marker \
  -v $(pwd)/models/huggingface:/root/.cache/huggingface \
  -v $(pwd)/models/torch:/root/.cache/torch \
  -v $(pwd)/models/transformers:/root/.cache/transformers \
  ccr.ccs.tencentyun.com/yfgaia/any2markdown-mcp-server:latest

# 💡 卷挂载说明：
# - uploads/: 上传文件存储
# - temp_images/: 临时图片缓存  
# - logs/: 日志文件
# - models/: AI模型缓存（首次运行会自动下载，约3-5GB）

# 或使用部署脚本
./scripts/deploy.sh docker

# GPU 加速部署（需要 NVIDIA GPU）
./scripts/deploy.sh docker-gpu

# 自定义端口部署
./scripts/deploy.sh docker -p 8080

# 或直接使用 docker-compose：
docker-compose up -d any2markdown-mcp

方式二：源码部署（开发环境）

# 使用部署脚本启动服务器
./scripts/deploy.sh source

# 或手动启动：
python run_server.py

# 服务器将在以下地址可用：
# - MCP 协议：http://localhost:3000/mcp (流式 HTTP)
# - REST API：http://localhost:3000/api/v1/
# - API 文档：http://localhost:3000/api/v1/docs

测试安装

# 测试 RESTful API
python test_restful_api.py

# 测试 MCP 协议（官方 SDK，streamable-http）
python test_streamable_client.py ~/Downloads/测试翻译_1_1_translate.docx

# 检查服务状态
./scripts/deploy.sh status

# 停止服务
./scripts/deploy.sh stop

📖 使用示例

RESTful API

📋 完整API文档: 详细的API设计和使用说明请参考 RESTful API 设计文档

📋 dify集成文档: 详细的dify集成文档请参考 dify集成文档

Any2Markdown 提供统一的RESTful API接口，支持两种调用方式：

快速开始

# 文件上传方式 (推荐)
curl -X POST "http://localhost:3000/api/v1/convert" \
  -F "file=@document.pdf" \
  -F "extract_images=true" \
  -F "include_content=false"

# JSON方式 (base64编码)
curl -X POST "http://localhost:3000/api/v1/convert" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [{
      "filename": "document.pdf",
      "file_content": "<base64编码的PDF>",
      "options": {
        "extract_images": true,
        "include_content": false
      }
    }]
  }'

# 查看系统状态
curl "http://localhost:3000/api/v1/status"

# 访问API文档
open http://localhost:3000/api/v1/docs

支持的功能

• ✅ 统一端点: 单一/api/v1/convert端点处理所有文档类型
• ✅ 双调用方式: 支持文件上传和base64 JSON两种方式
• ✅ 多文件处理: 支持批量转换多个文档
• ✅ 自动检测: 根据文件扩展名自动识别文档类型
• ✅ 丰富选项: 支持图片提取、页面范围、格式保留等选项

MCP 协议

from mcp.client import ClientSession
from mcp.client.stdio import stdio_client

# 连接到 MCP 服务器
async with stdio_client() as (read, write):
    async with ClientSession(read, write) as session:
        # 转换 PDF 文档
        result = await session.call_tool(
            "convert_pdf_to_markdown",
            {
                "file_content": base64_pdf_content,
                "filename": "document.pdf",
                "extract_images": True,
                "remove_header_footer": True
            }
        )
        print(result.content)

🛠️ 可用工具/端点

工具/端点	描述	输入格式	功能特性
convert_pdf_to_markdown	PDF 转换，AI 驱动的文本提取	PDF	OCR、布局检测、图片提取
convert_word_to_markdown	Word 文档转换	DOCX, DOC	格式保持、图片提取
convert_excel_to_markdown	电子表格转换	XLSX, XLS	多工作表、公式支持
batch_convert_documents	批量处理	混合格式	并发处理
analyze_pdf_structure	文档结构分析	PDF	元数据提取
validate_document	文档验证	所有格式	格式验证
get_supported_formats	列出支持的格式	-	功能发现

🏗️ 架构设计

┌─────────────────────────┐  ┌─────────────────────────┐
│     MCP 客户端          │  │    HTTP 客户端          │
│  (Claude, IDE 等)       │  │  (Web, Mobile 等)       │
└─────────────────────────┘  └─────────────────────────┘
            │                            │
            ▼                            ▼
┌─────────────────────────────────────────────────────┐
│              Any2Markdown 服务器                    │
├─────────────────────────┬───────────────────────────┤
│     MCP 协议            │      RESTful API          │
│  (流式 HTTP)            │   (OpenAPI/Swagger)       │
└─────────────────────────┴───────────────────────────┘
            │                            │
            └─────────────┬──────────────┘
                          ▼
┌─────────────────────────────────────────────────────┐
│               共享后端                               │
├─────────────────────────────────────────────────────┤
│  文档处理器           │  模型管理器     │  工具模块    │
│  ├─ PDF (marker)      │  ├─ AI 模型     │  ├─ 文件    │
│  ├─ Word (python-docx)│  ├─ 缓存        │  ├─ 验证    │
│  └─ Excel (pandas)    │  └─ 内存        │  └─ 图片    │
└─────────────────────────────────────────────────────┘

📁 项目结构

any2markdown/
├── 📚 docs/                    # 文档
│   ├── README.md               # 项目概述
│   ├── technical-design.md     # 技术架构
│   ├── restful-api-design.md   # API 规范
│   └── requirements.md         # 需求分析
├── 💻 src/any2markdown_mcp/    # 源代码
│   ├── server.py               # 主服务器 (MCP + FastAPI)
│   ├── config.py               # 配置管理
│   ├── 🔧 tools/               # MCP 工具实现
│   │   ├── pdf_tools.py        # PDF 转换工具
│   │   ├── word_tools.py       # Word 转换工具
│   │   ├── excel_tools.py      # Excel 转换工具
│   │   └── utility_tools.py    # 实用工具
│   ├── 🌐 api/                 # RESTful API 层
│   │   ├── handlers.py         # API 端点
│   │   ├── models.py           # Pydantic 模型
│   │   └── utils.py            # API 工具
│   ├── ⚙️ processors/          # 文档处理器
│   │   ├── pdf_processor.py    # PDF 处理逻辑
│   │   ├── word_processor.py   # Word 处理逻辑
│   │   └── excel_processor.py  # Excel 处理逻辑
│   └── 🧠 models/              # AI 模型管理
│       └── model_manager.py    # 模型加载和缓存
├── 🧪 tests/                   # 测试文件
├── 🚀 scripts/                 # 部署脚本
│   └── deploy.sh               # 统一部署脚本
├── 📋 requirements.txt         # 依赖列表
├── 🏗️ pyproject.toml           # 项目配置
├── 🐳 Dockerfile               # Docker 配置
├── 🐳 docker-compose.yml       # Docker Compose 配置
└── 🚀 run_server.py            # 服务器启动脚本

⚙️ 配置

环境变量

# 服务器配置
MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=3000

# 处理配置  
MAX_CONCURRENT_JOBS=3
MAX_FILE_SIZE=100MB
TEMP_IMAGE_DIR=./temp_images

# 模型配置
MODEL_CACHE_DIR=~/.cache/marker
USE_GPU=true

# Hugging Face模型缓存配置
HF_HOME=~/.cache/huggingface
HF_HUB_CACHE=~/.cache/huggingface/hub
HF_ASSETS_CACHE=~/.cache/huggingface/assets
TORCH_HOME=~/.cache/torch
TRANSFORMERS_CACHE=~/.cache/transformers

# 模型下载配置
HF_HUB_ENABLE_HF_TRANSFER=false
HF_HUB_DISABLE_PROGRESS_BARS=false
HF_HUB_DISABLE_TELEMETRY=true

# 日志配置
LOG_LEVEL=INFO
LOG_FILE=logs/server.log
DEBUG=false

部署选项

源码部署

# 基础部署
./scripts/deploy.sh source

# 开发模式，启用调试日志
./scripts/deploy.sh source --dev

# 自定义端口并禁用 GPU
./scripts/deploy.sh source -p 8080 --no-gpu

# 自定义环境文件
./scripts/deploy.sh source -e .env.production

Docker 部署

# 标准 Docker 部署
./scripts/deploy.sh docker

# GPU 加速部署（需要 NVIDIA Docker）
./scripts/deploy.sh docker-gpu

# 自定义端口
./scripts/deploy.sh docker -p 8080

# 开发模式
./scripts/deploy.sh docker --dev

模型缓存配置

为了避免每次重启容器都重新下载模型，建议配置模型缓存目录挂载：

# 1. 初始化模型缓存目录结构
./scripts/setup_model_cache.sh

# 2. 使用 Docker Compose（推荐）
docker-compose up -d

# 3. 或者手动指定挂载目录
docker run -d \
  -p 3000:3000 \
  -v ./models/marker:/home/appuser/.cache/marker \
  -v ./models/huggingface:/home/appuser/.cache/huggingface \
  -v ./models/torch:/home/appuser/.cache/torch \
  -v ./models/transformers:/home/appuser/.cache/transformers \
  -v ./logs:/app/logs \
  -v ./temp_images:/app/temp_images \
  --name any2markdown \
  any2markdown:latest

模型缓存说明：

• 首次启动：系统会自动下载所需模型（约3-5GB），需要较长时间
• 后续启动：使用缓存的模型，启动速度显著提升
• 磁盘空间：建议预留至少10GB空间用于模型缓存
• 网络要求：需要能够访问 Hugging Face Hub

服务管理

# 检查服务状态
./scripts/deploy.sh status

# 停止所有服务
./scripts/deploy.sh stop

# 清理资源
./scripts/deploy.sh cleanup

配置文件

创建 config.toml 或设置环境变量：

[server]
host = "0.0.0.0"
port = 3000
max_concurrent_jobs = 3

[processing]
max_file_size = "100MB"
temp_image_dir = "./temp_images"
enable_header_footer_removal = true

[models]
cache_dir = "~/.cache/marker"
enable_gpu = true
preload_models = true

# Hugging Face 模型缓存配置
hf_home = "~/.cache/huggingface"
hf_hub_cache = "~/.cache/huggingface/hub"
hf_assets_cache = "~/.cache/huggingface/assets"
torch_home = "~/.cache/torch"
transformers_cache = "~/.cache/transformers"

# 模型下载选项
hf_hub_enable_hf_transfer = false
hf_hub_disable_progress_bars = false
hf_hub_disable_telemetry = true

[logging]
level = "INFO"
file = "logs/server.log"

🧪 测试

# 运行所有测试
pytest

# 运行特定测试类别
pytest -m unit          # 单元测试
pytest -m integration   # 集成测试
pytest -m slow          # 需要模型加载的测试

# 运行覆盖率测试
pytest --cov=src/any2markdown_mcp --cov-report=html

# 测试特定功能
python test_restful_api.py      # REST API 测试
python test_streamable_client.py ~/Downloads/测试翻译_1_1_translate.docx  # MCP 协议测试

dify集成

支持在dify工作流中集成，即通过dify 默认的http节点即可实现文件转换，具体方法查阅dify集成

📊 性能

基准测试

• PDF 转换：~2-5 秒/页（使用 GPU）
• Word 转换：~0.5-2 秒/文档
• Excel 转换：~0.1-1 秒/工作表
• 并发请求：最多 3 个同时转换
• 内存使用：~2-4GB（模型加载后）

优化建议

• 为 PDF 处理启用 GPU 加速
• 根据可用内存调整 MAX_CONCURRENT_JOBS
• 为模型缓存使用 SSD 存储
• 为大型文档配置适当的超时值

🤝 贡献

我们欢迎贡献！请查看我们的贡献指南。

开发环境设置

# 安装开发依赖
pip install -e ".[dev]"

# 安装 pre-commit 钩子
pre-commit install

# 运行代码质量检查
black src/ tests/
isort src/ tests/  
mypy src/
flake8 src/
pytest

添加新文档类型

1. 在 src/any2markdown_mcp/processors/ 中创建处理器
2. 在 src/any2markdown_mcp/tools/ 中添加 MCP 工具
3. 在 src/any2markdown_mcp/api/ 中添加 API 端点
4. 更新文档和测试

📄 API 文档

• 交互式 API 文档：http://localhost:3000/api/v1/docs
• OpenAPI 规范：http://localhost:3000/api/v1/openapi.json
• 技术设计：docs/technical-design.md
• API 设计：docs/restful-api-design.md

🔗 相关项目

• 模型上下文协议 - 官方 MCP 规范
• marker-pdf - PDF 转 Markdown 转换
• python-docx - Word 文档处理
• FastAPI - 现代 Web 框架

📝 许可证

本项目使用 MIT 许可证 - 详见 LICENSE 文件。

🙋 支持

• 文档：docs/
• 问题反馈：GitHub Issues
• 讨论：GitHub Discussions

🎯 发展路线图

• [ ] 支持 PowerPoint (PPTX) 转换
• [ ] 图片类型PDF转换效果优化
• [ ] Kubernetes 部署清单
• [ ] 云存储集成