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_resul

... View full README on GitHub