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

⬆ 返回頂部