sweep-mcp

sweep-mcp

**简单来说：**它可以让 AI 清理开发者机器上日积月累的垃圾文件夹，同时确保它无法触碰其他任何东西。它只在你指定的文件夹中运行，只会删除自己找到的内容，并会在删除前一瞬间再次检查——因此，没人能在最后一刻替换目标。

一个用于删除目录的 MCP 服务，以及一套防护措施，确保将这一能力交给大语言模型时不至于鲁莽行事。

它通过模型上下文协议提供 sweep，让 Agent 能查找并清理 node_modules、.venv、target、__pycache__ 等目录。有意思的并不是删除操作，而是执行删除前必须满足的所有条件。

2026 年发布的一项研究发现，在扫描的 1,808 个 MCP 服务中，66% 存在安全问题；仅一个季度，就有 30 多个 CVE 针对 MCP 实现提交。本仓库采用了截然不同的思路来编写 MCP 服务：先做好拒绝机制，再实现功能。

---

威胁模型

一个能够删除目录的 MCP 服务，就像一把上膛的枪，指向进程能够访问的任何位置。可能出错的情况有五种，每种情况都有对应的控制措施和测试来验证。

风险	控制措施	测试
Agent 扫描 / 或 C:\ 并删除整台机器上的内容	根目录允许列表，在服务启动时固定。Agent 无法设置、扩展它，也无法访问其范围之外的内容。未配置根目录 → 拒绝所有请求	test_empty_allowlist_denies_every_path
使用 ../../ 或符号链接逃出允许列表	每个路径都会在进行范围检查之前调用 resolve()，因此检查依据是路径的实际指向	test_dotdot_traversal_is_denied、test_symlink_pointing_outside_root_is_denied
Agent 要求删除从未扫描过的路径	**reclaim 接受的是 ID，而不是路径。**API 中没有任何可以通过路径删除内容的入口	test_there_is_no_way_to_delete_by_path
目录在扫描和删除之间发生变化	删除时，会针对实时文件系统重新检查每个发现项——仍在允许范围内、仍是目录、仍不是链接，标记文件仍然存在	test_revalidate_refuses_a_directory_swapped_for_a_symlink
意外删除	**默认启用试运行。**只有 confirm="delete" 完全匹配时才会删除；其他任何内容都视为否	test_a_wrong_confirmation_string_stays_a_dry_run

另外还有两个较小的控制措施，出于同样的考虑：

• **工单 ID 是随机的，不是顺序编号。**例如 f-3a91c02b77de，而不是 1。可计数的 ID 会诱使 Agent 一直遍历，直到有东西被删除。
• **工具描述是字符串字面量。**它们绝不会由从磁盘读取的内容拼接而成，因此名为 ignore-previous-instructions 的目录会作为数据而不是句子传给模型（test_tool_descriptions_are_static）。

不提供保护的情形

上述控制措施的保护范围仅限于其涵盖的内容，不多不少。

• 根目录配置错误。 使用 --root / 启动后，它就会顺着你的文件系统一路操作。允许列表的安全性取决于你放入其中的内容，这里不会对这个选择进行任何二次核验。
• 恶意客户端。 防护机制限制的是可以删除什么，而不是谁在请求。客户端先正常扫描，再正常确认，就会得到它所请求的一切。
• 被说服去这么做的 Agent。 静态工具描述会将文件系统内容排除在模型指令之外，但如果 Agent 出于自身的不良理由，决定删除它确实找到的 node_modules，这里没有任何办法阻止它。
• 最后几毫秒。 revalidate() 缩短了检查和删除之间的时间窗口，但无法将其关闭。要彻底关闭这个窗口，需要在整个操作期间持有目录文件描述符，而 shutil.rmtree 无法跨平台提供这种能力。这是真实存在的竞态，只是风险更小，而非不存在。
• Python 3.11 中的 Windows junction。 os.path.isjunction 是在 3.12 中引入的。在更低版本中，junction 检测会退化为仅检测符号链接——sweep 本身也做出了相同的折中；这里把它明确说明，而不是埋在文档里。
• 权限。 这不是沙盒。它以启动它的用户身份运行。

扫描结果

于 2026 年 8 月 18 日使用 agent-audit 0.19.2 运行。

静态扫描——0 个发现，风险评分 0.0（LOW），7 个文件。

首次扫描时出现了一项低风险发现：AGENT-110，发行包未排除源映射文件。此包不含 JavaScript，因此没有可泄露的源映射，但现在仍在 pyproject.toml 中声明了排除规则——毫无成本；和供应链检查清单争论，纯属浪费任何人的下午时光。

工具检查——0 项工具发现。 在这 3 个定义中，均未检测到工具投毒、跨源或 rug-pull 模式。

值得复述一下它给出的风险评级，因为这些评级以一种很有启发性的方式错了：

工具	评级	推断的权限
list_targets	MEDIUM	SHELL_EXEC、FILE_READ
scan	HIGH	FILE_DELETE、SHELL_EXEC、FILE_READ
reclaim	HIGH	FILE_DELETE、SHELL_EXEC、FILE_READ

scan 无法删除任何内容。它是只读的，声明了 read_only_hint=True，而且有测试确保它始终如此。它之所以被评为 HIGH，并被赋予 FILE_DELETE 权限，是因为扫描器会根据描述中的关键词进行匹配，而此服务的 scan 描述中包含这样一句话：

“只读：此操作绝不会删除任何内容。”

删除一词出现在 FILE_DELETE 的关键词列表中。SHELL_EXEC 则来自“重新生成它的命令”这句话中的命令一词——此服务根本不会执行任何 shell 命令。

可以改写描述来获得更好的评分。但并没有这么做，因为描述的受众是需要决定是否调用此工具的语言模型，而“此操作绝不会删除任何内容”是其中最有用的一句话。关键词扫描器是烟雾探测器，不是裁判——扫描结果干净值得争取，也值得公布；而根据文本字符串匹配得出的评级，并不能证明行为如何，无论评级高低。

我们尝试了 2 个扫描器，其中 1 个无法运行：Invariant Labs 的 mcp-scan 在 Snyk 收购后更名为 snyk-agent-scan，现在需要 SNYK_TOKEN。Cisco 的 mcp-scanner 未发布到 PyPI。agent-audit 自带的 stdio 传输在 Windows 上对接此服务时也会超时，而手动与同一二进制文件完成握手只需几毫秒，因此我们直接将真实的 tools/list 输出交给了它的分析器——绕过的是传输层，而非分析过程。

安装

pip install sweep-mcp

从源代码检出目录安装：pip install -e .

配置

服务接受一个或多个 --root 目录。它没有默认值。 不指定根目录就启动会报错，而不会去扫描 所有内容：

{
  "mcpServers": {
    "sweep": {
      "command": "sweep-mcp",
      "args": ["--root", "/home/you/code", "--root", "/home/you/work"]
    }
  }
}

工具

工具	是否有破坏性	功能
list_targets	否	列出它知道如何回收的目录类型，以及重新生成各目录的命令
scan	否	在根目录内的路径下查找可回收的目录。返回 ID、大小和重新生成命令
reclaim	是	按 ID 删除找到的目录。除非设置 confirm="delete"，否则为试运行

这三个工具都带有 MCP ToolAnnotations，因此，对于会在执行破坏性工具前要求确认的客户端来说，所需信息一应俱全：reclaim 声明了 destructive_hint=True，另外两个声明了 read_only_hint=True。测试套件也会断言这一点——提示若悄悄退化，还不如没有。

一个会话

scan(path="/home/you/code")
  → 12 finds, 3.4 GB
    f-3a91c02b77de  /home/you/code/api/node_modules   1.9 GB  npm install
    f-8e0244fd1b6c  /home/you/code/ml/.venv           842 MB  python -m venv .venv

reclaim(ids=["f-3a91c02b77de"])
  → dry_run: true
    would_delete: 1 path, 1.9 GB
    note: Nothing was deleted. Call again with confirm='delete'.

reclaim(ids=["f-3a91c02b77de"], confirm="delete")
  → deleted: 1 path, reclaimed 1.9 GB

测试

共 38 项测试。34 项可在 Windows 上运行；38 项都可在 Linux 上运行。

其中 4 项在本地会跳过，因为它们需要创建符号链接，而 Windows 在未启用开发者模式时会拒绝创建——其中一项测试还覆盖了扫描与删除之间的交换攻击，这也是这里最重要的一项测试。如果悄悄跳过它，测试套件就会沦为摆设，因此 CI 会在 Linux 上运行，并在这些测试被报告为跳过时让构建失败。

pytest -q --cov=sweep_mcp

覆盖率为 83%。未覆盖部分主要是 main() 和 argparse 配置；测试套件改为通过 build_server 驱动它们——传输层最不值得模拟，也最不可能是造成损害的环节。

测试套件中没有任何地方会模拟文件系统。用模拟的 Path 可以通过这里的每一项测试，但服务仍可能删除错误的目录。

目录结构

src/sweep_mcp/
  guard.py    212 lines - the allowlist, the tickets, the re-check. Imports no MCP.
  server.py   280 lines - three tools. Translation only.
tests/
  test_guard.py    23 tests - one per rule, each named for the attack it stands in for
  test_server.py   15 tests - driven through call_tool, the way a client would

guard.py 刻意不依赖 MCP。任何可能导致用户数据丢失的决策，都可以在没有客户端、传输层或 Agent 参与的情况下进行测试。如果某条规则看起来是在 server.py 中实施的，那就是一个 Bug——它应该放在下一层，这样测试才能覆盖到它。

许可证

MIT。

作者

由 Leslie Kadenge 开发。我独立审查 MCP 服务的安全性；我对 13 个生产环境服务进行的公开调查见 les-k.github.io/field-notes.html。