huoshui-pdf-translator

Huoshui PDF Translator

Version: 0.1.0
Powered by: FastMCP & PDFMathTranslate-next
PyPI Package: huoshui-pdf-translator

数式を含む学術論文を専門とする、インテリジェントな PDF 翻訳アシスタントです。FastMCP フレームワークを使用して構築され、PDFMathTranslate-next を活用することで、文脈を考慮した支援と包括的な翻訳機能を提供します。

🌟 特長

翻訳の主な機能

• 📚 学術論文：数式や方程式を優れた精度で処理します
• 🔬 技術文書：書式と専門用語を保持します
• 🌐 多言語対応：自動検出機能を備え、中国語 ↔ 英語に特化しています
• 🎨 レイアウトの保持：元の PDF の構造と書式を維持します

スマートアシスタント機能

• 🧠 文脈を考慮したプロンプト：さまざまなシナリオに対応する複数の専用プロンプト
• 🛠️ ツールの状態確認：翻訳ツールのインストール状況と利用可否を確認します
• 📊 PDF 分析：翻訳前に PDF ファイルの詳細情報を取得します
• 🔍 柔軟なパス指定：絶対パスと相対パスの両方に対応します
• ⚡ 進捗レポート：翻訳中にリアルタイムで進捗を更新します
• 🚨 インテリジェントなエラー処理：包括的なエラー診断とトラブルシューティング

MCP 機能

• 📋 リソース：翻訳機能の一覧と PDF ファイル情報
• 🎯 ツール：翻訳、PDF 分析、ツールの状態確認
• 💬 プロンプト：役割の定義、パスの案内、オプションの説明、エラーのトラブルシューティング
• 🔒 セキュリティ：システムディレクトリを保護する安全なパス検証

🚀 クイックスタート

インストール

MCP Registry から（推奨）

このサーバーは Model Context Protocol Registry で利用できます。お使いの MCP クライアントからインストールしてください。

mcp-name: io.github.huoshuiai42/huoshui-pdf-translator

uvx を使用

uvx huoshui-pdf-translator

Claude Desktop の設定

以下を Claude Desktop の MCP 設定に追加してください。

{
  "mcpServers": {
    "huoshui-pdf-translator": {
      "command": "uvx",
      "args": ["huoshui-pdf-translator"]
    }
  }
}

代替のインストール方法

pipx 経由：

pipx install huoshui-pdf-translator

UV tools 経由：

uv tool install huoshui-pdf-translator

UV tools 用の Claude Desktop 設定：

{
  "mcpServers": {
    "huoshui-pdf-translator": {
      "command": "uv",
      "args": ["tool", "run", "huoshui-pdf-translator"]
    }
  }
}

📖 使い方

初回セットアップ

1. ウォームアップ（フォント／モデルをダウンロード）：warm_up_translator ツールを使用します
2. 状態を確認：check_translation_tool ツールを使用します
3. 翻訳：PDF のパスを指定して translate_pdf ツールを使用します

MCP ツール

translate_pdf

数式とレイアウトを保持しながら PDF 文書を翻訳します。

# Basic usage
translate_pdf(pdf_path="Desktop/paper.pdf")

# With custom output path
translate_pdf(
    pdf_path="Documents/research.pdf",
    output_path="Documents/translated/research_cn.pdf"
)

pdf_get

PDF ファイルの詳細情報を取得します。

pdf_info = pdf_get(path="Desktop/document.pdf")
# Returns: PDFResource with path, size_bytes, page_count

warm_up_translator

必要なアセットとモデルをダウンロードします。タイムアウトを避けるため、最初に実行してください。

warm_up_translator()
# Downloads fonts and models (~50MB) for faster subsequent translations

check_translation_tool

PDFMathTranslate-next のインストール状況と状態を確認します。

status = check_translation_tool()
# Returns: status, version, message

MCP プロンプト

• role_and_rules：基本的な役割と運用ルール
• explain_pdf_paths：ファイルパスの指定方法を案内します
• explain_translation_options：利用可能なオプションとベストプラクティス
• troubleshoot_translation_error：エラーの診断と解決策
• explain_translation_result：結果の説明と次の手順

ファイルパスの例

アシスタントは柔軟なパス指定に対応しています。

# Absolute paths
/Users/john/Desktop/research.pdf
C:\Users\John\Documents\paper.pdf

# Relative to home directory
Desktop/research.pdf
Documents/papers/study.pdf

# Simple filenames (assumes home directory)
paper.pdf

🎯 翻訳ワークフロー

1. インストール：uvx huoshui-pdf-translator
2. Claude Desktop を設定：MCP 設定を追加します
3. ウォームアップ：warm_up_translator ツールを実行します（初回のみ）
4. 翻訳：PDF のパスを指定して translate_pdf を使用します
5. 確認：2 つのファイル（対訳版と中国語のみの版）が作成されます

⚡ パフォーマンス

• 初回の翻訳：2～5 分（フォント／モデルをダウンロード）
• 2 回目以降の翻訳：30～60 秒
• ファイルサイズの上限：最大 200MB
• キャッシュサイズ：フォントとモデルで約 50MB

🔍 トラブルシューティング

よくある問題

翻訳ツールを利用できない

このツールは必要に応じて pdf2zh-next を自動的にインストールします。問題が発生した場合：

# Check status
# Use check_translation_tool in Claude Desktop

# Manual install if needed
pip install pdf2zh-next

初回翻訳のタイムアウト

# Run warmup first
# Use warm_up_translator tool in Claude Desktop

PDF ファイルが見つかりません

• ファイルパスが正しいことを確認してください
• 分かりやすくするため、絶対パスを使用してください
• ファイルが移動または削除されていないか確認してください

ネットワークの問題

• インターネット接続を確認してください（初回のフォントダウンロードに必要です）
• ファイアウォールの設定を確認してください

エラーの診断

アシスタントは、次の問題に対して具体的な解決策を提示し、エラーをインテリジェントに診断します。

• ファイルが見つからないエラー
• 無効な PDF ファイル
• 翻訳ツールの問題
• ネットワーク接続の問題
• ファイルサイズの制限

🛠️ 開発

開発者向け

ソースからインストールする：

git clone https://github.com/huoshuiai/huoshui-pdf-translator.git
cd huoshui-pdf-translator
uv sync
uv run python -m huoshui_pdf_translator.main

ビルドして公開する：

uv build
uv run twine upload dist/*

プロジェクト構成

huoshui-pdf-translator/
├── huoshui_pdf_translator/
│   ├── __init__.py      # Package metadata
│   └── main.py         # FastMCP server implementation
├── pyproject.toml      # Package configuration
├── README.md          # This file
└── LICENSE           # Apache-2.0 license

🔄 更新

最新バージョンに更新する：

uvx install --upgrade huoshui-pdf-translator
# or
uv tool upgrade huoshui-pdf-translator

🤝 貢献

貢献を歓迎します。以下の手順に従ってください。

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更を加えます
4. 該当する場合はテストを追加します
5. プルリクエストを送信します

📄 ライセンス

このプロジェクトは Apache-2.0 ライセンスのもとでライセンスされています。詳細については LICENSE ファイルをご覧ください。

🙏 謝辞

• PDFMathTranslate-next：中核となる翻訳エンジン
• FastMCP：インテリジェントなアシスタント機能を実現するフレームワーク
• Anthropic：MCP プロトコルとエコシステム
• UV & PyPI：モダンな Python パッケージングと配布