File Organizer

A Python utility to analyze folders and suggest organized file structures using AI classification. The classifier can use OpenAI, a custom LLM endpoint, or interactive prompts.

Features

• Analyze a folder and suggest categories for files using AI.
• Subcategorize files with AI-determined categories (e.g., Python, Flask, PostgreSQL, etc.).
• Produce a suggested folder structure and AI-suggested filenames.
• Support for OpenAI, custom LLM endpoints, or interactive manual classification.
• Graceful fallback: when AI unavailable, optionally ask user for input via CLI/Inspector.

Quick start

Prerequisites: Python 3.9+ and pip.

Install dependencies:

python -m pip install -r requirements.txt

Run tests:

python -m pytest -q

Using the classifier

Option 1: OpenAI (recommended)

1. Get an OpenAI API key from platform.openai.com.
2. Run with AI:

$env:OPENAI_API_KEY = 'sk-your-key-here'
python main.py /path/to/folder

Option 2: Custom LLM endpoint

If you have a custom LLM service, configure it:

$env:EXTERNAL_LLM_URL = 'https://your-llm-api.example.com/classify'
$env:EXTERNAL_LLM_API_KEY = 'your-api-key'
python main.py /path/to/folder

Your endpoint should accept JSON:

{
  "filename": "example.py",
  "file_type": ".py",
  "content_preview": "def hello(): ..."
}

And return JSON:

{
  "category": "Code",
  "confidence": 0.95,
  "subcategory": "Python",
  "suggested_name": "hello_world.py"
}

Option 3: Interactive mode (manual classification)

For testing or when you prefer to classify files manually:

$env:INTERACTIVE_MODE = 'true'
python main.py /path/to/folder

The system will prompt you for each file's category, confidence, subcategory, and suggested name.

Option 4: No AI (auto-categorizes as "Uncategorized")

python main.py /path/to/folder

All files will be categorized as "Uncategorized" without any AI or interactive prompts.

Project layout

• services/ — core services (FileAnalysisService, FileOrganizationService).
• models/ — dataclasses for FileMetadata, FolderOrganization, OrganizationResult.
• tests/ — unit tests (run with pytest).
• utils/ — helpers and validators.

Contributing

1. Fork the repo and create a branch for your feature/bugfix.
2. Run tests and add new tests for your changes.
3. Open a pull request describing the change.

License

This repository does not include a license file. Add one if you intend to publish or share the project publicly (e.g. MIT).

File Organizer MCP

An intelligent MCP (Model Context Protocol) server that analyzes folders, automatically categorizes files, suggests meaningful names, and organizes them into topic-based folder structures.

Features

• Folder Analysis: Scan a folder and analyze its contents
• Intelligent Categorization: Automatically categorize files by type (Documents, Images, Code, Data, etc.)
• Smart Naming: Suggest improved, meaningful filenames based on content and context
• Folder Organization: Create organized folder structures by topics
• File Organization: Option to move and rename files according to suggested structure
• Metadata Extraction: Extract tags and metadata from files for better organization
• Confidence Scoring: Get confidence scores for suggested categorizations

Installation

pip install -e .

Configuration

Edit settings.py to customize:

• Maximum file size to analyze
• File extensions to consider as text
• Category detection keywords
• Maximum folder name length

Usage

As an MCP Server

Start the server:

python main.py

Available Tools

1. analyze_folder

Analyze a folder to understand its contents and suggest organization.

Parameters:

• folder_path (string, required): Absolute path to the folder to analyze

Returns:

• Suggested folder structure
• File categorization
• Renamed suggestions for each file
• Confidence scores

Example:

{
  "folder_path": "/path/to/folder"
}

2. organize_files

Organize files into topic-based folders with suggested names.

Parameters:

• folder_path (string, required): Absolute path to the folder to organize
• create_folders (boolean, optional): Whether to create the folder structure (default: false)
• move_files (boolean, optional): Whether to actually move files to new folders (default: false)
• apply_naming (boolean, optional): Whether to rename files with suggested names (default: false)

Returns:

• Created folders list
• Moved files list
• Any errors encountered
• Summary statistics

3. get_structure

Get the suggested folder structure for an analyzed folder.

Parameters:

• folder_path (string, required): Absolute path to the folder

Returns:

• Suggested structure with categories and file counts

Project Structure

file-organizer-mcp/
├── main.py                    # MCP server entry point
├── settings.py                # Configuration settings
├── pyproject.toml            # Project metadata
├── requirements.txt          # Python dependencies
├── README.md                 # This file
├── models/
│   ├── __init__.py
│   ├── result.py            # OperationResult model
│   └── file_models.py       # File and organization models
├── services/
│   ├── __init__.py
│   ├── file_analysis_service.py      # File analysis logic
│   └── file_organization_service.py  # File organization logic
├── utils/
│   ├── __init__.py
│   ├── errors.py            # Custom exceptions
│   ├── paths.py             # Path utilities
│   └── validate.py          # Validation utilities
└── tests/
    ├── __init__.py
    ├── test_file_analysis_service.py
    ├── test_file_organization_service.py
    └── test_integration.py

Categories

The server automatically recognizes and organizes into these categories:

• Documents: PDFs, Word docs, text files, reports
• Images: Photos, graphics, icons, screenshots
• Videos: Video files and recordings
• Audio: Music files, podcasts, audio recordings
• Code: Source code files in various languages
• Data: Datasets, databases, CSV, SQL files
• Configuration: Config files, settings, environment files
• Archives: Compressed files (zip, rar, etc.)
• Backup: Backup and old version files
• README: Documentation and guide files

Example Workflow

1. Analyze a folder:

   result = analyze_folder("/path/to/messy/folder")
   

2. Review the suggested structure

3. Organize with folders created but files not moved (safe preview):

   organize_files("/path/to/messy/folder", create_folders=True, move_files=False)
   

4. If satisfied, actually move files:

   organize_files("/path/to/messy/folder", create_folders=True, move_files=True)
   

Testing

Run tests:

pytest tests/

Error Handling

The server provides detailed error handling:

• InvalidPathError: When folder path is invalid
• FileAccessError: When files cannot be accessed
• AnalysisError: When file analysis fails
• OrganizationError: When organization fails

Limitations

• Maximum file size for analysis: 10 MB (configurable)
• Maximum files per folder: 1000 (configurable)
• Text file preview: First 500 characters only
• Folder name length: Maximum 200 characters

Contributing

Feel free to submit issues and enhancement requests!

License

MIT License