「AIファイル整理アシスタント」のユースケースを通してMCPを説明するデモです。MCP Serverは2つのファイル管理ツール（list_files、move_file — read_fileはなし。サーバーはファイルの内容を一切読み取らず、ファイル名・拡張子・更新日時のみを扱います）を公開し、MCP Client/AgentはGemini（@google/genai経由、mcpToToolによる組み込みのMCPサポートを使用）を使って、ユーザーの自然言語リクエストに基づいてどのツールを呼び出すかを決定します。folderはマシン上の任意の絶対パスです（デモのstorage/inboxに限定されず、Downloadsなどの実際のフォルダを指定できます）。結果は常に<folder>/organized/<extension>/<year>/<month>/<day>/に配置されます。デモデータセットは365日分にわたって蓄積された500個のモックファイルで、拡張子、次いで最終更新日時の年/月/日で再整理されます。
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 daysこのコマンドを再実行すれば、いつでも新しいデータセットを生成できます。
client/client.tsが実際のAgentです。mcpToTool経由でMCPクライアントをGeminiに公開し、Geminiがどのツールをどの引数で呼び出すかを自ら決定します（自動関数呼び出し）。ハードコードされたルールはありません。キーはGEMINI_API_KEY、GOOGLE_API_KEY、API_KEYの順に読み取ります（この優先順位）。モデルはMODELの値がgemini-で始まる場合にその値を使用し、それ以外はデフォルトのgemini-2.5-flashにフォールバックします。
# PowerShell
$env:GEMINI_API_KEY = "AIza..."
npm run agent# bash
export GEMINI_API_KEY="AIza..."
npm run agentこれらの変数はプロジェクトディレクトリの.envファイルでも設定できます。npm run agentは.envが存在する場合に自動的に読み込みます（Nodeの--env-file-if-existsフラグを使用）。
storage/inboxの代わりに実際のフォルダで試すには、引数として絶対パスを渡します。例：npm run agent -- "C:\Users\you\Downloads"。
server.tsはファイルシステムに触れる前に、いくつかのケースをすでにガードしています。
folderは絶対パスである必要があります — 相対パスは即座に拒否され、サーバープロセスのcwdに対して暗黙的に解決されることはありません。
nameは単純なファイル名である必要があります（/、\、..は不可）— folderの外へのトラバーサルをブロックします。
to_folderは解決後に再チェックされ、<folder>/organized/内に収まることを確認します — ..による外部へのトラバーサルをブロックします。
move_fileは移動先がすでに存在する場合に拒否します（暗黙の上書きはしません）。dry_run: trueを渡すと、実際のファイルに触れずに移動内容をプレビューできます。
ALLOWED_ROOTS環境変数（絶対パスのリスト。Windowsでは;、Unixでは:で区切る — path.delimiterに従う）を設定すると、folderをそれらのルートのみに制限できます。未設定の場合、デモは元の動作を維持します：任意の絶対フォルダを受け入れます — デモ用途には問題ありませんが、実データを指す場合はALLOWED_ROOTSを設定すべきです。
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.