MCP 文件系统适配器全家桶

这个 pack 解决什么

多数开发者接 agent 都从单一文件系统开始 —— 一般是本地磁盘 + 官方 MCP server，然后就停了。直到下一个工单来了：「把昨晚的导出从 S3 拉下来」「把这个文件夹同步到 R2」「从合作方 SFTP 收件箱取 PDF」「在 Google Drive 和团队 NAS 之间合并文件」。每多一个后端，就多一份 ad-hoc shell 包装、一种凭据格式、零作用域强制、零审计日志。

这个 pack 是跨协议那一组 —— 10 个适配器选出来，让 agent 用同一套权限模型够到本地 fs / AWS S3 / Cloudflare R2 / Google Drive / SFTP-FTP / 30+ 多云后端。文件系统 Agent + 本地操作 深挖本地（Downloads 整理 / 去重 / 批量改名），这个 pack 横切各种协议。

三层：本地（1-3）/ 云原生（4-7）/ 网关 + 策略（8-10）。

为什么要做多协议

MCP 给 agent 提供了清晰的文件系统接口，但协议本身不规定另一头是什么。不同团队拓扑差别很大：

• 独立开发：只有本地磁盘，Filesystem MCP 就够
• 后端团队：本地 + S3 + R2 上一个 CI 产物桶。三个适配器、三套凭据
• 企业：再加合作方 SFTP / 财务 Google Drive / 内网 SMB NAS。5+ 后端，审计要求各不相同

Pack 里挑的都是同时把四件事做对的：作用域（agent 根本看不到配置路径之外的东西）、默认只读（写权限按 server 显式打开）、结构化审计日志（每次调用都进可 grep 的文件）、凭据隔离（每个适配器持有自己的密钥，互不连坐）。

安装顺序 —— 本地 → 云 → 传输 → 策略

1. 先本地（#1-3）。Filesystem MCP 指向一个项目目录起步。需要终端 + PDF/DOCX 文本提取时上 Desktop Commander。用 MCP Reference Servers 当 host（Claude Code / Cursor / Codex CLI）的烟雾测试，验证 MCP 链路通了

2. 再云桶（#4-6）。本地验证完之后接 AWS MCP server 给 S3。再 Cloudflare Workers MCP 如果你的边缘缓存和资产在 R2 —— 同一个协议，不同存储层。Google Workspace MCP 如果 Drive 是工作流的一部分

3. 再传输协议（#7-8）。rclone（#7）本身不是 MCP server，但它是跨云万能拷贝工具 —— 通过 Desktop Commander 的 shell 暴露出来，agent 用熟悉的 CLI 获得 70+ 后端能力。SFTPGo（#8）是自托管 SFTP/FTP/WebDAV 服务器，给合作方一个接入点，agent 挂载每用户独立虚拟 fs

4. 最后策略层（#9-10）。Alist（#9）让 agent 通过一个 WebDAV 挂载点访问 30+ 云后端 —— 不想每个 provider 起一个 MCP server 时用它。AgentSeal（#10）是把整条链路包起来的审计 + ACL 工具箱，所有适配器调用进一份日志、走一套策略

# 接好的 agent host 长这样
# ~/.config/claude/mcp.json
{
  "mcpServers": {
    "fs-local":   { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "$HOME/projects"] },
    "fs-aws":     { "command": "uvx", "args": ["awslabs.s3-mcp-server"], "env": { "AWS_PROFILE": "readonly" } },
    "fs-r2":      { "command": "npx", "args": ["-y", "@cloudflare/mcp-server-workers"] },
    "fs-drive":   { "command": "uvx", "args": ["workspace-mcp"], "env": { "GOOGLE_OAUTH_SCOPE": "drive.readonly" } }
  }
}

4 个适配器 / 4 个作用域 / 4 套凭据。Agent 调 fs-aws.list_objects 或 fs-drive.search_files，剩下的协议自己处理。

沙箱与权限作用域

这个 pack 相对于「直接给 agent aws / rclone / sftp 裸 shell」最大的胜负手是在协议边界上强制作用域：

• Filesystem MCP 启动时把允许的根目录作为位置参数传入。列表外的路径 agent 根本看不见 —— 不是写时被拦，是读时就不可见。cat ~/.ssh/id_rsa 这种调用根本无法发起，因为 server 不暴露 ~
• AWS MCP servers 在显式 IAM role 下跑。正确的姿势是浏览用 read-only role，单独一个 mcp-writer role 只对一个 bucket 前缀有 s3:PutObject，写任务才切过去
• Cloudflare Workers MCP 用 Worker 级绑定 —— R2 token 在 Worker（不是 agent）手里，agent 只能调 Worker 暴露的操作
• Google Workspace MCP 用 OAuth scope。默认 drive.readonly；写场景下最小是 drive.file（按文件授权），比多数 quickstart 贴的全量 drive scope 窄得多
• SFTPGo 把每个 agent 隔离到自己的虚拟 fs —— agent 以 mcp-agent 用户连接，只看到挂载的文件夹，看不到磁盘其他位置
• AgentSeal 横跨整个栈，强制按工具的 ACL 加结构化审计。适配器原生日志不一致时尤其有用

审计与撤销

Pack 里每个适配器都写到可 grep 的日志。组合姿势：

tail -f ~/.tokrepo/logs/fs-*.log | tee ~/.audit/$(date +%F).jsonl

每个 session 一个 tail，每天一份文件。出事的时候 —— agent 删错了对象 / 写错了路径 —— 你有调用、参数、结果、时间戳。再配上 S3 / R2 侧的版本化桶（生命周期规则 → 30 天保留），几乎所有失误都能回滚。

撤销是按适配器粒度：删 IAM role / 轮换 OAuth refresh token / 禁用 SFTPGo 用户 / 杀 Worker binding。没有一个凭据能开多种后端，这是唯一能规模化的结构性保护。

常见踩坑

• 一个凭据通吃所有后端。最大反模式就是个人 AWS access key 复用到所有 MCP server。每个适配器独立最小权限 role；混着用就把整个 pack 的意义都废了
• 忘了 OAuth 刷新。Google Workspace MCP 走 OAuth —— refresh token 6 个月不用会过期。挂个月度 cron 跑一次空调用，让 token 保持热的
• rclone 默认开了写权限。rclone 尊重 remote 自身的权限，但配错了 remote（拿账号根密钥）agent 就能看见所有 bucket。永远按任务建专用 remote，权限拧到最小
• SFTPGo 审计日志没轮转。SFTPGo 日志很啰嗦，不轮转一个忙碌的 agent 一周打满磁盘。配 logrotate 或它内置的保留策略
• Alist 是单点失陷。便利的代价 —— 一个 Alist 实例带着 10 个后端的凭据，一次入侵等于 10 个问题。Alist 放 VPN 后面，永远别暴露公网