Skip to main content
Glama
mcp-gate

mcp-gate

by jbisaccia-9

mcp-gate

ci

一个路径就是一条请求。根目录边界就是保证。

MCP 文件访问服务器通过 根目录(roots)——一组已授权的目录——来规定模型可以访问哪些文件。mcp-gate 演示了 告诉 服务器停留在其根目录内与 强制执行 这一点之间的区别:同一套攻击测试会针对两个版本运行,一个版本只有一条指令,另一个版本在读取任何文件之前先对每个路径进行规范化,并检查它是否处于边界之内。一个会泄露,一个能守住。两个方向都在 CI 中得到验证。

这是对 Anthropic 高级 MCP 材料中概念的独立实现,旨在明确展示三件事:

能力

体现位置

高级 MCP 服务器

src/mcp_gate/server.py —— 一个 FastMCP 服务器,提供类型化工具(list_roots, read_file, list_dir, summarize_file),并支持结构化错误和服务器发起的 采样(ctx.session.create_message),这样服务器可以请求 客户端 运行模型。

日志与进度

每个工具在运行时都会流式发送 MCP 日志通知(ctx.info)和 进度(ctx.report_progress)——包括记录请求在边界被阻断的准确时刻。src/mcp_gate/client.py 展示了匹配的 logging_callback / sampling_callback。

访问控制

src/mcp_gate/boundary.py —— 就是保证:.. 穿越、绝对路径、符号链接逃逸以及 %2e 编码的穿越,都会在根目录检查 之前 全部规范化。这就是门。

两种模式

模式

判断方式

结果

prompt(非安全控制)

系统提示词中的指令仅表示“只读取根目录下的文件”,但路径仍按原样打开。

泄露 —— 朴素的路径处理器是一个刻意设计的最坏情况对照。

boundary(强制执行)

每个路径先解码,然后通过 realpath 解析(折叠 .. 并跟随符号链接),最后必须位于某个已授权的根目录之内。

阻止 —— 越界请求在打开任何文件之前就会被拒绝。

攻击套件

攻击

prompt 模式

boundary 模式

direct_ask(一个合法的根目录内文件)

已返回 ✓

已返回 ✓

dotdot_traversal(../out_of_bounds/secret.txt)

泄露

已阻止

absolute_path(指向秘密文件的绝对路径)

泄露

已阻止

symlink_escape(沙箱内指向外部的符号链接)

泄露

已阻止

encoded_traversal(%2e%2e/...)

泄露

已阻止

direct_ask 在 两种 模式下都能成功,这正是“欺骗”之处:对提示层安全性进行快速的手动测试看起来是安全的,然后在你没有尝试过的攻击下失败。

Related MCP server: personal-mcp-bridge

门禁(CI 强制,双向)

python -m mcp_gate gate boundary   # exit 0 only if 0 escapes
python -m mcp_gate gate prompt      # exit 0 only if the leak is still demonstrated
python -m mcp_gate suite            # both halves must hold

如果 gate prompt 未能泄露,就意味着演示已经失去意义(如果非安全模式也能通过,“安全”结果也就毫无意义),所以 CI 同样会将该情况视为构建失败。

快速开始

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

pytest -q
python -m mcp_gate gate boundary
python -m mcp_gate gate prompt
python -m mcp_gate suite

运行实时 MCP 服务器 + 客户端演示(需要 pip install -e ".[demo]" 并在环境变量中配置 ANTHROPIC_API_KEY 以支持采样工具):

python -m mcp_gate serve ./data/sandbox      # start the server over stdio
python -m mcp_gate.client ./data/sandbox     # drive it: logs, progress, sampling, a blocked attack

参见 RESULTS.md 获取捕获的输出——其中每个代码块都是真实的命令输出,由 scripts/make_results.py 重新生成,从未手动编辑。

说明

  • data/ 下的所有数据都是虚构的;data/out_of_bounds/secret.txt 是“服务器绝不能提供的文件”的替代品。

  • 属于 -gate 家族:一切都要先通过门禁,否则不会发布。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables safe, read-only browsing of allowlisted local directories through MCP, providing tools to list roots, read files, and search text.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides safe, allowlisted local filesystem access for MCP-compatible AI clients, enabling directory listing, file reading/writing (with byte limits), and text search while blocking paths outside approved roots and symlink escapes.
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables secure filesystem operations (read, write, list, move, search files/directories) through the Model Context Protocol, with dynamic directory access control via MCP Roots.
      -