使用说明
PDF下载器MCP
一个强大的模型上下文协议（MCP）服务器，用于下载具有高级重试逻辑、错误处理和部分下载恢复的PDF文件。
特性
？核心功能
- 单用途工具：一个工具(
download_pdf)这使得PDF下载非常好 - 稳健的重试逻辑：具有抖动的指数级回退，可优雅地处理网络问题
- 部分下载恢复：使用HTTP范围请求恢复中断的下载
- 全面的错误处理：对错误进行智能分类，以确定重试策略
？高级重试策略
指数退避
- 第一次重试：等待5秒
- 第二次重试：等待10秒
- 第三次重试：等待20秒
- 通过快速重试尝试防止服务器不堪重负
智能错误处理
- 网络超时：重试，超时时间更长
- HTTP 429（速率受限）：等待更长时间，遵守费率限制
- HTTP 503（服务器不可用）：延迟后重试
- HTTP 404/403：不要重试，立即返回错误
- SSL/证书错误：使用不同的SSL设置重试
部分下载恢复
- 使用HTTP范围请求恢复中断的下载
- 检查服务器是否支持
Accept-Ranges: bytes - 从上次下载的字节位置恢复
- 如果恢复失败，则回退到完整下载
下载验证
- 验证文件大小是否匹配
Content-Length头球 - 基本PDF标题验证（从开始
%PDF) - 全面的PDF结构验证
- 如果文件出现损坏，请重试
后备策略
- 如果被阻止，请尝试其他用户代理字符串
- 尝试使用/不使用SSL验证
- 针对问题服务器的多种连接策略
安装
来源
git clone https://github.com/baldawsari/pdf-downloader-mcp.git
cd pdf-downloader-mcp
pip install -e .
开发安装
git clone https://github.com/baldawsari/pdf-downloader-mcp.git
cd pdf-downloader-mcp
pip install -e ".[dev]"
用法
作为MCP服务器
- 运行服务器:
pdf-downloader-mcp
- 或者作为Python模块运行:
python -m pdf_downloader_mcp
刀具参数
这 download_pdf 工具接受以下参数：
| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
url |
字符串 | ？ | - | 直接PDF URL |
destination_path |
字符串 | ？ | - | 本地文件夹路径 |
filename |
字符串 | ？ | URL文件名 | 自定义文件名 |
max_retries |
整数 | ？ | 3 | 重试次数（0-10） |
retry_delay |
号码 | ？ | 5.0 | 重试之间的基本延迟（0.1-60.0s） |
timeout |
号码 | ？ | 30.0 | 请求超时（5.0-300.0秒） |
示例用法
{
"tool": "download_pdf",
"arguments": {
"url": "https://example.com/document.pdf",
"destination_path": "/home/user/downloads",
"filename": "important_document.pdf",
"max_retries": 5,
"retry_delay": 10.0,
"timeout": 60.0
}
}
响应格式
成功响应
{
"success": true,
"local_path": "/home/user/downloads/important_document.pdf",
"file_size": 1234567,
"attempts_used": 2,
"max_retries": 5,
"download_time": 15.3,
"total_time": 25.8,
"average_speed": "4.85",
"resumed": false,
"bytes_downloaded": 1234567,
"error_message": null
}
错误响应
{
"success": false,
"local_path": null,
"file_size": 0,
"attempts_used": 6,
"max_retries": 5,
"download_time": 0,
"total_time": 45.2,
"average_speed": "0.00",
"resumed": false,
"bytes_downloaded": 0,
"error_message": "Failed after 6 attempts. Last error: HTTP 404: Not Found"
}
错误类别
下载器将错误分为三类，以获得最佳的重试行为：
重试错误
- 网络超时
- 服务器错误（5xx）
- 费率限制（429）
- 连接错误
- SSL错误
NO_RETRY错误
- 找不到文件（404）
- 拒绝访问（403）
- 错误请求（400）
- 需要身份验证（401）
PARTIAL_RETRY错误
- 下载不完整
- 检测到损坏
- 验证失败
配置
MCP服务器配置
添加到MCP配置文件中：
{
"mcpServers": {
"pdf-downloader": {
"command": "pdf-downloader-mcp",
"args": []
}
}
}
环境变量
| 变量 | 描述 | 默认值 |
|---|---|---|
PDF_DOWNLOADER_LOG_LEVEL |
日志记录级别（调试、信息、警告、错误） | 信息 |
PDF_DOWNLOADER_MAX_CONCURRENT |
最大并发下载量 | 5 |
发展
运行测试
pytest
代码格式化
black src/ tests/
isort src/ tests/
类型检查
mypy src/
代码检查
flake8 src/ tests/
建筑
src/pdf_downloader_mcp/
??? __init__.py # Package initialization
??? __main__.py # CLI entry point
??? server.py # MCP server implementation
??? downloader.py # Core PDF downloader
??? exceptions.py # Custom exception classes
??? validators.py # PDF validation logic
??? utils.py # Utility functions
贡献
- 分叉存储库
- 创建要素分支(
git checkout -b feature/amazing-feature) - 提交您的更改(
git commit -m 'Add amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
致谢
- 与 模型上下文协议（MCP）
- 用途 意图tp 用于健壮的HTTP操作
- 灵感来自企业级下载管理器
用？？用于可靠的PDF下载
