为 AI 代理工具调用提供本地策略执行和签名决策回执。
开发者页面 · 快速开始 · 代理配置 · 策略包 · 示例记录 · 集成 · 文档 · 贡献
将网关置于 MCP 客户端与其工具服务器之间,或在编码代理中使用其钩子。审查 Cedar 策略,启用执行,并保留决策的签名记录。本地评估和验证无需 ScopeBlind 账户,也不会发送任何决策遥测数据。
--enforce。网关覆盖通过它路由的调用。它不是操作系统沙箱,签名回执也不能证明某个操作已执行或没有遗漏任何操作。安全策略描述了边界和报告流程。
一次真实的本地运行:评估两个提议的调用,对决策签名,验证回执,然后更改一个已签名的决策并再次检查。


在新目录中使用 Node.js 22 和 npm。安装固定版本的网关和验证器:
mkdir protect-mcp-demo
cd protect-mcp-demo
npm init -y
npm install --save-exact [email protected] @veritasacta/[email protected]
此示例评估两个提议的调用并对其决策进行签名。它不会执行任一工具,也不会运行 git push。安装之后的所有操作均在本地进行。
# Create a starter policy and a private signing key.
npx --no-install protect-mcp init --starter
# A normal read is allowed; a force-push to main is denied (exit 2).
npx --no-install protect-mcp evaluate --policy ./protect.cedar --tool Read --input '{"path":"README.md"}'
npx --no-install protect-mcp evaluate --policy ./protect.cedar --tool Bash --input '{"command":"git push --force origin main"}' || test "$?" -eq 2
# Evaluate again at signing time and record both decisions, in order.
npx --no-install protect-mcp sign --cedar builtin:starter --tool Read --input '{"path":"README.md"}' --key ./protect-mcp.key --receipts ./receipts
npx --no-install protect-mcp sign --cedar builtin:starter --tool Bash --input '{"command":"git push --force origin main"}' --key ./protect-mcp.key --receipts ./receipts
# Take only the public key from the key you generated, not from the receipt.
PROTECT_MCP_PUBLIC_KEY=$(node -p 'JSON.parse(require("fs").readFileSync("protect-mcp.key", "utf8")).publicKey')
npx --no-install verify --replay-chain ./receipts/receipts.jsonl --key "$PROTECT_MCP_PUBLIC_KEY" --json
# Change the signed deny to allow. The original receipt log stays intact.
node -e 'const fs=require("fs");const r=JSON.parse(fs.readFileSync("receipts/receipts.jsonl","utf8").trim().split("\n")[1]);r.payload.decision="allow";fs.writeFileSync("tampered.json",JSON.stringify(r))'
npx --no-install verify tampered.json --key "$PROTECT_MCP_PUBLIC_KEY" --json || test "$?" -eq 1
预期结果:先 allow,再 deny;两个原始回执签名及其链接均验证通过;被修改的回执报告 invalid_signature。请妥善保管 protect-mcp.key 的私密性。若要验证他人的记录,请通过独立的可信渠道获取其预期的公钥。
验证器的退出码为 0:有效、1:无效、2:未检查/错误。无效结果不一定意味着篡改:错误的预期密钥同样会导致验证失败。链式重放会检查所提供的链接;它并不能证明你已收到完整的历史记录。
CI 会针对打包后的候选版本和固定版本的已发布验证器运行此示例。参见验证与发布。
选择与你的宿主环境及所需覆盖范围相匹配的集成方式。安装指导技能并不会启用强制执行。doctor 会检查本地配置;请通过一次真实的允许调用和一次真实的阻止调用来确认所选路径。
对于 Claude Code 插件,请先准备并启动本地网关,然后将其安装到你的项目中(Claude Code 2.1.295 或更高版本):
claude plugin install protect-mcp --marketplace ScopeBlind/scopeblind-gateway --scope project
当插件的 gate 不可用时,它会阻止被路由的工具调用。请选择插件或独立项目钩子,以免同一次调用被记录两次。
| 使用场景 | 从这里开始 |
|---|---|
| 包装现有的 MCP 服务器 | MCP 设置与 shadow-to-enforce 工作流 |
| Claude Code 强制执行插件 | 插件设置与本地 gate |
| Claude Code 项目钩子 | 钩子设置 |
| Cursor 项目预览 | 显式设置、工具映射与宿主检查 |
| ChatGPT / Codex 助手预览 | 设置指南与无害验证演示,不使用钩子 |
| 现有的 Claude 目录指南插件 | 已发布的插件源码,与强制执行相互独立 |
| 将策略评估器作为 MCP 工具调用 | 作为 MCP 服务器的 gate |
| 托管 HTTP 网关 | HTTP 部署说明 |
宿主兼容性与发布状态将适配器测试与真实宿主验证区分开来。Cursor 和助手包属于预览版,并非公开目录条目。独立钩子格式修复随 0.32.4 发布;其变更日志列出了每种格式的变更内容。仅凭一个格式标志并不能确立可用的 Codex、Gemini 或 Hermes 集成。
对于现有的 MCP 服务器,请在与上述示例不同的目录中初始化其配置,然后使用你的服务器命令运行包装器:
npx --yes [email protected] init
npx --yes [email protected] --policy ./protect-mcp.json -- node your-mcp-server.js
这以 shadow 模式启动。在添加 --enforce 之前,请先审查观察到的调用和策略。wrap 会打印客户端配置并退出;它不是启动命令。完整设置说明。
入门 shell 规则会检查命令文本。它们是有用的防护措施,但可能会漏掉其他命令拼写方式,也可能匹配到无害的引号文本。在依赖它之前,请先查看入门策略的覆盖范围和限制。