JinDaGe - file-organizer-mcp MCP Details

article

README

🚀 文件整理器MCP服务器

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

🚀 快速开始

一键设置

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

npx file-organizer-mcp --setup

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

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

要求

Node.js 18+

常用命令

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

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

安装方法

| 方法 | 命令 | 使用场景 | | --- | --- | --- | | npx | npx file-organizer-mcp --setup | 偶尔使用/试用 | | 全局 | npm install -g file-organizer-mcp | 常规使用/更快启动 |

✨ 主要特性

分类：智能分类到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：撤销上一次整理操作。

文件类别

| 类别 | 典型扩展名 | | --- | --- | | 可执行文件 | .exe, .msi, .bat, .sh | | 视频文件 | .mp4, .avi, .mkv, .mov | | 文档文件 | .pdf, .doc, .docx, .txt, .md | | 图像文件 | .jpg, .jpeg, .png, .gif, .webp | | 音频文件 | .mp3, .wav, .flac, .m4a | | 存档文件 | .zip, .rar, .7z, .tar.gz | | 代码文件 | .py, .js, .ts, .java, .go, .json |

🔧 技术细节

技术栈

核心依赖

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                               │
└───────────────────────────────────────────────────────────┘

关键架构原则

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

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社区用心打造 ❤️

⬆ 返回顶部

file-organizer-mcp

README

🚀 文件整理器MCP服务器

🚀 快速开始

一键设置

要求

常用命令

安装方法

✨ 主要特性

📦 安装指南

一键设置

安装方法

💻 使用示例

基础用法

高级用法

智能下载文件夹清理

项目文件夹整理

重复文件管理

大文件发现

音乐整理

照片整理

安全筛查与元数据

设置自动整理

📚 详细文档

工具参考

核心工具

文件类别

🔧 技术细节

技术栈

核心依赖

安全特性

性能优化

架构

先筛选后丰富架构

关键架构原则

API文档

新的元数据API

元数据缓存系统

📄 许可证

📝 重要提示

🤝 贡献

开发设置

报告问题

📚 文档

🙏 致谢

📞 支持

愉快地整理文件！🎯

Runtime guide

Hosted runtime

Local runtime / other methods