MCP 文件系统工具：安全边界、路径隔离与流式处理

1. 文件系统工具的价值与风险

文件系统是模型操作世界的窗口：读配置文件、写报告、整理目录、批量重命名。但文件系统工具也是最容易造成破坏的——一次误删、一个越权读、一条路径穿越，都可能带来实际损失。文件系统 MCP 工具的工程核心，是在"能干活"与"不闯祸"之间找到平衡。

1.1 典型能力

1.2 风险面

# 文件工具核心风险
# 1) 路径穿越: ../ 逃出授权目录
# 2) 越权读: 读取系统文件（/etc/passwd、.env）
# 3) 覆盖写: 模型覆盖了不该动的文件
# 4) 删除破坏: 误删数据
# 5) 资源耗尽: 读超大文件 / 列出海量目录
# 6) 符号链接: 软链指向授权目录外
# 设计原则: 根目录白名单 + 路径规范化 + 显式高危操作

2. 安全边界模型

文件系统的授权不能靠"工具自觉",要靠边界强制。边界模型是文件工具安全的第一设计决策。

2.1 根目录白名单

# 只允许操作白名单内的根目录
# 例如: /workspace, /tmp/mcp-shared
# 禁止: /, /etc, /usr, /home/*/others, /var
# 模型的操作被锁在"根目录集合"内，集合外一律拒绝
# 根目录白名单 = 虚拟文件系统的"活动范围"

2.2 虚拟文件系统（VFS）

# 把授权根映射成模型眼里的"顶层"
# 模型看到的路径: /data/report.md
# 实际路径: /workspace/report.md
# 优点
# 1) 模型无法感知/拼写真实绝对路径
# 2) 工具内部统一做映射与校验
# 3) 迁移根目录不改工具语义
# VFS 让"授权根"变成路径空间的硬约束

2.3 边界校验的层次

# 校验分三层，缺一不可
# 1) 输入层: 参数里的路径必须是授权根下（规范化后）
# 2) 解析层: 处理后 realpath 再校验一次（防符号链接逃逸）
# 3) 内核层: 操作系统级（chroot/沙箱）兜底
# 工具层校验防"普通人"，沙箱层防"真正的攻击者"

3. 路径隔离与防穿越

路径穿越是最经典的文件攻击。模型生成的路径可能含 ../、符号链接、编码技巧，工具必须把路径「规范化 + 再校验」。

3.1 路径规范化

from pathlib import Path

def resolve_safe(path: str, roots: list[Path]) -> Path:
    p = Path(path)
    if not p.is_absolute():
        p = (roots[0] / p).resolve()  # 相对路径锚到根
    else:
        p = p.resolve()               # 解析 .. 与软链
    # 校验是否落在任一授权根内
    if not any(p.is_relative_to(root.resolve()) for root in roots):
        raise PermissionError(f"路径越界: {path}")
    return p

3.2 防穿越要点

# 1) 解析 .. 与 .（resolve 完成）
# 2) 解析符号链接（resolve 完成，且最终路径再校验）
# 3) 拒绝绝对路径里混入的授权根拼接技巧
# 4) 统一用校验后的规范化路径执行操作
# 5) 目录遍历（list）同样走 resolve_safe
# 永远用"解析后的最终路径"做权限判断，而不是原始字符串

3.3 符号链接策略

# 对符号链接的选择
# 1) 默认跟随并校验最终目标（灵活但有边界风险）
# 2) 严格模式: 禁止任何软链/硬链（最安全，可能误伤正常使用）
# 3) 白名单软链: 只允许指向授权根内的软链
# 推荐: 跟随 + 最终路径校验，兼顾可用与安全

4. 权限与沙箱

路径白名单之外，还有权限模型与进程沙箱两道防线。三者叠加才是完整的文件安全。

4.1 工具级读写分离

# 与数据库工具同样的原则
# 1) 读工具（read/list/glob）默认可用
# 2) 写工具（write/append）默认可用但显式命名
# 3) 修改/删除工具高危，默认关闭或需配置开启
# 4) 删除工具带 force 确认参数
# 读与写分开，模型要"故意"才能破坏

4.2 进程沙箱

# 沙箱选项（从软到硬）
# 1) 受限账号: 以低权限用户跑 MCP 服务器
# 2) 容器: 只挂载授权目录（Docker 卷映射）
# 3) seccomp/Landlock: 内核级限制文件系统调用
# 4) 虚拟机: 完全隔离（重型方案）
# 最实用组合: 低权限账号 + 容器挂载白名单目录

4.3 删除与覆盖保护

# 高危操作的保护机制
# 1) 删除进回收站（Trash）而非直接 rm
# 2) 覆盖写保留备份（.bak）或要求确认
# 3) 删除前返回文件信息让模型/用户确认
# 4) 审计记录每次删除/覆盖
# "可恢复"是把破坏变成"麻烦"的关键

5. 大文件流式处理

模型上下文有 token 上限，一个 500MB 的日志文件不能整个读进上下文。大文件处理要「流式、分页、按需」。

5.1 读取的分页

# 按行/字节范围读取
async def read_file(path: str, offset: int = 0, limit: int = 2000):
    safe = resolve_safe(path, roots)
    with open(safe, "r", encoding="utf-8", errors="replace") as f:
        f.seek(offset)
        lines = f.readlines(limit)
    total = file_line_count(safe)  # 缓存的行数
    return {
        "lines": lines,
        "start": offset,
        "end": offset + len(lines),
        "total_lines": total,
        "has_more": offset + len(lines) < total,
    }

5.2 流式读的策略

# 1) 按行读取上限（如 2000 行/次）
# 2) 按字节 seek（适合非文本）
# 3) 返回 has_more + 下次 offset（模型可翻页）
# 4) 行号标注（模型可以引用"第 120 行"）
# 大文件读不完没关系，模型拿到"需要的片段"即可

5.3 写入的流式

# 1) append 工具: 追加到文件尾（模型逐段写长文件）
# 2) 分段写: 模型分多次 append 大内容
# 3) 服务器限制单次写入大小（防一次写爆磁盘）
# 4) 写入前可先建目录
# 长文件的正确姿势: 多次小写 + 定期 flush，而非一次大写

6. 文本与二进制处理

文件不只是文本。日志、CSV、JSON、图片、压缩包各需要不同的处理策略。

6.1 文本文件的编码

# 编码处理
# 1) 默认 UTF-8，读取时 errors=replace（容错乱码）
# 2) 检测 BOM（UTF-8/16）并去除
# 3) 换行符归一化（CRLF/LF）
# 4) 非文本内容别当文本读（见二进制）
# 乱码比"读不到"更糟——先保证可读性

6.2 结构化文本工具

# 结构化文件用专门工具比 read_file 更省 token
# 1) read_json -> 按路径取字段（.a.b[0].c）
# 2) read_csv -> 列过滤 + 行数上限
# 3) parse_log -> 按关键字过滤行
# 结构化工具"只取需要的"，避免整文件进上下文
# 对文件内容"挑着读"是 token 优化的关键

6.3 二进制文件的处理

# 二进制文件不进上下文
# 1) 检测二进制（null 字节/魔数）
# 2) 返回元数据（大小/类型/行数）而非内容
# 3) 图片可用 MCP 的 image 内容类型传给视觉模型
# 4) 压缩包/Office 文档用专用解析工具提取文本
# 原则: 模型需要的是"文件的语义"而不是"文件的字节"

7. 文件搜索与 glob

让模型找到文件，是文件系统工具的高频需求。搜索要在授权根内、控制结果量。

7.1 glob 工具

# 1) glob(pattern): 支持 * / ** / {a,b}
# 2) 限制返回条数（如 500）
# 3) 结果按目录分组展示
# 4) 排除隐藏目录/大目录（可选）
# glob 是"让模型自己找文件"的入口，别让它翻整个 /var

7.2 内容搜索（grep）

# 在授权根内按内容搜文件
async def grep_text(pattern: str, root: str = "", max_hits: int = 50):
    safe = resolve_safe(root or ".", roots)
    hits = []
    for p in iter_files(safe, max_depth=4):
        for lineno, line in p.grep(pattern):
            hits.append(f"{p}:{lineno}:{line[:200]}")
            if len(hits) >= max_hits:
                return {"hits": hits, "truncated": True}
    return {"hits": hits, "truncated": False}

7.3 搜索的边界

# 1) 深度限制（默认 3-4 层）
# 2) 排除目录（node_modules/.git/dist）
# 3) 结果截断 + 摘要
# 4) 命中数超限返回"还有更多"
# 搜索也受 token 预算约束——返回"证据"而非"清单"

8. 临时文件与生命周期

模型的工作流经常产生中间文件：下载、解压、生成草稿。临时文件管理不好会泄漏或堆积。

8.1 临时目录约定

# 1) 固定临时根（/tmp/mcp-workspace）
# 2) 每个会话一个子目录（session_id）
# 3) 会话结束/空闲超时清理
# 4) 临时文件默认不共享（防跨会话泄漏）
# 临时目录 = 模型工作的"草稿纸"，用后即焚

8.2 生命周期管理

# 1) 服务器启动时清理过期临时目录
# 2) 空闲超时（如 24h）自动清理
# 3) 大临时文件提前删除（磁盘水位告警）
# 4) 审计临时文件的创建/删除
# 临时文件的安全要点: 不留在授权根外、不跨会话、不堆积

8.3 下载与外部文件

# 如果服务器有下载能力
# 1) 下载目录必须在授权根内
# 2) 限制文件大小（如 50MB）
# 3) 校验类型（MIME 白名单）
# 4) 恶意文件不进模型上下文（只给元数据/摘要）
# 外部文件进入工作区要过"安检"

9. 生产实践

9.1 部署形态

# 文件工具的部署考量
# 1) stdio 本地: 模型与文件同机（桌面场景）
# 2) 远程端点: 需把授权根映射到远程工作区 + OAuth
# 3) 容器: 授权目录挂载为卷，只读 + 写挂载分开
# 4) 多个根目录时用命名空间（/data-A, /data-B）
# 部署决定边界: 容器挂载是最容易实现的物理边界

9.2 监控与审计

# 指标
# 1) 读/写/删操作次数
# 2) 越界拒绝次数（路径穿越尝试）
# 3) 大文件读取（发现"整文件拖进上下文"）
# 4) 临时目录体积
# 审计
# 每次写/删: 谁、哪个会话、哪个文件、原哈希
# 越界拒绝是高价值告警信号（要么模型乱来，要么有人试探）

9.3 工具设计检查清单

# ☐ 根目录白名单（授权根集合）
# ☐ 路径 resolve_safe + 再校验（防穿越/软链）
# ☐ 读/写/删工具分离，删默认关闭
# ☐ 大文件分页读取（行号 + has_more）
# ☐ 二进制不进上下文
# ☐ 临时目录按会话隔离 + 清理
# ☐ 覆盖保护 + 回收站
# ☐ 审计与越界告警

10. 常见陷阱

• 路径不规范化：直接拿原始路径操作，../ 逃逸——必须 resolve + 再校验。
• 忽略符号链接：软链指向授权根外，读取越界——解析软链并校验最终目标。
• 整个文件读进上下文：读 100MB 日志 token 爆炸——分页 + 按需。
• 删除直接 rm：误删无法挽回——回收站 + 确认 + 审计。
• 临时文件不清理：跨会话泄漏 + 磁盘堆积——会话隔离 + 定时清理。
• 二进制当文本读：乱码污染上下文——检测并返回元数据。
• 只用路径白名单：忘了账号/容器层的物理边界——沙箱叠加。
• 搜索无限制：grep 全盘 + 深度无限——深度限制 + 排除目录 + 截断。

11. 总结

文件系统 MCP 工具的安全工程，核心是边界强制 + 按需取用：用根目录白名单和 VFS 锁定活动范围，用路径规范化与软链解析堵住穿越，用读写删分离和回收站守住破坏底线，用分页读取、结构化挑读和二进制识别控制 token 与语义污染，用会话隔离的临时目录管好中间产物。文件工具让模型真正「动手做事」，但只有把安全边界做成硬约束、把文件访问做成按需的流式操作，模型才值得被信任去碰真实文件系统——否则，一次穿越、一次误删，就足以让「智能助手」变成「生产事故制造机」。