File Organizer MCP

🚀 文件整理器MCP服务器

文件整理器MCP服务器是一个强大且安全加固的模型上下文协议（MCP）服务器，用于智能文件整理。它提供了高级的原子工具，封装了复杂的文件操作，能有效解决传统文件系统MCP服务器在AI文件整理时面临的复杂性、令牌效率低、易出错和延迟高等问题。

🚀 快速开始

一键设置

运行以下命令启动交互式设置：

npx file-organizer-mcp --setup

设置向导将执行以下操作：

• 自动检测已安装的AI客户端（如Claude Desktop、Cursor、Windsurf、Cline等）。
• 自动配置客户端。
• 引导你完成文件夹选择和偏好设置。

要求

• Node.js 18+

常用命令

配置完成后，你可以向AI提出以下请求：

• "整理我的下载文件夹"
• "查找我的文档中的重复文件"
• "显示我的最大文件"

安装方法

✨ 主要特性

• 分类：智能分类到12种以上的类别。
• 调度：基于Cron的自动整理。
• 重复检测：使用内容哈希（SHA - 256）进行精确识别。
• 元数据提取：提取照片的EXIF数据、音乐的ID3标签以及文档主题。
• 智能整理：统一策略检测混合文件类型。
• 安全操作：支持干运行模式、回滚操作和原子移动。
• 安全防护：缓解TOCTOU攻击、防止路径遍历和清理元数据。
• 多平台支持：原生支持Windows、macOS和Linux。

📦 安装指南

一键设置

运行以下命令启动交互式设置：

npx file-organizer-mcp --setup

安装方法

💻 使用示例

基础用法

以下是使用npx进行一键设置的示例：

npx file-organizer-mcp --setup

高级用法

智能下载文件夹清理

1. **扫描** -> 查看文件分布和空间使用情况。
2. **分析** -> 识别重复文件和过时文件。
3. **执行** -> 原子化整理到分类文件夹。
3. 找到重复文件 → 找到45个重复文件组，浪费2.3 GB空间
4. 显示最大文件 → old_backup.zip: 5.2 GB
5. 预览整理结果 → 显示计划的移动和冲突
6. 请求确认
7. 整理文件 → ✅ 整理1,247个文件到8个分类文件夹

结果：清理并整理好的下载文件夹，重复文件已识别

项目文件夹整理

用户: "Claude, 整理我在~/myproject的项目文件夹"

Claude:
1. 扫描项目 → 多个子目录中共有423个文件
2. 识别文件类型 → 代码（289个）、资产（87个）、文档（47个）
3. 建议整理方式 → 保留src/结构，整理根目录文件
4. 预览更改 → 显示（47）个待整理项目
5. 执行 → 将配置文件、自述文件、截图移动到合适的文件夹

结果：干净的项目结构，文档和资产已整理

重复文件管理

用户: "Claude, 查找并分析C:/Users/[YOUR_USERNAME]/Documents中的重复文件"

Claude:
1. 扫描重复文件 → 找到23个重复文件组
2. 分析每个组 → 根据位置、文件名质量、文件年龄对文件进行评分
3. 建议保留的文件 → 保留 "/Documents/Important/file.pdf"
4. 建议删除的文件 → 删除 "/Downloads/file (1).pdf"
5. 显示浪费的空间 → 总共可回收1.8 GB空间

用户可以手动删除或要求Claude整理以移除重复文件

大文件发现

用户: "Claude, 显示我下载文件夹中占用空间最大的20个文件"

Claude:
1. 分析目录大小 → 总计：45.2 GB
2. 找到最大的文件：
   - old_backup_2023.zip: 12.3 GB（2年前）
   - movie_collection.mkv: 8.7 GB
   - presentation_final.pptx: 890 MB
3. 建议清理 → 存档或删除旧备份
4. 显示大文件中的重复文件 → 一些大文件有副本

结果：清晰了解空间使用情况，并提供可操作的建议

音乐整理

用户: "Claude, 整理我在C:/Users/[YOUR_USERNAME]/Music的音乐文件夹"

Claude:
1. 扫描目录 → 显示456个音乐文件，2.3 GB
2. 提取元数据 → 读取ID3标签以获取艺术家、专辑和标题信息
3. 预览整理结果 → 显示计划的结构：艺术家/专辑/标题.mp3
4. 请求确认
5. 整理文件 → ✅ 整理456个音乐文件到32个艺术家文件夹

结果：使用ID3元数据按艺术家/专辑/标题结构整理音乐文件

整理前:
├── Downloads/
│   ├── song1.mp3
│   ├── track02.mp3
│   └── music_file.mp3

整理后:
├── Music/
│   ├── Coldplay/
│   │   ├── A Rush of Blood to the Head/
│   │   │   ├── Clocks.mp3
│   │   │   └── The Scientist.mp3
│   └── Radiohead/
│       ├── OK Computer/
│       │   ├── Paranoid Android.mp3
│       │   └── Karma Police.mp3

照片整理

用户: "Claude, 整理我在C:/Users/[YOUR_USERNAME]/Pictures的照片"

Claude:
1. 扫描目录 → 显示1,234张照片，4.5 GB
2. 提取EXIF元数据 → 从EXIF标签中读取拍摄日期
3. 预览整理结果 → 显示计划的结构：YYYY/MM/DD
4. 请求确认
5. 整理文件 → ✅ 整理1,234张照片到按日期分类的文件夹

结果：使用EXIF元数据按拍摄日期（YYYY/MM/DD）整理照片

整理前:
├── Pictures/
│   ├── IMG_001.jpg
│   ├── photo123.png
│   └── DSC_4567.raw

整理后:
├── Pictures/
│   ├── 2023/
│   │   ├── 12/
│   │   │   ├── 25/
│   │   │   │   ├── IMG_001.jpg
│   │   │   └── 31/
│   │   │       └── photo123.png
│   └── 2024/
│       ├── 01/
│       │   └── 15/
│       │       └── DSC_4567.raw

安全筛查与元数据

用户: "Claude, 扫描我的文档文件夹以查找安全问题"

Claude:
1. 扫描目录 → 显示567个文档，1.2 GB
2. 提取元数据 → 读取文件元数据和内容签名
3. 执行安全筛查 →
   - 发现3个包含敏感元数据的文件
   - 发现1个包含潜在恶意内容的文件
4. 显示详细报告 →
   - "report.pdf" 包含EXIF GPS坐标
   - "resume.docx" 包含个人身份信息
5. 建议操作 → 编辑元数据、隔离文件

结果：基于元数据的全面安全扫描，检测潜在威胁

设置自动整理

用户: "Claude, 每天早上9点自动整理我的下载文件夹"

Claude:
1. 设置监控目录 →
   file_organizer_watch_directory({
     directory: "/Users/john/Downloads",
     schedule: "0 9 * * *",
     min_file_age_minutes: 5
   })
2. 确认设置 → "下载文件夹将在每天上午9:00整理"
3. 显示当前监控目录 → 列出所有监控的目录

用户: "也每小时监控我的桌面文件夹"

Claude:
4. 添加第二个监控目录 →
   file_organizer_watch_directory({
     directory: "/Users/john/Desktop",
     schedule: "0 * * * *",
     max_files_per_run: 50
   })

结果：通过智能调度实现自动后台整理

📚 详细文档

工具参考

核心工具

• file_organizer_scan_directory：扫描目录并提供详细的文件信息。
  • directory（必需）：目录的完整路径。
  • include_subdirs（可选）：递归扫描。
• file_organizer_read_file：安全读取文件，具有8层验证。
  • path（必需）：绝对路径。
  • encoding（可选）：utf - 8、base64或二进制。
• file_organizer_organize_smart：统一工具，自动处理音乐、照片和文档，为每种类型使用最佳策略。
• file_organizer_batch_rename：使用模式、正则表达式或编号重命名多个文件。
• file_organizer_undo_last_operation：撤销上一次整理操作。

文件类别

🔧 技术细节

技术栈

核心依赖

• MCP服务器：@modelcontextprotocol/sdk - 模型上下文协议实现
• 安全防护：Zod模式验证、路径遍历保护
• 元数据提取：
  • music - metadata - 提取音频文件的ID3标签
  • exif - parser - 提取图像的EXIF元数据
• 调度管理：node - cron - 基于Cron的调度管理
• 交互式UI：Ink + React - 终端用户界面
• 提示工具：@inquirer/prompts - 交互式CLI提示
• 实用工具：Chalk（颜色）、minimatch（通配符模式）

安全特性

• 8层路径验证：阻止遍历攻击和URI编码技巧
• 敏感文件检测：阻止访问.env、.ssh、密码、密钥等文件
• 速率限制：每分钟120个请求，每小时2000个请求
• TOCTOU保护：基于文件描述符的操作
• 元数据安全：编辑敏感元数据（GPS、个人信息）

性能优化

• 元数据缓存：7天缓存，使用文件哈希验证
• 并行处理：可配置并发处理批量操作
• 流处理：处理大文件时无内存问题
• 内存限制：防止过度消耗资源

架构

先筛选后丰富架构

文件整理器MCP服务器实现了“先筛选后丰富”的架构，用于安全高效的文件操作：

┌───────────────────────────────────────────────────────────┐
│                     MCP Client (LLM)                      │
└─────────────────────────┬─────────────────────────────────┘
                           │ JSON - RPC 2.0
┌─────────────────────────▼─────────────────────────────────┐
│                    MCP Server Layer                        │
│  (server.ts - Protocol Handler)                            │
└─────────────────────────┬─────────────────────────────────┘
                           │
┌─────────────────────────▼─────────────────────────────────┐
│                     Security Screening                     │
│  - Path validation & containment checks                    │
│  - Sensitive file detection                                │
│  - Rate limiting                                           │
└─────────────────────────┬─────────────────────────────────┘
                           │
┌─────────────────────────▼─────────────────────────────────┐
│                   Metadata Enrichment                      │
│  - EXIF extraction for images (camera, date, GPS)          │
│  - ID3 extraction for audio (artist, album, title)         │
│  - Document metadata (PDF, DOCX properties)                │
└─────────────────────────┬─────────────────────────────────┘
                           │
┌─────────────────────────▼─────────────────────────────────┐
│                    Services Layer                           │
│  ┌────────────┬──────────────┬─────────────┬──────────┐    │
│  │ Path       │ Organizer    │ Hash        │ Scanner  │    │
│  │ Validator  │ Service      │ Calculator  │ Service  │    │
│  └────────────┴──────────────┴─────────────┴──────────┘    │
└─────────────────────────┬─────────────────────────────────┘
                           │
┌─────────────────────────▼─────────────────────────────────┐
│                    File System                               │
└───────────────────────────────────────────────────────────┘

关键架构原则

1. 安全优先：在进行任何文件操作之前进行多层验证。
2. 元数据驱动：使用提取的元数据进行内容感知整理。
3. 缓存策略：7天元数据缓存，使用文件哈希验证。
4. 批量处理：可配置并发处理大型操作。
5. 原子操作：支持回滚的安全文件操作。

API文档

新的元数据API

• file_organizer_inspect_metadata
  • 描述：从文件中提取全面的元数据，并提供隐私控制。
  • 参数：
    • file：字符串（必需） - 文件的完整路径
    • response_format：'json' | 'markdown'（可选，默认：'markdown'）
  • 返回值：
    • 对于图像：EXIF数据（相机、日期、尺寸、ISO、光圈）
    • 对于音频：ID3标签（艺术家、专辑、标题、年份、流派）
    • 对于文档：文件属性

元数据缓存系统

• 配置：

{
  "metadataCache": {
    "enabled": true,
    "maxAge": 604800000, // 7天（毫秒）
    "maxEntries": 10000,
    "cacheDir": ".cache"
  }
}

• 缓存统计：

// 获取缓存统计信息
const stats = await getCacheStats();
// {
//   totalEntries: 1500,
//   audioEntries: 800,
//   imageEntries: 700,
//   cacheSize: 256000
// }

📄 许可证

本项目采用MIT许可证，详情请参阅LICENSE文件。

📝 重要提示

⚠️ 重要提示

• 默认情况下，仅整理根目录中的文件，不包括子目录。
• 现有的分类文件夹不会被重新整理，以防止循环。

💡 使用建议

• 文件扩展名不区分大小写。
• 保留原始修改日期。
• 自动跳过以 . 开头的隐藏文件。
• 每次操作最多处理10,000个文件（安全限制）。
• 最多扫描10层目录（安全限制）。
• 支持回滚操作以撤销更改。

🤝 贡献

欢迎贡献代码！请阅读CONTRIBUTING.md了解贡献指南。

开发设置

git clone https://github.com/kridaydave/File-Organizer-MCP.git
cd File-Organizer-MCP
npm install
npm run build
npm test

报告问题

• 🚨 安全漏洞：发送邮件至technocratix902@gmail.com
• 🐛 Bug/功能请求：GitHub Issues

📚 文档

• API.md - 完整的工具参考
• ARCHITECTURE.md - 技术架构和设计模式
• CONTRIBUTING.md - 贡献指南
• MIGRATION.md - v2到v3升级指南
• CHANGELOG.md - 版本历史

🙏 致谢

• Anthropic - 提供模型上下文协议规范
• NetworkChuck - 提供启发本项目的MCP教程
• MCP社区 - 提供反馈和支持

📞 支持

• MCP注册表：查看列表
• NPM包：在NPM上查看
• 问题反馈：GitHub Issues
• MCP规范：模型上下文协议

愉快地整理文件！🎯

为MCP社区用心打造 ❤️

⬆ 返回顶部