Pdftranslate MCP

🚀 PDF2ZH — PDF翻訳のためのFeatherFlow MCPサーバー

数式・図表・目次・レイアウトを保持したまま科学技術PDF文書を翻訳する、軽量なMCP (Model Context Protocol)ツールサーバー。FeatherFlow から起動・管理されることを想定して設計されています。

PDFMathTranslate をベースに、単一のOpenAI互換翻訳バックエンドへとスリム化したもので、FeatherFlowがすでに接続しているLLMをそのまま再利用します。

✨ 主な機能

• MCP stdio transport — FeatherFlow（または任意のMCP互換ホスト）とプラグアンドプレイで連携
• 数式とレイアウトを保持 — ONNXベースの文書レイアウト解析 + pdfminer/pymupdf による処理
• デュアル出力 — mono（翻訳のみ）と dual（対訳の見開き）の両方の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設定をFeatherFlow自身のPythonではなく、このプロジェクトの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 は、FeatherFlowのPythonではなく、このプロジェクト自身の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ページの論文でもLLMの速度によって通常1〜5分かかります。toolTimeout を増やさない場合、ツール呼び出しは翻訳の途中でキャンセルされ、エージェントは失敗を報告します。

推奨："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ホスト統合