MCP File Organizer — テックブログ記事「MCP in Practice」用のデモ

「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 install

Related MCP server: Organizer MCP Server

モックデータの生成

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

このコマンドを再実行すれば、いつでも新しいデータセットを生成できます。

実際のAgentを実行する（Gemini APIキーが必要）

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 repo