MCP File Organizer — demo for the techblog post "MCP in Practice"

A demo illustrating MCP through the "AI File Organization Assistant" use case: an MCP Server exposing 2 file-management tools (list_files, move_file — no read_file; the server never reads file contents, only file name/extension/modification date), and an MCP Client/Agent using Gemini (via @google/genai, with built-in MCP support through mcpToTool) to decide which tool to call based on the user's natural-language request. folder is any absolute path on the machine (not limited to the demo's storage/inbox — it can point to a real folder such as Downloads), and results always land in <folder>/organized/<extension>/<year>/<month>/<day>/. The demo dataset is 500 mock files accumulated over 365 days, reorganized by extension and then by year/month/day of last modification.

Setup

npm install

Generating mock data

npm run generate-mock   # generates 500 mock files into storage/inbox, with mtimes spread across the last 365 days

Rerun this command anytime to generate a fresh dataset.

Running the real Agent (requires a Gemini API key)

client/client.ts is the real Agent: it exposes the MCP client to Gemini via mcpToTool, letting Gemini decide on its own which tool to call and with what arguments (automatic function calling), with no hardcoded rules. It reads the key from GEMINI_API_KEY, or GOOGLE_API_KEY, or API_KEY (in that priority order); it reads the model from MODEL if the value starts with gemini-, otherwise it falls back to the default gemini-2.5-flash.

# PowerShell
$env:GEMINI_API_KEY = "AIza..."
npm run agent

# bash
export GEMINI_API_KEY="AIza..."
npm run agent

These variables can also be set in a .env file in the project directory; npm run agent automatically loads .env if it exists (using Node's --env-file-if-exists flag).

To try it on a real folder instead of storage/inbox, pass an absolute path as an argument, e.g. npm run agent -- "C:\Users\you\Downloads".

Safety when using real data

server.ts already guards against several cases before touching the filesystem:

folder must be an absolute path — a relative path is rejected immediately, never silently resolved against the server process's cwd.
name must be a bare file name (no /, \, or ..) — blocks traversal outside folder.
to_folder is resolved and then re-checked to ensure it stays within <folder>/organized/ — blocks traversal outside via ...
move_file refuses if the destination already exists (never silently overwrites); pass dry_run: true to preview what would be moved without touching real files.
Set the ALLOWED_ROOTS environment variable (a list of absolute paths, delimited by ; on Windows or : on Unix — following path.delimiter) to restrict folder to those roots only. If unset, the demo keeps its original behavior: accepting any absolute folder — fine for demo purposes, but ALLOWED_ROOTS should be set when pointing at real data.

Structure

server/server.ts               MCP Server: list_files, move_file — folder is any absolute path, never reads file contents
client/generate-mock-inbox.ts  Generates 500 mock files into storage/inbox
client/client.ts               MCP Client + Agent, using Gemini via @google/genai
storage/                       Generated by running generate-mock, not committed to the repo

MCP File Organizer — demo for the techblog post "MCP in Practice"