{
  "markdown": "# 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## 🌟 Features\n\n### Core Translation Capabilities\n\n- **📚 Academic Papers**: Excellent handling of mathematical formulas and equations\n- **🔬 Technical Documents**: Preserves formatting and technical terminology\n- **🌐 Multi-language Support**: Auto-detection with Chinese ↔ English specialization\n- **🎨 Layout Preservation**: Maintains original PDF structure and formatting\n\n### Smart Assistant Features\n\n- **🧠 Context-Aware Prompts**: Multiple specialized prompts for different scenarios\n- **🛠️ Tool Status Checking**: Verify translation tool installation and availability\n- **📊 PDF Analysis**: Get detailed information about PDF files before translation\n- **🔍 Flexible Path Handling**: Support for both absolute and relative file paths\n- **⚡ Progress Reporting**: Real-time progress updates during translation\n- **🚨 Intelligent Error Handling**: Comprehensive error diagnosis and troubleshooting\n\n### MCP Features\n\n- **📋 Resources**: Translation capability listings and PDF file information\n- **🎯 Tools**: Translation, PDF analysis, and tool status checking\n- **💬 Prompts**: Role definitions, path guidance, options explanation, and error troubleshooting\n- **🔒 Security**: Safe path validation with system directory protection\n\n## 🚀 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## 📖 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## 🎯 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## ⚡ 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## 🔍 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## 🛠️ 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├── huoshui_pdf_translator/\n│   ├── __init__.py      # Package metadata\n│   └── main.py         # FastMCP server implementation\n├── pyproject.toml      # Package configuration\n├── README.md          # This file\n└── LICENSE           # Apache-2.0 license\n```\n\n## 🔄 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## 🤝 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## 📄 License\n\nThis project is licensed under the Apache-2.0 License. See the LICENSE file for details.\n\n## 🙏 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",
  "bytes": 7024,
  "sha": "c30c4e7553ac1d485c8430fa6bbd2340e056b7ea440fb814d620e5115ac562b7",
  "repo_slug": "huoshuiai42/huoshui-pdf-translator",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_huoshuiai42_huoshui_pdf_transl_f1f65c9b/readme"
}