Smart File Organizer Server

Welcome to Day 3 of your 7-Day Project! Today, you are building a Smart File Organizer and wrapping it as a Model Context Protocol (MCP) Server.

This document explains what MCP is, how your organizer works, and how to test and run it as an AI-callable tool.

---

💡 What is MCP (Model Context Protocol)?

Traditionally, AI models (like Claude, ChatGPT, or Gemini) are locked inside their chat boxes. They cannot access your local files or run scripts on your computer unless the application hosting them specifically builds a custom feature.

Model Context Protocol (MCP) is an open standard created by Anthropic. It acts like a USB port for AI:

• MCP Client: The AI chat application (e.g., Claude Desktop, Cursor IDE).
• MCP Server: A background program (written in Python, Node.js, etc.) that exposes local resources, prompts, or executable Tools.
• Protocol: The AI can query the server to ask "What tools do you have?" and then "Call tool organize_directory with parameter directory_path."

Today, you are building an MCP Server that exposes your file organizer as a tool, allowing an AI assistant to manage your directories for you!

---

📁 Project Structure

Here is what we have built in this directory:

1. organizer.py: The core script that does the file sorting. It can be run by itself from the command line.
2. server.py: The MCP server code that wraps organizer.py using FastMCP.
3. test_env_setup.py: A helper script that creates a safe test_downloads/ folder full of dummy files so you can test without touching your real files.
4. requirements.txt: The dependencies (mcp, fastmcp) needed to run the server.

---

🚀 How to Run and Test

Follow these steps to learn and run the project:

Step 1: Set up the environment

Make sure you have created your virtual environment and installed the dependencies:

# Create a virtual environment
python -m venv .venv

# Activate it (Windows PowerShell)
.venv\Scripts\Activate.ps1

# Install requirements
pip install -r requirements.txt

Step 2: Generate mock files for testing

Before organizing your actual files, run the generator script. This creates a folder named test_downloads/ with dummy files (.jpg, .pdf, .mp4, etc.):

python test_env_setup.py

Step 3: Run the organizer manually (CLI)

You can run the organizer directly. Let's start with a Dry Run (simulation) so it won't actually move anything:

python organizer.py test_downloads --dry-run

Once you verify that it lists the correct folders and destinations, run it for real:

python organizer.py test_downloads

Check your test_downloads/ folder. You will see that subfolders like Images, Documents, and Videos have been created, and files have been successfully sorted into them!

---

🔍 Testing the MCP Server (The AI Interface)

MCP servers communicate over standard input/output (stdio) using JSON-RPC, so running python server.py directly in the terminal will look like it's frozen.

To test it visually, we use the MCP Inspector, an official web UI wrapper:

# Run this inside your Day 3 directory
npx @modelcontextprotocol/inspector .venv\Scripts\python.exe server.py

• What happens: This command starts your server and launches a web browser window (usually at http://localhost:5173 or similar).
• What to look for:
  1. Click the Tools tab. You should see analyze_directory and organize_directory listed!
  2. Select analyze_directory and enter the path of your test_downloads folder (e.g., C:/Users/user/Desktop/7 day project/Day 3/test_downloads). Click Run.
  3. You will see the AI-friendly textual response summarizing the files.
  4. Now try organize_directory with dry_run = True or False. Watch the directory tidy up!

---

🤖 Connecting to Your AI Clients

Once your server works, you can add it to your daily AI editors so they can call it.

1. Claude Desktop

Open your Claude Desktop configuration file (typically at %APPDATA%\Claude\claude_desktop_config.json) and add your server:

{
  "mcpServers": {
    "smart-file-organizer": {
      "command": "C:/Users/user/Desktop/7 day project/Day 3/.venv/Scripts/python.exe",
      "args": [
        "C:/Users/user/Desktop/7 day project/Day 3/server.py"
      ]
    }
  }
}

(Make sure to replace the paths above with the actual absolute paths on your computer!)

Restart Claude Desktop, and you will see an organizer tool icon. You can now type: "Organize my downloads folder"!

2. Cursor IDE

1. Open Cursor Settings -> Features -> MCP.
2. Click + Add New MCP Server.
3. Fill in the fields:
   • Name: Smart File Organizer
   • Type: command
   • Command: C:/Users/user/Desktop/7 day project/Day 3/.venv/Scripts/python.exe "C:/Users/user/Desktop/7 day project/Day 3/server.py"
4. Save and click Refresh. Your Cursor AI agent can now use this tool during chat!

---

🎯 What You Learned Today

• Separation of Concerns: Keeping your core logic (organizer.py) separate from your communication logic (server.py).
• Model Context Protocol (MCP): How to let LLMs access local capabilities via stdio JSON-RPC.
• Safe CLI Design: Using dry-runs and safe file naming to prevent data loss.
• Log redirection: Why outputting logs to sys.stderr is critical when standard output (stdout) is used for data transmission.