huoshui-pdf-translator

Huoshui PDF Translator

版本： 0.1.0
由以下项目提供支持： FastMCP 和 PDFMathTranslate-next
PyPI 软件包： huoshui-pdf-translator

一款智能 PDF 翻译助手，专为包含数学公式的学术论文打造。它基于 FastMCP 框架构建，并由 PDFMathTranslate-next 提供支持，可提供全面的翻译能力和上下文感知辅助。

🌟 功能

核心翻译能力

• 📚 学术论文：擅长处理数学公式和方程
• 🔬 技术文档：保留格式和技术术语
• 🌐 多语言支持：自动检测，专门支持中文 ↔ 英文
• 🎨 保留版式：保留原始 PDF 结构和格式

智能助手功能

• 🧠 上下文感知提示词：针对不同场景提供多种专用提示词
• 🛠️ 工具状态检查：验证翻译工具是否已安装且可用
• 📊 PDF 分析：在翻译前获取 PDF 文件的详细信息
• 🔍 灵活的路径处理：支持绝对路径和相对路径
• ⚡ 进度报告：翻译过程中实时更新进度
• 🚨 智能错误处理：全面诊断错误并提供故障排除方法

MCP 功能

• 📋 资源：翻译能力列表和 PDF 文件信息
• 🎯 工具：翻译、PDF 分析和工具状态检查
• 💬 提示词：角色定义、路径指导、选项说明和错误排查
• 🔒 安全性：安全的路径验证，并保护系统目录

🚀 快速开始

安装

从 MCP Registry 安装（推荐）

此服务已发布在 Model Context Protocol Registry 中。请使用你的 MCP 客户端安装。

mcp-name: io.github.huoshuiai42/huoshui-pdf-translator

使用 uvx

uvx huoshui-pdf-translator

Claude Desktop 配置

将以下内容添加到 Claude Desktop 的 MCP 配置中：

{
  "mcpServers": {
    "huoshui-pdf-translator": {
      "command": "uvx",
      "args": ["huoshui-pdf-translator"]
    }
  }
}

其他安装方式

通过 pipx：

pipx install huoshui-pdf-translator

通过 UV tools：

uv tool install huoshui-pdf-translator

UV tools 的 Claude Desktop 配置：

{
  "mcpServers": {
    "huoshui-pdf-translator": {
      "command": "uv",
      "args": ["tool", "run", "huoshui-pdf-translator"]
    }
  }
}

📖 使用方法

首次设置

1. 预热（下载字体／模型）：使用 warm_up_translator 工具
2. 检查状态：使用 check_translation_tool 工具
3. 翻译：使用 translate_pdf 工具并提供 PDF 路径

MCP 工具

translate_pdf

翻译 PDF 文档，同时保留数学公式和版式。

# 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

获取 PDF 文件的详细信息。

pdf_info = pdf_get(path="Desktop/document.pdf")
# Returns: PDFResource with path, size_bytes, page_count

warm_up_translator

下载所需的资源和模型。请先运行此工具，以避免超时。

warm_up_translator()
# Downloads fonts and models (~50MB) for faster subsequent translations

check_translation_tool

验证 PDFMathTranslate-next 是否已安装及其状态。

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

MCP 提示词

• role_and_rules：核心身份和操作规则
• explain_pdf_paths：获取文件路径指定方面的帮助
• explain_translation_options：可用选项和最佳实践
• troubleshoot_translation_error：错误诊断和解决方案
• explain_translation_result：结果说明和后续步骤

文件路径示例

助手支持灵活指定路径：

# 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

🎯 翻译工作流

1. 安装：uvx huoshui-pdf-translator
2. 配置 Claude Desktop：添加 MCP 配置
3. 预热：运行 warm_up_translator 工具（仅首次需要）
4. 翻译：使用 translate_pdf 并提供 PDF 路径
5. 检查：生成两个文件（双语版和纯中文版）

⚡ 性能

• 首次翻译：2-5 分钟（下载字体／模型）
• 后续翻译：30-60 秒
• 文件大小上限：最大 200MB
• 缓存大小：字体和模型约占 50MB

🔍 故障排除

常见问题

翻译工具不可用

该工具会在需要时自动安装 pdf2zh-next。如果遇到问题：

# Check status
# Use check_translation_tool in Claude Desktop

# Manual install if needed
pip install pdf2zh-next

首次翻译超时

# Run warmup first
# Use warm_up_translator tool in Claude Desktop

未找到 PDF 文件

• 验证文件路径是否正确
• 使用绝对路径以便明确指定
• 检查文件是否已移动或删除

网络问题

• 确保网络连接正常（首次下载字体时需要联网）
• 检查防火墙设置

错误诊断

助手会智能诊断错误，并提供针对性的解决方案，涵盖以下问题：

• 找不到文件
• PDF 文件无效
• 翻译工具问题
• 网络连接问题
• 文件大小限制

🛠️ 开发

面向开发者

从源代码安装：

git clone https://github.com/huoshuiai/huoshui-pdf-translator.git
cd huoshui-pdf-translator
uv sync
uv run python -m huoshui_pdf_translator.main

构建并发布：

uv build
uv run twine upload dist/*

项目结构

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

🔄 更新

更新到最新版本：

uvx install --upgrade huoshui-pdf-translator
# or
uv tool upgrade huoshui-pdf-translator

🤝 参与贡献

欢迎贡献！请：

1. Fork 仓库
2. 创建功能分支
3. 进行修改
4. 视情况添加测试
5. 提交拉取请求

📄 许可证

本项目采用 Apache-2.0 许可证。详情请参阅 LICENSE 文件。

🙏 致谢

• PDFMathTranslate-next：核心翻译引擎
• FastMCP：用于实现智能助手功能的框架
• Anthropic：MCP 协议及生态系统
• UV & PyPI：现代 Python 打包与分发