Pdftranslate MCP

🔬 PDF2ZH — 面向 FeatherFlow 的 PDF 翻译 MCP 服务器

一个精简的 MCP（模型上下文协议） 工具服务器，在翻译科学 PDF 文档时完整保留公式、图表、目录与排版。专为被 FeatherFlow 启动和管理而设计。

本项目基于 PDFMathTranslate 构建，裁剪至仅保留单一的 OpenAI 兼容翻译后端 —— 直接复用 FeatherFlow 已经连接的同一个 LLM。

✨ 主要特性

• MCP stdio 传输 —— 即插即用，兼容 FeatherFlow（或任何 MCP 兼容宿主）
• 保留公式与排版 —— 由基于 ONNX 的文档版面分析 + pdfminer/pymupdf 驱动
• 双路输出 —— 同时生成 单语（仅译文）与 双语对照（原文译文并排）两种 PDF
• 共享 FeatherFlow 的 LLM —— 通过环境变量接入 OpenAI 兼容端点，无需额外 API 密钥
• 跨平台 —— 支持 Linux 与 Windows；所有路径均使用 pathlib 以保证可移植性

🛠️ MCP 工具

📂 文件路径解析

translate_pdf 的 file 参数同时支持绝对路径与相对路径：

• 绝对路径 —— 按原样使用（例如 /home/user/.featherflow/workspace/paper.pdf）
• 相对路径 —— 相对于工作区目录进行解析（默认为 ~/.featherflow/workspace，可通过 WORKSPACE_DIR 环境变量覆盖）

输出 PDF 默认写入工作区目录。返回的路径始终为绝对路径，因此可直接被其他 MCP 工具使用（例如 feishu-mcp 的 upload_file / upload_file_and_share）。

⚙️ 环境要求

⚠️ Python 环境隔离 —— 重要

本项目依赖 babeldoc / onnxruntime，它们要求 Python ≥3.10, <3.13。 FeatherFlow 本身可能运行在不同的 Python 版本上（例如 3.13+）。 你必须为本项目创建一个独立的 Python 环境，并将 FeatherFlow 的 MCP 配置指向本项目的 Python 可执行文件 —— 而不是 FeatherFlow 自身的 Python。

• Python 3.10 – 3.12（推荐：3.12）
• uv（推荐）、Conda 或 virtualenv，用于实现环境隔离

📦 安装指南

0. 安装 uv（一次性设置，推荐）

uv 可以自动下载并管理任意 Python 版本 —— 无需手动安装 Python 3.12。

# Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装完成后重启终端，然后验证：

uv --version

1. 创建专用的 Python 3.12 环境

使用 uv（推荐 —— 即便你只有 3.13+ 也会自动下载 Python 3.12）：

cd /path/to/pdftranslate-mcp
uv venv .venv --python 3.12

激活环境：

# Linux / macOS
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

# Windows CMD
.venv\Scripts\activate.bat

备选方案：Conda

conda create -p /path/to/pdftranslate-mcp/.venv python=3.12 -y
conda activate /path/to/pdftranslate-mcp/.venv

备选方案：venv（仅当系统 Python 已为 3.10–3.12 时可用）

python3.12 -m venv .venv
source .venv/bin/activate        # Linux/macOS
# .venv\Scripts\Activate.ps1     # Windows PowerShell

2. 安装软件包

pip install -e .

或使用 uv（快 10–100 倍）：

uv pip install -e .

这将安装所有依赖项：pymupdf、pdfminer-six、babeldoc、onnxruntime、openai、mcp 等。

3. 验证

python -m pdf2zh.mcp_server --help

🔌 FeatherFlow 配置

编辑 ~/.featherflow/config.json（或你所用配置方案对应的配置文件），在 tools.mcpServers 下添加 pdf2zh。

关键点： command 必须指向本项目自己的 Python 可执行文件，而非 FeatherFlow 的 Python。本项目要求 Python <3.13，而 FeatherFlow 可能运行在更新的版本上。

示例（Linux —— 生产服务器）

{
  "tools": {
    "mcpServers": {
      "pdf2zh": {
        "command": "/opt/PDFMathTranslate/.venv/bin/python",
        "args": ["-m", "pdf2zh.mcp_server"],
        "toolTimeout": 600,
        "env": {
          "OPENAI_BASE_URL": "https://openrouter.ai/api/v1",
          "OPENAI_API_KEY": "sk-or-v1-xxxxxxxx",
          "OPENAI_MODEL": "anthropic/claude-opus-4-5"
        }
      }
    }
  }
}

示例（Windows —— 开发环境）

{
  "tools": {
    "mcpServers": {
      "pdf2zh": {
        "command": "C:/Users/<you>/code/PDFMathTranslate/.venv/python.exe",
        "args": ["-m", "pdf2zh.mcp_server"],
        "toolTimeout": 600,
        "env": {
          "OPENAI_BASE_URL": "https://openrouter.ai/api/v1",
          "OPENAI_API_KEY": "sk-or-v1-xxxxxxxx",
          "OPENAI_MODEL": "anthropic/claude-opus-4-5"
        }
      }
    }
  }
}

💡 提示： 在 Windows 上，JSON 路径中使用正斜杠 / —— 它们与 Python 的 pathlib 配合良好。

⏱️ 工具超时 —— PDF 翻译的关键

⚠️ 你必须为 pdf2zh MCP 服务器设置 toolTimeout。

FeatherFlow 默认的 MCP 工具超时为 30 秒。PDF 翻译是一项重操作 —— 一篇 6 页的论文通常需要 1–5 分钟，具体取决于 LLM 的速度。若不增大 toolTimeout，工具调用将在翻译中途被取消，Agent 会报告失败。

推荐值： "toolTimeout": 600（10 分钟）。对于超长文档（50+ 页），可考虑 1200（20 分钟）。

"pdf2zh": {
  "command": "...",
  "args": ["-m", "pdf2zh.mcp_server"],
  "toolTimeout": 600,
  ...
}

🌐 环境变量

OPENAI_* 变量与 FeatherFlow 使用的凭证相同 —— 只需通过 env 透传即可。WORKSPACE_DIR 通常无需设置；它会自动使用 FeatherFlow 的默认工作区。

🧪 独立使用（不依赖 FeatherFlow）

stdio 模式（默认）

python -m pdf2zh.mcp_server

SSE 模式（用于基于 Web 的 MCP 客户端）

python -m pdf2zh.mcp_server --sse --host 0.0.0.0 --port 3001

🔗 跨 MCP 工作流：pdf2zh + feishu-mcp

本项目设计为与 feishu-mcp 协同工作。一个典型的端到端流程如下：

User: "Translate this paper and share it in the Feishu group"
  ↓
FeatherFlow (LLM orchestration):
  1. paper_download → ~/.featherflow/workspace/paper.pdf
  2. pdf2zh.translate_pdf(file="paper.pdf", lang_in="en", lang_out="zh")
     → ~/.featherflow/workspace/paper-mono.pdf
     → ~/.featherflow/workspace/paper-dual.pdf
  3. feishu-mcp.upload_file_and_share(file_path="/home/user/.featherflow/workspace/paper-dual.pdf")
     → share_url
  4. feishu-mcp.send_message(chat_id, share_url)

为何此流程能够无缝衔接：

• pdf2zh 默认将输出写入 ~/.featherflow/workspace
• feishu-mcp 的 upload_file / upload_file_and_share 接受绝对文件路径
• pdf2zh 在结果中返回绝对路径 —— LLM 可以提取并直接传给 feishu-mcp
• 两个 MCP 服务器均作为本地进程运行在同一台机器上，共享同一文件系统

🗂️ 项目结构

pdf2zh/
  __init__.py        # Package entry, exports translate_stream
  mcp_server.py      # MCP server (entry point, tools definition)
  translator.py      # BaseTranslator + OpenAITranslator
  converter.py       # PDF content conversion & layout processing
  high_level.py      # Core translation pipeline (translate_stream)
  config.py          # Configuration & constants
  cache.py           # Translation cache (SQLite via peewee)
  doclayout.py       # ONNX document layout model loading
  pdfinterp.py       # Extended PDF interpreter
pyproject.toml       # Dependencies & build config

📄 许可证

AGPL-3.0

🙏 致谢

• 核心 PDF 翻译引擎来自 Byaidu 的 PDFMathTranslate
• FeatherFlow 的 MCP 宿主集成