MCP File Organizer — Demo für den Techblog-Beitrag „MCP in Practice“

Ein Demo, das MCP anhand des Anwendungsfalls „AI File Organization Assistant“ veranschaulicht: ein MCP-Server, der 2 Dateiverwaltungs-Tools bereitstellt (list_files, move_file — kein read_file; der Server liest nie Dateiinhalte, nur Dateiname/Erweiterung/Änderungsdatum), und ein MCP-Client/Agent, der Gemini verwendet (über @google/genai, mit integrierter MCP-Unterstützung durch mcpToTool), um anhand der natürlichen Anfrage des Benutzers zu entscheiden, welches Tool aufgerufen werden soll. folder ist ein beliebiger absoluter Pfad auf dem Rechner (nicht auf das storage/inbox des Demos beschränkt — er kann auf einen echten Ordner wie Downloads zeigen), und Ergebnisse landen immer in <folder>/organized/<extension>/<year>/<month>/<day>/. Der Demo-Datensatz besteht aus 500 Mock-Dateien, die über 365 Tage erzeugt wurden, neu organisiert nach Endung und dann nach Jahr/Monat/Tag der letzten Änderung.

Einrichtung

npm install

Related MCP server: Organizer MCP Server

Mock-Daten erzeugen

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

Führen Sie diesen Befehl jederzeit erneut aus, um einen frischen Datensatz zu erzeugen.

Den echten Agenten ausführen (erfordert einen Gemini-API-Schlüssel)

client/client.ts ist der echte Agent: Er stellt den MCP-Client Gemini über mcpToTool bereit, sodass Gemini selbst entscheiden kann, welches Tool mit welchen Argumenten aufgerufen wird (automatisches Function Calling), ohne fest verdrahtete Regeln. Er liest den Schlüssel aus GEMINI_API_KEY, GOOGLE_API_KEY oder API_KEY (in dieser Prioritätsreihenfolge); das Modell liest er aus MODEL, wenn der Wert mit gemini- beginnt, andernfalls fällt er auf das Standardmodell gemini-2.5-flash zurück.

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

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

Diese Variablen können auch in einer .env-Datei im Projektverzeichnis gesetzt werden; npm run agent lädt .env automatisch, falls es existiert (mithilfe des --env-file-if-exists-Flags von Node).

Um es mit einem echten Ordner statt storage/inbox auszuprobieren, übergeben Sie einen absoluten Pfad als Argument, z. B. npm run agent -- "C:\Users\you\Downloads".

Sicherheit bei der Verwendung echter Daten

server.ts schützt bereits vor mehreren Fällen, bevor das Dateisystem berührt wird:

• folder muss ein absoluter Pfad sein — ein relativer Pfad wird sofort abgelehnt, nie stillschweigend gegen das cwd des Serverprozesses aufgelöst.

• name muss ein reiner Dateiname sein (kein /, \ oder ..) — verhindert Traversal außerhalb von folder.

• to_folder wird aufgelöst und dann erneut geprüft, um sicherzustellen, dass es innerhalb von <folder>/organized/ bleibt — verhindert Traversal nach außen über ...

• move_file lehnt ab, wenn das Ziel bereits existiert (überschreibt nie stillschweigend); übergeben Sie dry_run: true, um eine Vorschau zu sehen, was verschoben würde, ohne echte Dateien anzufassen.

• Setzen Sie die Umgebungsvariable ALLOWED_ROOTS (eine Liste absoluter Pfade, getrennt durch ; unter Windows oder : unter Unix — gemäß path.delimiter), um folder nur auf diese Roots zu beschränken. Wenn nicht gesetzt, behält das Demo sein ursprüngliches Verhalten: Es akzeptiert jeden absoluten Ordner — für Demo-Zwecke in Ordnung, aber ALLOWED_ROOTS sollte gesetzt werden, wenn auf echte Daten gezeigt wird.

Struktur

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