Downloads Warden MCP

📥 git 初始化

使用FastMCP和Python 3.10+进行智能下载文件夹管理的专业MCP服务器。

🎯 概述

Downloads Warden是一个模型上下文协议（MCP）服务器，它将您的下载文件夹从混乱状态转换为有组织、高效的系统。通过MCP连接到Claude，AI代理可以通过智能操作自动管理您的文件。

✨ 特性

7强大的工具

智能组织

自动将文件分类：

• 📄 文件 -PDF、DOCX、TXT、XLSX、PPTX
• 🎬 媒体 -JPG、PNG、MP4、MP3、GIF
• 🔧 安装程序 -EXE、MSI、DMG、PKG
• 💻 代码 -PY、JS、TS、HTML、CSS、JSON
• 📦 档案 -ZIP、RAR、7Z、TAR、GZ
• 📂 其他 -其他文件

📋 先决条件

• Python 3.10或更高版本
• pip（Python包安装程序）
• 支持MCP的Claude桌面

🚀 安装和设置

1.克隆/创建项目

# Navigate to your projects directory
cd ~/projects

# Create project directory
mkdir downloads-warden
cd downloads-warden

2.安装依赖项

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

## 🚀 Quick Start

### Prerequisites

- Python 3.10 or higher
- pip or uv package manager
- Claude Desktop (for testing)

### Installation

Clone or navigate to project

cd downloads-warden

Create virtual environment

python -m venv venv venv\Scripts\activate # Windows

or

source venv/bin/activate # macOS/Linux

Install dependencies

pip install -r requirements.txt

### 运行服务器

Direct run

python src/server.py

Or with uv (if installed)

uv run src/server.py

## 🧪 测试

### 单元测试

Install test dependencies

pip install pytest pytest-asyncio

Run all tests

pytest tests/ -v

Run with coverage

pytest tests/ --cov=src

**测试结果：** ✅ 13/13项测试通过

### 与MCP检查员一起

mcp-inspector python src/server.py

打开http://localhost:3000用于交互式工具测试。

## 💡 使用示例

配置后，您可以自然地与Claude聊天：

**示例1：全面分析**

> “克劳德，分析我的下载文件夹 告诉我如何节省空间”

克劳德将：

1. 跑 `scan_downloads` 获取统计数据
1. 跑 `deduplicate_by_hash` 查找重复项
1. 跑 `find_large_files` 识别太空猪
1. 提供建议

**示例2：快速清理**

> “清理我的资料夹，画画，拿出剪刀，删除重复”

克劳德将：

1. 跑 `smart_sort_files`
1. 跑 `auto_extract_and_cleanup`
1. 跑 `deduplicate_by_hash`
1. 跑 `deduplicate_folders`
1. 汇报进展

**示例3：空间管理**

> “我能节省多少空间？”

克劳德将：

1. 跑 `find_large_files`
1. 跑 `deduplicate_by_hash`
1. 跑 `clear_installers`
1. 计算潜在的节省

## 🏗 项目结构

downloads-warden/ ├── src/ │ └── server.py # Main MCP server implementation ├── .vscode/ │ └── mcp.json # MCP server configuration ├── pyproject.toml # Project metadata ├── requirements.txt # Python dependencies └── README.md # This file

## 🔧 发展

### 以开发模式运行

With virtual environment activated

python src/server.py

### 本地测试工具

Example Python script to test a tool

import asyncio from src.server import handle_scan_downloads

async def test(): result = await handle_scan_downloads(os.path.expanduser("~/Downloads")) print(result)

asyncio.run(test())

## 📝 API 参考

### 工具：scan_downloads

- **输入：** 无
- **输出：** 包含文件统计信息的报告
- **副作用：** 无（只读）

### 工具：smart_sport_files

- **输入：** 无
- **输出：** 移动文件摘要
- **副作用：** 修改文件夹结构

### 工具：重复数据删除_by_hash

- **输入：** 无
- **输出：** 已删除的重复项数量
- **副作用：** 删除文件

### 工具：重复数据删除文件夹

- **输入：** 无
- **输出：** 已删除的重复文件夹数
- **副作用：** 删除重复目录
- **说明：** 识别内容相同的文件夹，并在保留原始内容的同时删除重复项

### 工具：自动提取和清理

- **输入：** 无
- **输出：** 提取的文件数
- **副作用：** 创建目录，删除存档

### 工具：clear_installers

- **输入：** 无
- **输出：** 已删除的安装程序数量
- **副作用：** 删除旧的安装程序文件

### 工具：find_large_files

- **输入：** `min_size_mb` （数字，默认值：500）
- **输出：** 大文件列表
- **副作用：** 无（只读）

## ⚠️ 重要说明

- **备份：** 在使用清理工具之前，始终备份重要文件
- **权限：** 需要对下载文件夹进行读/写访问
- **隐私：** 所有操作都在您的计算机上本地运行
- **安全：** 删除前会验证重复文件
- **测试：** 首先对非关键文件进行测试

## 🔐 隐私和安全

- 没有数据发送到外部服务器
- 所有操作都在您的机器上本地进行
- 只有在验证后才会删除文件
- 基于哈希的重复数据删除可确保准确性

## 🐛 故障排除

### 服务器未启动

Check Python version

python --version # Should be 3.10+

Verify MCP is installed

pip list | grep mcp

Try running directly

python src/server.py

### 克劳德没有看到工具

- 重新启动克劳德桌面
- 检查claude_desktop_config.json语法
- 验证配置中的文件路径是否正确
- 检查虚拟环境是否处于活动状态

### 权限被拒绝错误

- 以适当的权限运行
- 检查文件/文件夹所有权
- 在Windows上，可能需要管理员权限

## 📚 参考文献

- [模型上下文协议文档](https://modelcontextprotocol.io)
- [Python路径库文档](https://docs.python.org/3/library/pathlib.html)
- [Python中的异步/等待](https://docs.python.org/3/library/asyncio.html)

## 📄 许可证

MIT许可证-可根据您的需求自由使用和修改

## 🤝 贡献

欢迎投稿！请随时提交拉取请求或未决问题。

______________________________________________________________________

**制作❤️ 用于随处可见的有序下载文件夹**