File Organizer MCP

🚀 File Organizer MCP Server

強力でセキュリティが強化された、インテリジェントなファイル整理のためのModel Context Protocol (MCP)サーバです。

🚀 クイックスタート

1コマンドでのセットアップ

インタラクティブなセットアップを開始するには、以下のコマンドを実行します。

npx file-organizer-mcp --setup

ウィザードは以下のことを行います。

• インストールされているAIクライアント（Claude Desktop、Cursor、Windsurf、Clineなど）を自動検出します。
• クライアントを自動的に設定します。
• フォルダの選択と設定のガイドを行います。

必要条件

• Node.js 18以上

一般的なコマンド

設定が完了したら、AIに以下のような指示をすることができます。

• "Downloadsフォルダを整理して"
• "Documentsフォルダ内の重複ファイルを見つけて"
• "最も大きいファイルを表示して"

インストール方法

✨ 主な機能

• カテゴリ分類 - 12種類以上のカテゴリにインテリジェントに分類します。
• スケジューリング - Cronベースの自動整理機能があります。
• 重複検出 - 内容のハッシュ化（SHA - 256）により、正確な重複ファイルの識別が可能です。
• メタデータ抽出 - 写真のEXIF、音楽のID3、文書のトピック抽出ができます。
• スマート整理 - 混合ファイルタイプを検出し、統一的な戦略で整理します。
• 安全な操作 - ドライランモード、ロールバックサポート、アトミックな移動が可能です。
• セキュリティ - TOCTOU対策、パストラバーサル保護、メタデータのスクラビングが行われます。
• マルチプラットフォーム対応 - Windows、macOS、Linuxにネイティブサポートされています。

📦 インストール

インストール方法

💻 使用例

基本的な使用法

# インタラクティブセットアップの開始
npx file-organizer-mcp --setup

高度な使用法

// セキュリティ設定のカスタマイズ
{
  "customAllowedDirectories": [
    "C:\\Users\\Name\\My Special Folder",
    "D:\\Backups"
  ]
}

📚 ドキュメント

ツールリファレンス

コアツール

• file_organizer_scan_directory：ディレクトリをスキャンし、詳細なファイル情報を取得します。
  • directory (必須): ディレクトリの完全パス
  • include_subdirs (オプション): 再帰的なスキャン
• file_organizer_read_file：8層の検証を行い、安全にファイルを読み取ります。
  • path (必須): 絶対パス
  • encoding (オプション): utf - 8、base64、またはbinary
• file_organizer_organize_smart：音楽、写真、文書を自動的に最適な戦略で整理する統一ツールです。
• file_organizer_batch_rename：パターン、正規表現、または番号付けを使用して複数のファイルをリネームします。
• file_organizer_undo_last_operation：前回の整理操作を元に戻します。

ファイルカテゴリ

ワークフロー例

インテリジェントなDownloadsフォルダの整理

1. スキャン -> ファイルの分布と使用領域を確認します。
2. 分析 -> 重複ファイルと古いファイルを特定します。
3. 実行 -> カテゴリ別のフォルダにアトミックに整理します。
4. 重複ファイルを見つける -> 45の重複グループが見つかり、2.3GBの無駄な領域がありました。
5. 最大のファイルを表示 -> old_backup.zip: 5.2GB
6. 整理のプレビュー -> 予定された移動と競合を表示します。
7. 確認を求める
8. ファイルを整理 -> ✅ 1,247個のファイルを8つのカテゴリフォルダに整理しました。

プロジェクトの整理

ユーザー: "Claude, ~/myprojectのプロジェクトフォルダを整理して"

Claude:
1. プロジェクトをスキャン -> 複数のサブディレクトリにまたがる423個のファイル
2. ファイルタイプを特定 -> コード (289)、アセット (87)、ドキュメント (47)
3. 整理の提案 -> src/構造を維持し、ルートファイルを整理します。
4. 変更のプレビュー -> 整理する47個のアイテムを表示します。
5. 実行 -> 設定ファイル、README、スクリーンショットを適切なフォルダに移動します。

重複ファイルの管理

ユーザー: "Claude, C:/Users/[YOUR_USERNAME]/Documents内の重複ファイルを見つけて分析して"

Claude:
1. 重複ファイルをスキャン -> 23の重複グループが見つかりました。
2. 各グループを分析 -> 場所、名前の品質、年齢でファイルをスコアリングします。
3. 残すファイルを提案 -> "/Documents/Important/file.pdf"を残します。
4. 削除するファイルを提案 -> "/Downloads/file (1).pdf"を削除します。
5. 無駄な領域を表示 -> 合計: 1.8GBを回収できます。

大きなファイルの発見

ユーザー: "Claude, Downloadsフォルダ内でスペースを占有している20個の最大のファイルを表示して"

Claude:
1. ディレクトリのサイズを分析 -> 合計: 45.2GB
2. 最大のファイルを見つける:
    - old_backup_2023.zip: 12.3GB (2年前)
    - movie_collection.mkv: 8.7GB
    - presentation_final.pptx: 890MB
3. クリーンアップの提案 -> 古いバックアップをアーカイブまたは削除します。
4. 大きなファイル内の重複を表示 -> 一部の大きなファイルにコピーがあります。

音楽の整理

ユーザー: "Claude, C:/Users/[YOUR_USERNAME]/Musicの音楽フォルダを整理して"

Claude:
1. ディレクトリをスキャン -> 456個の音楽ファイル、2.3GBを表示します。
2. メタデータを抽出 -> ID3タグからアーティスト、アルバム、タイトルを読み取ります。
3. 整理のプレビュー -> 予定された構造: Artist/Album/Title.mp3を表示します。
4. 確認を求める
5. ファイルを整理 -> ✅ 456個の音楽ファイルを32個のアーティストフォルダに整理しました。

写真の整理

ユーザー: "Claude, C:/Users/[YOUR_USERNAME]/Picturesの写真を整理して"

Claude:
1. ディレクトリをスキャン -> 1,234個の写真、4.5GBを表示します。
2. メタデータを抽出 -> EXIFタグから撮影日を読み取ります。
3. 整理のプレビュー -> 予定された構造: YYYY/MM/DDを表示します。
4. 確認を求める
5. ファイルを整理 -> ✅ 1,234個の写真を日付ベースのフォルダに整理しました。

メタデータを使用したセキュリティスクリーニング

ユーザー: "Claude, Documentsフォルダをセキュリティ問題についてスキャンして"

Claude:
1. ディレクトリをスキャン -> 567個の文書、1.2GBを表示します。
2. メタデータを抽出 -> ファイルのメタデータとコンテンツの署名を読み取ります。
3. セキュリティスクリーニングを実行 ->
    - 3つのファイルに機密メタデータがあることが判明
    - 1つのファイルに潜在的に悪意のあるコンテンツがあることが判明
4. 詳細なレポートを表示 ->
    - "report.pdf"にEXIF GPS座標が含まれている
    - "resume.docx"に個人識別情報が含まれている
5. アクションを提案 -> メタデータを編集、ファイルを隔離

自動整理の設定

ユーザー: "Claude, Downloadsフォルダを毎日午前9時に自動的に整理して"

Claude:
1. 監視ディレクトリを設定 ->
    file_organizer_watch_directory({
        directory: "/Users/john/Downloads",
        schedule: "0 9 * * *",
        min_file_age_minutes: 5
    })
2. 設定を確認 -> "Downloadsフォルダは毎日午前9:00に整理されます"
3. 現在の監視を表示 -> すべての監視ディレクトリをリスト表示します。

ユーザー: "Desktopフォルダも1時間ごとに監視して"

Claude:
4. 2番目の監視を追加 ->
    file_organizer_watch_directory({
        directory: "/Users/john/Desktop",
        schedule: "0 * * * *",
        max_files_per_run: 50
    })

🔧 技術詳細

技術スタック

File Organizer MCPは、最新のWeb技術を使用して構築され、厳格なセキュリティ慣行に則っています。

コア依存関係

• MCP Server：@modelcontextprotocol/sdk - Model Context Protocolの実装
• セキュリティ：Zodスキーマ検証、パストラバーサル保護
• メタデータ抽出：
  • music-metadata - オーディオファイルのID3タグ抽出
  • exif-parser - 画像のEXIFメタデータ抽出
• スケジューリング：node-cron - Cronベースのスケジュール管理
• インタラクティブUI：Ink + React - ターミナルユーザーインターフェイス
• プロンプト：@inquirer/prompts - インタラクティブCLIプロンプト
• ユーティリティ：Chalk（色）、minimatch（グロブパターン）

セキュリティ機能

• 8層のパス検証 - トラバーサル攻撃とURIエンコーディングのトリックをブロックします。
• 機密ファイル検出 - .env、.ssh、パスワード、キーへのアクセスをブロックします。
• レート制限 - 1分あたり120リクエスト、1時間あたり2000リクエスト
• TOCTOU保護 - ファイルディスクリプタベースの操作
• メタデータセキュリティ - 機密メタデータ（GPS、個人情報）を編集します。

パフォーマンス最適化

• メタデータキャッシュ - ファイルハッシュ検証付きの7日間のキャッシュ
• 並列処理 - バッチ操作のための設定可能な並列性
• ストリーム処理 - メモリ問題なしで大きなファイルを処理します。
• メモリ制限 - 過度のリソース消費を防止します。

アーキテクチャ

Screen - Then - Enrichアーキテクチャ

File Organizer MCPサーバは、安全で効率的なファイル操作のための"Screen - Then - Enrich"アーキテクチャを実装しています。

┌───────────────────────────────────────────────────────────┐
│                     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. アトミック操作 - ロールバックサポート付きの安全なファイル操作

📄 ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください。

🤝 コントリビュート

コントリビューションは歓迎されます！ガイドラインについては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にメールで報告してください。
🐛 バグ/機能要望：GitHub Issuesで報告してください。

📚 その他のドキュメント

• API.md - 完全なツールリファレンス
• ARCHITECTURE.md - 技術的なアーキテクチャとデザインパターン
• CONTRIBUTING.md - コントリビューションガイドライン
• MIGRATION.md - v2からv3へのアップグレードガイド
• CHANGELOG.md - バージョン履歴

📞 サポート

• MCP Registry：View Listing
• NPM Package：View on NPM
• Issues：GitHub Issues
• MCP Spec：Model Context Protocol

快適な整理を！ 🎯

MCPコミュニティのために愛を込めて作成されました。

⬆ ページトップに戻る