MCP File Organizer — 技术博客文章“MCP in Practice”的演示

这是一个通过“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 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- 开头，则从 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 repo