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.
npm installRelated MCP server: Organizer MCP Server
npm run generate-mock # generates 500 mock files into storage/inbox, with mtimes spread across the last 365 daysFühren Sie diesen Befehl jederzeit erneut aus, um einen frischen Datensatz zu erzeugen.
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 agentDiese 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".
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.
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 repoThis server cannot be deployed
Safe folder access for ChatGPT and Claude: read, write and search files, risky tools opt-in.
Find, read and reorganize files across Google Drive, OneDrive, SharePoint and Dropbox, with undo.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Markdown notes in folders, with files, that your AI assistant can read, write and organise.