Local File Organizer

🚀 Local File Organizer

A Python-based file organization system that securely manages and organizes files between directories using the Model Context Protocol (MCP).

🚀 Quick Start

This project implements a file organization system using the MCP framework to achieve the following:

1. Securely access user-specified directories through powerful permission checks.
2. Automatically classify files by type into categorized directories.
3. Search for files within allowed directories.
4. Analyze directory contents and provide detailed file information.

✨ Features

• Directory Security: Only operate on explicitly allowed directories.
• Intelligent Classification: Organize files into the following categories based on their extensions:
  • Documents (PDF, DOC, DOCX, TXT, RTF, MD, HTML, JSON, CSV, etc.)
  • Images (JPG, PNG, GIF, SVG, WEBP, HEIC, etc.)
  • Videos (MP4, MOV, AVI, MKV, etc.)
  • Audio (MP3, WAV, OGG, FLAC, etc.)
  • Archives (ZIP, RAR, 7Z, TAR, etc.)
  • Code (PY, JS, HTML, CSS, Java, etc.)
  • Applications (DMG, EXE, MSI, etc.)
  • Others (Uncategorized file types)
• Project Detection: Identify code repositories to avoid interference.
• Recursive Processing: Analyze and organize nested directory structures.
• Resource Efficiency: Optimized for performance on large directory structures.
• Detailed Analysis: Provide insights into file distribution by type.

📦 Installation

# Clone the repository
git clone https://github.com/diganto-deb/local_file_organizer.git
cd local_file_organizer

# Install dependencies
pip install -r requirements.txt

💻 Usage Examples

Basic Usage

1. Configure Allowed Directories

Create or modify the .cursor/mcp.json file in the project directory:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/organize/dir1",
        "/path/to/organize/dir2"
      ]
    }
  }
}

Replace the paths with the directories you want to allow the MCP server to access.

2. Enable the MCP Server

After configuring the .cursor/mcp.json file:

1. Restart Cursor.
2. Open Cursor settings (⚙️).
3. Navigate to MCP.
4. You should see the filesystem server in the MCP server list.
   • The server should be named "filesystem".
5. Click the toggle switch next to the server name to enable it.

3. Use File Organization Commands

Once the MCP server is enabled, you can use the file organization commands directly in the Cursor proxy:

# List all available categories
list_categories

# Analyze a directory without making changes
analyze_directory /path/to/directory

# Create categorized folders in the target directory
create_category_directories /path/to/target

# Organize files by type
organize_files /path/to/directory

# Search for files
search_files /path/to/directory "*.jpg"

🔧 Technical Details

The system uses the following technologies:

• MCP Python SDK: For core server implementation.
• Filesystem MCP Server: For file system processing.
• Pathlib: For path operations.
• Type Annotations: For code maintainability and clarity.

📚 Future Plans

The following features will be added in future versions:

• Support for more file types and classifications.
• A graphical user interface (GUI).
• Integration with cloud storage.
• Enhanced security and permission control.

🤝 Contribution

If you'd like to contribute, please visit the project repository: https://github.com/diganto-deb/local_file_organizer

📄 License

This software is protected under the MIT License. Please refer to LICENSE for detailed information.