这是一个通过“AI File Organization Assistant”用例来演示 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>/ 中。演示数据集是 500 个在 365 天内累积的模拟文件，先按扩展名、再按最后修改的年/月/日重新组织。
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- 开头，则从 MODEL 读取模型，否则回退到默认的 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.