list_dir(".")                     → 目录: sub
                                    文件: notes.txt
                                    文件: second.txt
read_file("notes.txt")            → 这是一份测试文件。...
write_file("backup.txt", "这是一份测试文件。...")  → 成功：已写入文件 backup.txt。

BASE_DIR = Path(__file__).resolve().parent / "sandbox"

def _safe(path: str) -> Path:
    target = (BASE_DIR / path).resolve()      # ① 拼接 + ② 展开
    if not target.is_relative_to(BASE_DIR):   # ③ 判断
        raise ValueError(f"Path escapes sandbox: {path}")
    return target                              # ④ 交付

攻击路径            : ...\sandbox\..\..\secret.txt
不 resolve 直接判断 : True      ← 放行了，防护完全失效
resolve 后判断      : False     ← 拦住了

if ".." in path: ...                          # ❌ 符号链接 / Windows 短名可绕过
if str(target).startswith(str(BASE_DIR)): ...  # ❌ 见下

Path('C:/ab').is_relative_to(Path('C:/a'))    →  False   ✅ 正确
'C:/ab'.startswith('C:/a')                     →  True    ❌ 误判

错误：文件不存在（nope.txt）。可以先调用 list_dir 看看有什么。
错误：notes.txt 是文件不是目录，请用 read_file。
错误：路径为空。请传入相对于 sandbox 根目录的路径（例如 notes.txt）。

错误：无法写入文件 deep/a.txt。      ← 模型不知道是权限、磁盘还是路径问题

# 方式一：只装运行时依赖
pip install fastmcp

# 方式二：按 pyproject.toml 的声明安装（依赖 + 本项目）
pip install -e .

# 直接运行（stdio，供 Host 调用）
python agent_mcp.py

# 用 CLI 查看它暴露了哪些工具
fastmcp list agent_mcp.py

# 命令行直接调一个工具
fastmcp call agent_mcp.py read_file path=notes.txt

# 正常读取
fastmcp call agent_mcp.py read_file path=notes.txt

# 越界 —— 应该被拒绝
fastmcp call agent_mcp.py read_file path=../secret.txt
fastmcp call agent_mcp.py read_file path=C:/Windows/win.ini

# 业务错误 —— 应该返回可读的提示
fastmcp call agent_mcp.py read_file path=nope.txt
fastmcp call agent_mcp.py read_file path=.

# 空路径
fastmcp call agent_mcp.py read_file path=

# 搜索（递归 + 行号）
fastmcp call agent_mcp.py search_content path=. keyword=hello

{
  "mcpServers": {
    "file-server": {
      "command": "python",
      "args": ["/绝对路径/agent_mcp.py"]
    }
  }
}

mcp-file-server/
├── agent_mcp.py       # Server 本体（四个工具 + _safe）
├── README.md
├── TEST-CASES.md      # 测试样本清单 + 分场景测试命令 + 问题记录
├── pyproject.toml
├── .gitignore
├── LICENSE
└── sandbox/           # 沙箱根目录 = BASE_DIR，模型只能在这里操作
    ├── notes.txt / second.txt      # 普通文本
    ├── empty.txt / blank.txt       # 0 字节 / 纯空白
    ├── gbk.txt / bom.txt           # GBK 编码 / UTF-8 BOM
    ├── crlf.txt                    # CRLF 换行
    ├── bin.dat                     # 假二进制 → 验证"读不了就跳过"
    ├── long.txt                    # needle 命中 60 行 → 验证结果上限
    ├── hello_big.txt               # 190 KB → 验证大文件截断
    ├── huge_line.txt               # 单行 50 KB → 验证单条截断
    ├── edge_20000.txt / edge_20001.txt   # 长度上限的边界值
    ├── no_extension / my notes.txt / 中文文件.txt
    ├── empty_dir/                  # 空目录 → 验证「（空目录）」
    ├── docs/ logs/                 # 子目录，验证递归
    ├── data/2026/09/report/         # 5 层深
    └── sub/deep/c.txt              # 关键词在第 2、4 行 → 验证递归 + 行号