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 宿主集成