# Huoshui PDF Translator
**Version:** 0.1.0
**Powered by:** FastMCP & PDFMathTranslate-next
**PyPI Package:** [`huoshui-pdf-translator`](https://pypi.org/project/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
```bash
uvx huoshui-pdf-translator
```
### Claude Desktop Setup
Add this to your Claude Desktop MCP configuration:
```json
{
"mcpServers": {
"huoshui-pdf-translator": {
"command": "uvx",
"args": ["huoshui-pdf-translator"]
}
}
}
```
### Alternative Installation Methods
**Via pipx:**
```bash
pipx install huoshui-pdf-translator
```
**Via UV tools:**
```bash
uv tool install huoshui-pdf-translator
```
**Claude Desktop config for UV tools:**
```json
{
"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.
```python
# 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.
```python
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.
```python
warm_up_translator()
# Downloads fonts and models (~50MB) for faster subsequent translations
```
#### `check_translation_tool`
Verifies PDFMathTranslate-next installation and status.
```python
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:
```bash
# 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:
```bash
# Check status
# Use check_translation_tool in Claude Desktop
# Manual install if needed
pip install pdf2zh-next
```
#### First Translation Timeout
```bash
# 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:**
```bash
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:**
```bash
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:**
```bash
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
Raw data
{
"_id": null,
"home_page": null,
"name": "huoshui-pdf-translator",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "academic, fastmcp, mathematics, mcp, pdf, translation",
"author": null,
"author_email": "Huoshui AI <contact@huoshui.ai>",
"download_url": "https://files.pythonhosted.org/packages/47/6b/e5732bd20402b61f9824178e139cd9a79814799829757ca234d27682e893/huoshui_pdf_translator-0.1.1.tar.gz",
"platform": null,
"description": "# Huoshui PDF Translator\n\n**Version:** 0.1.0 \n**Powered by:** FastMCP & PDFMathTranslate-next \n**PyPI Package:** [`huoshui-pdf-translator`](https://pypi.org/project/huoshui-pdf-translator/)\n\nAn 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.\n\n## \ud83c\udf1f Features\n\n### Core Translation Capabilities\n\n- **\ud83d\udcda Academic Papers**: Excellent handling of mathematical formulas and equations\n- **\ud83d\udd2c Technical Documents**: Preserves formatting and technical terminology\n- **\ud83c\udf10 Multi-language Support**: Auto-detection with Chinese \u2194 English specialization\n- **\ud83c\udfa8 Layout Preservation**: Maintains original PDF structure and formatting\n\n### Smart Assistant Features\n\n- **\ud83e\udde0 Context-Aware Prompts**: Multiple specialized prompts for different scenarios\n- **\ud83d\udee0\ufe0f Tool Status Checking**: Verify translation tool installation and availability\n- **\ud83d\udcca PDF Analysis**: Get detailed information about PDF files before translation\n- **\ud83d\udd0d Flexible Path Handling**: Support for both absolute and relative file paths\n- **\u26a1 Progress Reporting**: Real-time progress updates during translation\n- **\ud83d\udea8 Intelligent Error Handling**: Comprehensive error diagnosis and troubleshooting\n\n### MCP Features\n\n- **\ud83d\udccb Resources**: Translation capability listings and PDF file information\n- **\ud83c\udfaf Tools**: Translation, PDF analysis, and tool status checking\n- **\ud83d\udcac Prompts**: Role definitions, path guidance, options explanation, and error troubleshooting\n- **\ud83d\udd12 Security**: Safe path validation with system directory protection\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n#### From MCP Registry (Recommended)\n\nThis server is available in the Model Context Protocol\nRegistry. Install it using your MCP client.\n\nmcp-name: io.github.huoshuiai42/huoshui-pdf-translator\n\n#### Using uvx\n\n```bash\nuvx huoshui-pdf-translator\n```\n\n### Claude Desktop Setup\n\nAdd this to your Claude Desktop MCP configuration:\n\n```json\n{\n \"mcpServers\": {\n \"huoshui-pdf-translator\": {\n \"command\": \"uvx\",\n \"args\": [\"huoshui-pdf-translator\"]\n }\n }\n}\n```\n\n### Alternative Installation Methods\n\n**Via pipx:**\n\n```bash\npipx install huoshui-pdf-translator\n```\n\n**Via UV tools:**\n\n```bash\nuv tool install huoshui-pdf-translator\n```\n\n**Claude Desktop config for UV tools:**\n\n```json\n{\n \"mcpServers\": {\n \"huoshui-pdf-translator\": {\n \"command\": \"uv\",\n \"args\": [\"tool\", \"run\", \"huoshui-pdf-translator\"]\n }\n }\n}\n```\n\n## \ud83d\udcd6 Usage\n\n### First-Time Setup\n\n1. **Warm up** (downloads fonts/models): Use `warm_up_translator` tool\n2. **Check status**: Use `check_translation_tool` tool\n3. **Translate**: Use `translate_pdf` tool with your PDF path\n\n### MCP Tools\n\n#### `translate_pdf`\n\nTranslates PDF documents while preserving mathematical formulas and layout.\n\n```python\n# Basic usage\ntranslate_pdf(pdf_path=\"Desktop/paper.pdf\")\n\n# With custom output path\ntranslate_pdf(\n pdf_path=\"Documents/research.pdf\",\n output_path=\"Documents/translated/research_cn.pdf\"\n)\n```\n\n#### `pdf_get`\n\nRetrieves detailed information about a PDF file.\n\n```python\npdf_info = pdf_get(path=\"Desktop/document.pdf\")\n# Returns: PDFResource with path, size_bytes, page_count\n```\n\n#### `warm_up_translator`\n\nDownloads required assets and models. Run this first to avoid timeouts.\n\n```python\nwarm_up_translator()\n# Downloads fonts and models (~50MB) for faster subsequent translations\n```\n\n#### `check_translation_tool`\n\nVerifies PDFMathTranslate-next installation and status.\n\n```python\nstatus = check_translation_tool()\n# Returns: status, version, message\n```\n\n### MCP Prompts\n\n- **`role_and_rules`**: Core identity and operational rules\n- **`explain_pdf_paths`**: Help with file path specifications\n- **`explain_translation_options`**: Available options and best practices\n- **`troubleshoot_translation_error`**: Error diagnosis and solutions\n- **`explain_translation_result`**: Result explanation and next steps\n\n### File Path Examples\n\nThe assistant supports flexible path specifications:\n\n```bash\n# Absolute paths\n/Users/john/Desktop/research.pdf\nC:\\Users\\John\\Documents\\paper.pdf\n\n# Relative to home directory\nDesktop/research.pdf\nDocuments/papers/study.pdf\n\n# Simple filenames (assumes home directory)\npaper.pdf\n```\n\n## \ud83c\udfaf Translation Workflow\n\n1. **Install**: `uvx huoshui-pdf-translator`\n2. **Setup Claude Desktop**: Add MCP configuration\n3. **Warm up**: Run `warm_up_translator` tool (first time only)\n4. **Translate**: Use `translate_pdf` with your PDF path\n5. **Review**: Two files created (dual-language and Chinese-only)\n\n## \u26a1 Performance\n\n- **First translation**: 2-5 minutes (downloads fonts/models)\n- **Subsequent translations**: 30-60 seconds\n- **File size limit**: 200MB maximum\n- **Cache size**: ~50MB for fonts and models\n\n## \ud83d\udd0d Troubleshooting\n\n### Common Issues\n\n#### Translation Tool Not Available\n\nThe tool automatically installs `pdf2zh-next` when needed. If issues occur:\n\n```bash\n# Check status\n# Use check_translation_tool in Claude Desktop\n\n# Manual install if needed\npip install pdf2zh-next\n```\n\n#### First Translation Timeout\n\n```bash\n# Run warmup first\n# Use warm_up_translator tool in Claude Desktop\n```\n\n#### PDF File Not Found\n\n- Verify file path is correct\n- Use absolute paths for clarity\n- Check file hasn't been moved or deleted\n\n#### Network Issues\n\n- Ensure internet connection (required for first-time font downloads)\n- Check firewall settings\n\n### Error Diagnosis\n\nThe assistant provides intelligent error diagnosis with specific solutions for:\n\n- File not found errors\n- Invalid PDF files\n- Translation tool issues\n- Network connectivity problems\n- File size limitations\n\n## \ud83d\udee0\ufe0f Development\n\n### For Developers\n\n**Install from source:**\n\n```bash\ngit clone https://github.com/huoshuiai/huoshui-pdf-translator.git\ncd huoshui-pdf-translator\nuv sync\nuv run python -m huoshui_pdf_translator.main\n```\n\n**Build and publish:**\n\n```bash\nuv build\nuv run twine upload dist/*\n```\n\n### Project Structure\n\n```\nhuoshui-pdf-translator/\n\u251c\u2500\u2500 huoshui_pdf_translator/\n\u2502 \u251c\u2500\u2500 __init__.py # Package metadata\n\u2502 \u2514\u2500\u2500 main.py # FastMCP server implementation\n\u251c\u2500\u2500 pyproject.toml # Package configuration\n\u251c\u2500\u2500 README.md # This file\n\u2514\u2500\u2500 LICENSE # Apache-2.0 license\n```\n\n## \ud83d\udd04 Updates\n\n**Update to latest version:**\n\n```bash\nuvx install --upgrade huoshui-pdf-translator\n# or\nuv tool upgrade huoshui-pdf-translator\n```\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the Apache-2.0 License. See the LICENSE file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- **PDFMathTranslate-next**: Core translation engine\n- **FastMCP**: Framework for intelligent assistant capabilities\n- **Anthropic**: MCP protocol and ecosystem\n- **UV & PyPI**: Modern Python packaging and distribution\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "AI-powered PDF translation assistant using PDFMathTranslate-next, specialized for academic papers with mathematical formulas",
"version": "0.1.1",
"project_urls": {
"Bug Reports": "https://github.com/huoshuiai/huoshui-pdf-translator/issues",
"Documentation": "https://github.com/huoshuiai/huoshui-pdf-translator#readme",
"Homepage": "https://github.com/huoshuiai/huoshui-pdf-translator",
"Source": "https://github.com/huoshuiai/huoshui-pdf-translator"
},
"split_keywords": [
"academic",
" fastmcp",
" mathematics",
" mcp",
" pdf",
" translation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d1758585ed7d2b21a30abcc02e68b4091f3ba8430b1697c6f415a70aeb371b43",
"md5": "e6d86726894474f767bf3037de825cdc",
"sha256": "b2af0505ad2c535190e11e4480fd50d04173a2d9de0736c56ff1967f4189de45"
},
"downloads": -1,
"filename": "huoshui_pdf_translator-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e6d86726894474f767bf3037de825cdc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 16450,
"upload_time": "2025-09-10T01:31:20",
"upload_time_iso_8601": "2025-09-10T01:31:20.154242Z",
"url": "https://files.pythonhosted.org/packages/d1/75/8585ed7d2b21a30abcc02e68b4091f3ba8430b1697c6f415a70aeb371b43/huoshui_pdf_translator-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "476be5732bd20402b61f9824178e139cd9a79814799829757ca234d27682e893",
"md5": "8c6e2dee9e26dabbf4043046cf3aebed",
"sha256": "a80fa3a9dae7f641362a25d025a157ff0a527b3583d086175df33b5f5c4ca3f2"
},
"downloads": -1,
"filename": "huoshui_pdf_translator-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "8c6e2dee9e26dabbf4043046cf3aebed",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 15054,
"upload_time": "2025-09-10T01:31:21",
"upload_time_iso_8601": "2025-09-10T01:31:21.613694Z",
"url": "https://files.pythonhosted.org/packages/47/6b/e5732bd20402b61f9824178e139cd9a79814799829757ca234d27682e893/huoshui_pdf_translator-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-10 01:31:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "huoshuiai",
"github_project": "huoshui-pdf-translator",
"github_not_found": true,
"lcname": "huoshui-pdf-translator"
}
JSON
