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 exposes two file-management tools (list_files, move_files; there is no read_file), while a custom host/agent application calls Gemini and contains the MCP Client that connects to the server. move_files accepts one or more moves in a single call. to_folder is optional: when it is omitted the server itself derives the destination as <extension>/<year>/<month>/<day> from the file's own modification time, so the default organization scheme holds even when the request never spells it out. The model only has to override to_folder when a different layout is asked for. folder must be an absolute path allowed by the operating system and, when configured, ALLOWED_ROOTS. Results land in <folder>/organized/<extension>/<year>/<month>/<day>/, with extension-less files under <folder>/organized/no-extension/.... Only plain files directly inside folder are in scope; subfolders are excluded. The demo dataset contains 500 mock files whose modification times span the previous 365 days.

Setup

npm ci

The setup was verified on 2026-08-27 with Node.js 24.15.0, @modelcontextprotocol/client 2.0.0, @modelcontextprotocol/server 2.0.0, @google/genai 2.17.0, Zod 4.4.3, tsx 4.23.12, and TypeScript 7.0.2. MCP TypeScript SDK v2 uses separate client and server packages; v1 used the monolithic @modelcontextprotocol/sdk package.

The mcpToTool integration is experimental in @google/genai 2.17.0. This repository verifies the locked version combination; it does not claim that every MCP client version is compatible with every @google/genai version.

Related MCP server: Organizer MCP Server

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 custom host/agent (requires a Gemini API key)

client/client.ts is a custom host/agent application. It creates an MCP Client, connects that client to the File MCP Server, and exposes the discovered tools to Gemini through mcpToTool. Gemini then chooses the tool and arguments through automatic function calling. The application reads the key from GEMINI_API_KEY, GOOGLE_API_KEY, or API_KEY in that order. MODEL is optional; invalid or missing values fall back to 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_files refuses an entry if name resolves to a folder instead of a file — only plain files directly inside folder can be moved, so a subfolder (e.g. organized/ itself) can never be renamed/moved as a whole.

• move_files creates the destination with an atomic hard link, which fails if the path already exists, and then removes the source link. This prevents the check-then-rename overwrite race while preserving file metadata. The source and destination must be on a filesystem that supports hard links; unsupported filesystems return a per-entry error instead of falling back to an overwrite-prone move.

• If source removal fails after the hard link is created, the server removes the destination as a rollback. If rollback also fails, the error identifies both paths so the duplicate links can be inspected manually.

• Pass dry_run: true to preview a move without creating directories or links.

• to_folder is validated the same way whether it comes from the caller or from the server's default scheme: the destination is resolved and re-checked against <folder>/organized/ before anything is created, and each result entry reports the to_folder actually used so the caller can see what the default resolved to. A failing entry that omitted to_folder reports no to_folder at all, since the default is only computed once the source is confirmed to be a real file.

• move_files applies these checks to each entry in moves independently — one bad entry (typo'd name, existing destination, ...) is reported as a failure for that entry only and does not stop the rest of the batch from moving.

• 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. client.ts explicitly forwards ALLOWED_ROOTS to the server.ts subprocess it spawns — a plain child process only inherits a fixed safe env allowlist (PATH, APPDATA, ...) by default, so this variable would otherwise never reach the server.

Structure

server/server.ts               MCP Server: list_files, move_files — validates allowed absolute paths, never reads file contents
client/generate-mock-inbox.ts  Generates 500 mock files into storage/inbox
client/client.ts               Custom host/agent containing an MCP Client and using Gemini via @google/genai
tests/server.test.ts           MCP integration tests that do not require a Gemini API key
storage/                       Generated by running generate-mock, not committed to the repo

Testing

npm run test
npm run build

The integration test starts the server over stdio and checks tool discovery, file listing, successful moves, modification-time preservation, existing destinations, dry runs, unsafe inputs, directory inputs, mixed-result batches, and the default <extension>/<year>/<month>/<day> scheme applied when to_folder is omitted (including the UTC date agreeing with list_files, the no-extension bucket, and an explicit to_folder still overriding it). It does not call the Gemini API.