火水PDF翻译器
版本： 0.1.0\ 由……提供支持/驱动 FastMCP & PDFMathTranslate-next 翻译为中文是：“快速数学内容处理（FastMCP）与PDF数学公式翻译（PDFMathTranslate-next）”\ PyPI 包： huoshui-pdf-translator
一个专注于处理包含数学公式的学术论文的智能PDF翻译助手。该助手基于FastMCP框架构建，并由PDFMathTranslate-next提供支持，具备全面的翻译能力，同时提供上下文感知辅助功能。
🌟 特点
核心翻译能力
- 📚 学术论文出色的数学公式和方程处理能力
- 🔬 技术文件保持格式和技术术语
- 🌐 多语言支持自动检测，专攻中英文对照
- 🎨 布局保持保持原始PDF的结构和格式
智能助手功能
- 🧠 上下文感知提示针对不同场景的多种专业提示
- 🛠️ 工具状态检查验证翻译工具的安装情况及可用性
- 📊 PDF 分析在翻译前获取PDF文件的详细信息
- 🔍 灵活的路径处理支持绝对路径和相对路径
- ⚡ 进度报告翻译过程中的实时进度更新
- 🚨 智能错误处理全面的错误诊断与故障排除
MCP特性
- 📋 资源翻译能力列表及PDF文件信息
- 🎯 工具翻译、PDF分析及工具状态检查
- 💬 提示/指令角色定义、路径指导、选项解释和错误排查
- 🔒 安全带系统目录保护的安全路径验证
🚀 快速入门
安装
来自MCP注册表（推荐）
此服务器在模型上下文协议中可用 注册表。使用您的MCP客户端进行安装。
mcp-name: io.github.huoshuiai42/huoshui-pdf-translator 翻译为中文是：“mcp 名称：io.github.huoshuiai42/huoshui-pdf-translator”（这里的“mcp-name”通常指的是某个配置或模块中的名称字段，但具体含义可能根据上下文有所不同，这里直接翻译为“mcp 名称”以保持原意）。不过，在实际应用中，我们可能会根据上下文简化为“名称：io.github.huoshuiai42/huoshui-pdf-translator”
使用uvx
uvx huoshui-pdf-translatorClaude 桌面版设置
将此添加到您的Claude Desktop MCP配置中：
{
"mcpServers": {
"huoshui-pdf-translator": {
"command": "uvx",
"args": ["huoshui-pdf-translator"]
}
}
}替代安装方法
通过 pipx：
pipx install huoshui-pdf-translator通过UV工具：
uv tool install huoshui-pdf-translatorUV工具的Claude Desktop配置：
{
"mcpServers": {
"huoshui-pdf-translator": {
"command": "uv",
"args": ["tool", "run", "huoshui-pdf-translator"]
}
}
}📖 使用方法
首次设置
- 热身 (下载字体/模型)：使用
warm_up_translator工具 - 检查状态使用
check_translation_tool工具 - 翻译使用
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_countwarm_up_translator
下载所需的资源和模型。请先运行此操作以避免超时。
warm_up_translator()
# Downloads fonts and models (~50MB) for faster subsequent translationscheck_translation_tool
验证PDFMathTranslate-next的安装情况及状态。
status = check_translation_tool()
# Returns: status, version, messageMCP 提示
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🎯 翻译工作流程
- 安装:
uvx huoshui-pdf-translator - 设置Claude桌面版添加MCP配置
- 热身跑
warm_up_translator工具（仅限首次使用） - 翻译使用
translate_pdf附上您的PDF文件路径 - 评论创建了两个文件（双语版和中文版）
⚡ 性能
- 首次翻译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🤝 贡献
欢迎投稿！请：
- 为仓库创建分支（或：克隆仓库）
- 创建一个特性分支
- 做出你的更改
- 如适用，请添加测试
- 提交拉取请求
📄 许可证
此项目遵循Apache-2.0许可证。详情请参阅LICENSE文件。
🙏 致谢
- PDFMathTranslate-next（可译为）：PDF数学翻译增强版/下一代PDF数学翻译工具核心翻译引擎
- FastMCP智能助手能力框架
- Anthropic（公司名，可译为“安萨里奇”或根据具体语境保留原名）MCP协议及其生态系统
- UV 和 PyPI现代Python的打包与分发