AI导哈

下载文件夹管理工具

一款用于自动和智能管理下载文件夹的MCP服务器工具，提供文件扫描、智能分类、去重、清理等功能。

  • by tehila1985
  • Python
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 tehila1985/downloads-mcp

使用说明

下载管理员--MCP服务器

MCP服务器，用于通过Claude Desktop自动智能管理您的下载文件夹。

目录

特征

Downloads Warden提供8个工具来管理您的下载文件夹：

# 工具 说明
1 scan_downloads_tool 扫描文件夹并返回详细统计数据
2 smart_sort_files_tool 按类型对文件进行排序（文档、媒体、安装程序、代码、档案、其他）
3 sort_by_date_tool 将文件排序到年月文件夹中（YYYY-MM）
4 deduplicate_by_hash_tool 使用SHA-256删除重复文件
5 deduplicate_folders_tool 删除内容相同的文件夹
6 auto_extract_and_cleanup_tool 提取ZIP存档，然后删除
7 clear_installers_tool 删除旧的安装程序文件
8 find_large_files_tool 查找超过大小阈值的文件

建筑

该项目遵循严格的4层干净架构：

src/
├── domain/               # Domain layer — pure business logic
│   ├── config.py         # All categories, extensions and thresholds (frozen dataclasses)
│   ├── exceptions.py     # Custom exception hierarchy (WardenError → ...)
│   ├── events.py         # Observer pattern — EventBus + event dataclasses
│   ├── strategies.py     # Strategy pattern — SortStrategy ABC + StrategyFactory
│   └── models.py         # Immutable domain models (frozen dataclasses)
│
├── infrastructure/       # Infrastructure layer — all file-system I/O
│   └── file_repository.py  # BaseFileRepository ABC + LocalFileRepository
│
├── application/          # Application layer — Use Cases (orchestrators)
│   ├── base_sort_use_case.py   # Template Method — sort pipeline skeleton
│   ├── sort_use_case.py        # SmartSortUseCase + DateSortUseCase
│   ├── scan_use_case.py
│   ├── deduplicate_use_case.py
│   ├── extract_use_case.py
│   └── clean_use_case.py
│
├── container.py          # DI Container — wires all dependencies
└── server.py             # MCP interface — thin adapter only

设计原则

  • 策略模式 — ExtensionSortStrategy / DateSortStrategy 带着一个 StrategyFactory 注册表
  • 模板方法 — BaseSortUseCase 定义管道；子类只注入一个策略
  • 观察员/活动巴士 --用例发布事件；日志记录在容器中单独订阅
  • 存储库模式 — BaseFileRepository ABC允许在不改变任何业务逻辑的情况下将文件系统交换为模拟
  • 不可变性 --所有域模型和配置对象 @dataclass(frozen=True)
  • 自定义例外 — WardenError → FolderNotFoundError / HashComputationError / ExtractionError / ...
  • 冲突分解 --顺序计数器(_1 … _99) → 微秒时间戳回退→ CollisionError

安装

先决条件

  • Python 3.11或更高版本
  • 克劳德桌面版

步骤

# 1. Enter the project directory
cd downloads-warden

# 2. Create a virtual environment
python -m venv .venv

# 3. Activate the virtual environment
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # macOS / Linux

# 4. Install the project with dev dependencies
pip install -e ".[dev]"

# 5. Verify the server starts correctly
python run_server.py

Claude桌面设置

打开Claude Desktop配置文件：

%APPDATA%\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json

添加以下内容：

{
  "mcpServers": {
    "downloads-warden": {
      "command": "C:\\path\\to\\downloads-warden\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\downloads-warden\\run_server.py"]
    }
  }
}

⚠️ 替换 C:\\path\\to\\downloads-warden 使用机器上的实际路径。

重新启动Claude Desktop，然后转到“设置”→ 开发者→ 本地MCP服务器——“下载管理员”应显示为绿色✓.

MCP检验员测试

npx @modelcontextprotocol/inspector
  • 运输类型： 工作室
  • 命令： .venv\Scripts\python.exe
  • 论据： run_server.py

点击 连接 并验证所有8个工具是否出现。

运行测试

# All tests (unit + integration) with coverage
python -m pytest

# Unit tests only (no disk I/O)
python -m pytest tests/unit

# Integration tests only
python -m pytest tests/integration

预期结果： 47项通过，覆盖率92%

可用工具

工具 关键参数 默认值
scan_downloads_tool folder_path 用户下载文件夹
smart_sort_files_tool folder_path, dry_run dry_run=true
sort_by_date_tool folder_path, dry_run dry_run=true
deduplicate_by_hash_tool folder_path, dry_run dry_run=true
deduplicate_folders_tool folder_path, dry_run dry_run=true
auto_extract_and_cleanup_tool folder_path, dry_run dry_run=true
clear_installers_tool folder_path, days_old, dry_run days_old=30, dry_run=true
find_large_files_tool folder_path, min_size_mb min_size_mb=500

⚠️ 始终与 dry_run=true 第一 在任何破坏性操作之前。

故障排除

服务器在Claude Desktop中未连接

  • 验证中的路径 claude_desktop_config.json 正确且虚拟环境存在

ModuleNotFoundError: No module named 'src'

  • 确保已安装 pip install -e ".[dev]" 而且不仅仅是 pip install -r requirements.txt

工具未出现在检查器中

  • 单击“断开连接”→ 重新连接并检查服务器是否正确启动

许可证

MIT许可证

内置于❤️ 使用FastMCP

相关 MCP