huoshui-pdf-translator 0.1.0

AI-powered PDF translation assistant using PDFMathTranslate-next, specialized for academic papers with mathematical formulas

Huoshui PDF Translator

Version: 0.1.0
Powered by: FastMCP & PDFMathTranslate-next

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

🔧 Prerequisites

Required Software

1. Python 3.12+: Modern Python with async support
2. PDFMathTranslate-next: The core translation engine
3. FastMCP: Framework for intelligent assistant capabilities

Installation Commands

# Install PDFMathTranslate-next
pip install pdf-math-translate-next

# Verify installation
pmt --version

# Install project dependencies
uv sync

🚀 Installation

Using UV (Recommended)

# Clone the repository
git clone https://github.com/your-username/huoshui-pdf-translator.git
cd huoshui-pdf-translator

# Install dependencies with uv
uv sync

# Run the server
uv run python main.py

Using Traditional pip

# Clone and setup
git clone https://github.com/your-username/huoshui-pdf-translator.git
cd huoshui-pdf-translator

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run the server
python main.py

📖 Usage

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

check_translation_tool

Verifies PDFMathTranslate-next installation and status.

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

MCP Resources

translation_capability_list

Lists all supported translation capabilities and methods.

MCP Prompts

role_and_rules

Core identity and operational rules for the PDF translation assistant.

explain_pdf_paths

Help users understand how to specify PDF file paths correctly.

explain_translation_options

Explain available translation options and best practices.

troubleshoot_translation_error

Provide helpful guidance for common translation errors.

explain_translation_result

Explain translation results and provide 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. Specify PDF Path: Use any supported path format
2. Automatic Validation: File existence and format verification
3. Progress Tracking: Real-time updates during translation
4. Quality Assurance: Output file verification
5. Result Reporting: Detailed success information with next steps

🔍 Troubleshooting

Common Issues

Translation Tool Not Found

# Check if pmt is installed
pmt --version

# Install if missing
pip install pdf-math-translate-next

PDF File Not Found

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

Translation Fails

• Ensure PDF contains selectable text (not scanned images)
• Check internet connection (required for translation)
• Try with a simpler PDF first

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

Project Structure

huoshui-pdf-translator/
├── main.py              # FastMCP server with tools, prompts, and resources
├── pyproject.toml       # Project configuration and dependencies
├── manifest.json        # MCP manifest
├── README.md           # This file
└── uv.lock            # Dependency lock file

Testing

# Run the server directly
uv run python main.py

# Check tool status
# Use MCP client to call check_translation_tool

# Test with sample PDF
# Use MCP client to call translate_pdf with test file

Development Dependencies

# Install development tools
uv sync --group dev

# Format code
black main.py

# Lint code
ruff check main.py

🤝 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