Skip to main content
Glama
huoshui-pdf-translator

huoshui-pdf-translator

by huoshuiai42

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

Related MCP server: PDF2ZH MCP Server

๐Ÿš€ Quick Start

Installation

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

Available Tools

4 tools
check_translation_toolA

Checks if the PDFMathTranslate-next tool is properly installed and available.

Returns: Dictionary with status information about the translation tool

Inputs: no named parameters. Returns: object

pdf_getA

Retrieves detailed information about a PDF file.

Args: path: PDF file path (absolute or relative to home directory)

Returns: PDF resource with detailed information

Inputs: path (required). Returns: PDF file resource representation

translate_pdfA

Translates a PDF document using PDFMathTranslate-next. Preserves mathematical formulas and layout.

Args: pdf_path: PDF file path (absolute or relative to home directory) output_path: Optional custom output path for the translated PDF

Returns: Dictionary with paths to translated files (dual and mono versions)

Inputs: pdf_path (required), output_path. Returns: object

warm_up_translatorA

Warm up the PDF translator by downloading required assets and models. Run this first to avoid timeouts during actual translation.

Returns: Dictionary with warmup status information

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    A4.1/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a distinct purpose: pdf_get retrieves PDF info, warm_up_translator prepares the model, translate_pdf performs the translation, and check_translation_tool verifies installation. There is no overlap or ambiguity between them.

    Naming Consistency4/5

    Three tools follow a clear verb_noun pattern (warm_up_translator, translate_pdf, check_translation_tool), but pdf_get reverses this to noun_verb, creating a minor inconsistency. The naming is otherwise clear and readable.

    Tool Count5/5

    With 4 tools, the server is well-scoped for its purpose of PDF translation. Each tool covers a necessary step in the workflow, and the count is appropriate.

    Completeness5/5

    The toolset covers the complete workflow: checking installation, warming up models, translating PDFs, and retrieving PDF details. There are no obvious gaps in the provided functionality.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers