Huoshui PDF Translator

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

An intelligent PDF translation assistant that specializes in academic papers with mathematical formulas. Built using the FastMCP framework and powered by PDFMathTranslate-next, it provides comprehensive translation capabilities with context-aware assistance.

🌟 Features

Core Translation Capabilities

📚 Academic Papers: Excellent handling of mathematical formulas and equations
🔬 Technical Documents: Preserves formatting and technical terminology
🌐 Multi-language Support: Auto-detection with Chinese ↔ English specialization
🎨 Layout Preservation: Maintains original PDF structure and formatting

Smart Assistant Features

🧠 Context-Aware Prompts: Multiple specialized prompts for different scenarios
🛠️ Tool Status Checking: Verify translation tool installation and availability
📊 PDF Analysis: Get detailed information about PDF files before translation
🔍 Flexible Path Handling: Support for both absolute and relative file paths
⚡ Progress Reporting: Real-time progress updates during translation
🚨 Intelligent Error Handling: Comprehensive error diagnosis and troubleshooting

MCP Features

📋 Resources: Translation capability listings and PDF file information
🎯 Tools: Translation, PDF analysis, and tool status checking
💬 Prompts: Role definitions, path guidance, options explanation, and error troubleshooting
🔒 Security: Safe path validation with system directory protection

🚀 Quick Start

Installation

From MCP Registry (Recommended)

This server is available in the Model Context Protocol Registry. Install it using your MCP client.

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

Using uvx

uvx huoshui-pdf-translator

Claude Desktop Setup

Add this to your Claude Desktop MCP configuration:

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

Alternative Installation Methods

Via pipx:

pipx install huoshui-pdf-translator

Via UV tools:

uv tool install huoshui-pdf-translator

Claude Desktop config for UV tools:

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

📖 Usage

First-Time Setup

Warm up (downloads fonts/models): Use warm_up_translator tool
Check status: Use check_translation_tool tool
Translate: Use translate_pdf tool with your PDF path

MCP Tools

`translate_pdf`

Translates PDF documents while preserving mathematical formulas and layout.

# 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`

Retrieves detailed information about a PDF file.

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

`warm_up_translator`

Downloads required assets and models. Run this first to avoid timeouts.

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

`check_translation_tool`

Verifies PDFMathTranslate-next installation and status.

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

MCP Prompts

role_and_rules: Core identity and operational rules
explain_pdf_paths: Help with file path specifications
explain_translation_options: Available options and best practices
troubleshoot_translation_error: Error diagnosis and solutions
explain_translation_result: Result explanation and next steps

File Path Examples

The assistant supports flexible path specifications:

# 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

🎯 Translation Workflow

Install: uvx huoshui-pdf-translator
Setup Claude Desktop: Add MCP configuration
Warm up: Run warm_up_translator tool (first time only)
Translate: Use translate_pdf with your PDF path
Review: Two files created (dual-language and Chinese-only)

⚡ Performance

First translation: 2-5 minutes (downloads fonts/models)
Subsequent translations: 30-60 seconds
File size limit: 200MB maximum
Cache size: ~50MB for fonts and models

🔍 Troubleshooting

Common Issues

Translation Tool Not Available

The tool automatically installs pdf2zh-next when needed. If issues occur:

# Check status
# Use check_translation_tool in Claude Desktop

# Manual install if needed
pip install pdf2zh-next

First Translation Timeout

# Run warmup first
# Use warm_up_translator tool in Claude Desktop

PDF File Not Found

Verify file path is correct
Use absolute paths for clarity
Check file hasn't been moved or deleted

Network Issues

Ensure internet connection (required for first-time font downloads)
Check firewall settings

Error Diagnosis

The assistant provides intelligent error diagnosis with specific solutions for:

File not found errors
Invalid PDF files
Translation tool issues
Network connectivity problems
File size limitations

🛠️ Development

For Developers

Install from source:

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

Build and publish:

uv build
uv run twine upload dist/*

Project Structure

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

🔄 Updates

Update to latest version:

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

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

📄 License

This project is licensed under the Apache-2.0 License. See the LICENSE file for details.

🙏 Acknowledgments

PDFMathTranslate-next: Core translation engine
FastMCP: Framework for intelligent assistant capabilities
Anthropic: MCP protocol and ecosystem
UV & PyPI: Modern Python packaging and distribution

huoshui-pdf-translator

Documentation