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

1. Warm up (downloads fonts/models): Use warm_up_translator tool
2. Check status: Use check_translation_tool tool
3. 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

1. Install: uvx huoshui-pdf-translator
2. Setup Claude Desktop: Add MCP configuration
3. Warm up: Run warm_up_translator tool (first time only)
4. Translate: Use translate_pdf with your PDF path
5. 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:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. 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