🧾 mcp-proof

交付一个 MCP 服务器，附上收据。

一条命令审计任意 MCP 服务器——工具、资源和提示词，无论哪个协议时代、stdio 还是 Streamable HTTP——并交给你的客户端一份带指纹、可复现的交付报告，外加一套他们可以保留的 CI 回归套件。

English · 简体中文

对官方 MCP filesystem 服务器的一次真实审计：25 项一致性检查、MSSS 合规表、34 个回归夹具——全部通过。

✨ 你能得到什么

• 🔍 覆盖每个表面、横跨两个时代的线路级协议检查——mcp-proof 直接与你的服务器对话原始 JSON-RPC，并自动检测其时代：针对 2026-07-28 现代时代的 30 项检查（server/discover、_meta 信封强制、resultType、每个可缓存结果上的 ttlMs/cacheScope、-32022 版本拒绝、HTTP 路由头强制），以及针对 initialize 握手时代的 25 项检查——精确的错误码、模式有效性、结构化输出、stdout 卫生、分页安全、专用的资源与提示词通道，以及经过验证的负向探测：TOOL-07 发送可证明违反所声明 inputSchema 的输入，并在服务器正常应答时发出警告，同时引用最小复现器。两个方向都具备能力感知：服务器未通告的表面会被跳过，已通告的表面必须正常工作。

• 🛡️ 与公开标准挂钩的安全审计——6 项确定性检查（工具描述投毒、不可见/双向字符、凭据泄露、无约束的注入面、通告的 shell 执行），每项都映射到 24 项控制的 MCP Server Security Standard 的规范控制 ID，并在每份报告中以完整合规表形式呈现。

• 📼 你的客户端可以保留的回归套件——可在任一协议时代录制；带 SHA-256 溯源的金标夹具冻结服务器的行为；回放对每次漂移分级（BREAKING / VALUE / COSMETIC / LATENCY），理解结构化输出，保持有状态调用顺序，并附带可直接粘贴的 GitHub Actions 门禁。

• 📄 一份给人类和机器看的报告——自包含 HTML，带粘性导航、逐检查锚点（report.html#SEC-03）、关注/通过过滤器以及可折叠的 MSSS 矩阵；--pdf 用于打印。同一版本化模型以 --json（schema v1）、供任意 CI 使用的 --junit 以及供 GitHub 安全选项卡使用的 --sarif 形式输出。

• 🔁 设计上可复现——零 LLM 调用、零 API 密钥。每个哈希仅从行为计算——时间戳和延迟位于独立的、不参与哈希的观测层——因此相同的服务器行为产生相同的报告指纹，验收是验证而非信任。

• 🧯 注解优先的调用规划——MCP 工具注解在两个方向上都优先于名称启发式：readOnlyHint 拯救了正则可能过度拦截的只读工具，destructiveHint 捕获了它可能漏掉的修改器；未注解的工具回退到保守启发式。mcp-proof plan 在任何东西接触生产环境之前，精确展示自动基线化会调用什么以及基于什么依据；--include-destructive 和 --edge-cases 可选择更多。

• 📋 面向 CI 的契约差异对比——mcp-proof inspect 将所服务的表面（能力 + 工具 + 资源 + 提示词，完全分页）冻结为带指纹的清单；mcp-proof diff 将每次变更分类为 BREAKING / ADDITIVE / METADATA，并在存在破坏性变更时以非零退出码退出——模式收紧、枚举收窄、必填翻转、移除输出字段和削弱安全注解都算在内。

Related MCP server: MCProbe

🚀 快速开始

pip install git+https://github.com/YuCPbit/mcp-proof
mcp-proof run python my_server.py --fixtures fixtures/ --out report.html

改为审计一个正在运行的 HTTP 服务器？mcp-proof run --url http://localhost:8000/mcp --out report.html

退出码 0 意味着：所有 MUST 检查通过、零安全发现、零行为漂移——一行 CI 门禁。

mcp-proof plan python my_server.py                            # what would auto-baselining call, and why
mcp-proof record python my_server.py --fixtures fixtures/    # freeze the behavioural contract
mcp-proof replay --fixtures fixtures/ -- python my_server.py  # fail on any drift
mcp-proof inspect python my_server.py --out baseline.json     # freeze the contract surface
mcp-proof diff baseline.json current.json                     # BREAKING / ADDITIVE / METADATA, exit 1 on breaking

用内置的演示对——一个干净的服务器和一个植入了九处违规的服务器——在 60 秒内看到差异：

mcp-proof run python demo/good_server.py --fixtures demo/fixtures-good --out report-good.html   # → SHIP-READY
mcp-proof run python demo/bad_server.py --out report-bad.html                                    # → 5 MUST failures, 3 security findings

📊 真实审计，真实报告

🔬 三条通道

每条通道汇入同一份报告——而报告以按优先级排序的修复清单收尾，因此它同时充当修复计划。

📡 协议支持

现代通道已针对官方 v2 SDK 双向验证：官方客户端通过 server/discover 采用 mcp-proof 手工编写的现代测试服务器，而 mcp-proof 在两种传输方式上——stdio 和带 SSE 响应的 Streamable HTTP（scripts/crosscheck_modern_server.py）——对官方 v2 SDK 服务器全绿运行所有三条通道。

适用于任何语言编写的服务器——mcp-proof 与进程（或 URL）对话，而不是与你的代码库对话。

⚙️ 一步完成 CI

- uses: YuCPbit/mcp-proof@v0.5.0
  with:
    server-command: python my_server.py
    fixtures: fixtures/

除非服务器达到可交付状态，否则该任务失败，并留下 mcp-proof-report.html / .json / .junit.xml / .sarif 供上传。更喜欢原始命令？mcp-proof run … --junit r.xml --sarif r.sarif 加上 mcp-proof diff 就是同一个门禁。

🏗️ 基于审计干净的模板构建

是在构建服务器而不是审计服务器？templates/server-starter/ 是一个开箱即通过此审计的 fastmcp 服务器——受约束的输入模式、正确的错误语义、结构化输出，每个实践都标注了其满足的检查 ID。复制、实现你的工具、审计、带着报告交付。

🖥️ 平台

🗺️ 路线图

🔍 局限性

mcp-proof 证明的是可以用确定性方式证明的东西，并说明哪些是哪些：

• 安全检查覆盖可观察的协议和元数据表面。需要部署、源码或过程证据的 MSSS 控制项始终报告为人工审查——绝不会标记为通过。

• 自动基线化通过保守的名称/描述启发式规则对工具进行分类。在信任针对生产环境记录的基线之前，请先审查 fixtures 清单中的跳过列表。

• 语义正确性（答案意思是否正确？）按设计不在确定性核心范围内。

📄 许可证

MIT — MSSS 合规部分中的分类法遵循 MCP Server Security Standard（CC BY-SA 4.0）。