⚠️ 此仓库已迁移。 后续开发请移至 ScopeBlind/scopeblind-gateway。

此个人分支可能落后于官方仓库。请使用组织仓库提交问题、拉取请求并获取最新代码。

protect-mcp

MCP 服务器安全网关。默认以影子模式记录日志，支持按工具策略、可选的本地 Ed25519 签名收据，以及便于验证的审计输出。

当前 CLI 路径： 将任何 stdio MCP 服务器包装为透明代理。在影子模式下，它会记录所有 tools/call 请求并放行所有内容。添加策略文件以实施按工具规则。运行 protect-mcp init 生成本地签名密钥和配置，以便网关也能输出签名收据。

快速开始

# 将现有的 OpenClaw / MCP 配置包装成可用包
npx @scopeblind/passport wrap --runtime openclaw --config ./openclaw.json --policy email-safe

# 影子模式 — 记录每次工具调用，不强制任何策略
npx protect-mcp -- node my-server.js

# 生成密钥 + 配置模板用于本地签名
npx protect-mcp init

# 影子模式并启用本地签名
npx protect-mcp --policy protect-mcp.json -- node my-server.js

# 强制模式
npx protect-mcp --policy protect-mcp.json --enforce -- node my-server.js

# 导出可离线验证的审计包
npx protect-mcp bundle --output audit.json

功能说明

protect-mcp 作为 stdio 代理位于您的 MCP 客户端和服务器之间：

MCP 客户端 ←stdin/stdout→ protect-mcp ←stdin/stdout→ 您的 MCP 服务器

它拦截 tools/call JSON-RPC 请求，并执行以下操作：

影子模式（默认）：记录每次工具调用并放行所有内容
强制模式：应用按工具策略规则，例如 block、rate_limit 和 min_tier
可选的本地签名：配置签名后，会在结构化日志旁输出 Ed25519 签名的收据

所有其他 MCP 消息（initialize、tools/list、通知）均透明传递。

当前提供功能

按工具策略 — 阻止破坏性工具、限制昂贵工具的速率、附加最低层级要求
结构化决策日志 — 每次决策都会以 [PROTECT_MCP] 前缀输出到 stderr
可选的本地签名收据 — 当使用包含 signing.key_path 的策略运行时生成，持久化到 .protect-mcp-receipts.jsonl，并通过 http://127.0.0.1:9876/receipts 暴露
离线验证 — 使用 npx @veritasacta/verify 验证收据或包
无需注册账号 — 本地密钥、本地策略、本地进程

当前能力边界

在推广或向用户介绍前，请注意以下几点：

签名在单纯的 npx protect-mcp -- ... 路径上不会自动启用。 该路径会在影子模式下记录决策。如需本地签名，请先运行 npx protect-mcp init，然后使用生成的策略文件启动网关。
层级感知策略检查已生效，但清单准入尚未集成到默认 CLI/stdio 路径。 CLI 默认将会话设为 unknown，除非主机集成通过编程方式调用准入 API。
凭据配置目前会验证环境变量后端的凭据引用，并在日志/收据中记录凭据标签。 向任意 stdio 工具注入通用每次调用凭据的功能是适配器特定的，默认代理路径不执行此操作。
外部 PDP 适配器和审计包辅助工具已作为导出工具存在。 它们尚未完全集成到默认 CLI 路径中。

策略文件

{
  "default_tier": "unknown",
  "tools": {
    "dangerous_tool": { "block": true },
    "admin_tool": { "min_tier": "signed-known", "rate_limit": "5/hour" },
    "read_tool": { "require": "any", "rate_limit": "100/hour" },
    "*": { "rate_limit": "500/hour" }
  },
  "signing": {
    "key_path": "./keys/gateway.json",
    "issuer": "protect-mcp",
    "enabled": true
  },
  "credentials": {
    "internal_api": {
      "inject": "env",
      "name": "INTERNAL_API_KEY",
      "value_env": "INTERNAL_API_KEY"
    }
  }
}

策略规则

工具名称精确匹配，"*" 用作通配符回退。

MCP 客户端配置

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "my-protected-server": {
      "command": "npx",
      "args": [
        "-y", "protect-mcp",
        "--policy", "/path/to/protect-mcp.json",
        "--enforce",
        "--", "node", "my-server.js"
      ]
    }
  }
}

Cursor / VS Code

相同模式 — 将服务器命令替换为 protect-mcp 进行包装。

CLI 选项

protect-mcp [options] -- <command> [args...]
protect-mcp init

命令：
  init              生成 Ed25519 密钥对 + 配置模板
  status            显示决策统计信息和本地 passport 身份
  digest            生成本地人类可读摘要
  receipts          显示最近持久化的签名收据
  bundle            导出可离线验证的审计包

选项：
  --policy <path>   策略/配置 JSON 文件
  --slug <slug>     用于日志/收据的服务标识符
  --enforce         启用强制模式（默认：影子）
  --verbose         启用调试日志
  --help            显示帮助

编程钩子

该库还暴露了尚未集成到默认 CLI 路径的原语：

import {
  ProtectGateway,
  loadPolicy,
  evaluateTier,
  meetsMinTier,
  resolveCredential,
  initSigning,
  signDecision,
  queryExternalPDP,
  buildDecisionContext,
  createAuditBundle,
} from 'protect-mcp';

如果您需要添加以下功能，可以使用这些原语：

会话开始前的清单准入
外部 PDP（OPA、Cerbos 或通用 HTTP Webhook）
自定义凭据代理集成
基于您自己的收据存储的审计包导出

决策日志与收据

每次工具调用都会向 stderr 输出结构化 JSON：

[PROTECT_MCP] {"v":2,"tool":"read_file","decision":"allow","reason_code":"observe_mode","policy_digest":"none","mode":"shadow","timestamp":1710000000}

配置签名后，会跟随一个签名收据：

[PROTECT_MCP_RECEIPT] {"v":2,"type":"decision_receipt","algorithm":"ed25519","kid":"...","issuer":"protect-mcp","issued_at":"2026-03-22T00:00:00Z","payload":{"tool":"read_file","decision":"allow","policy_digest":"...","mode":"shadow","request_id":"..."},"signature":"..."}

使用 CLI 验证：npx @veritasacta/verify receipt.json 在浏览器中验证：scopeblind.com/verify

审计包

该包导出了一个用于自包含审计包的辅助工具：

{
  "format": "scopeblind:audit-bundle",
  "version": 1,
  "tenant": "my-service",
  "receipts": ["..."],
  "verification": {
    "algorithm": "ed25519",
    "signing_keys": ["..."]
  }
}

使用 createAuditBundle() 围绕您自己收集的签名收据。

理念

影子优先。 在强制执行前，先观察代理的行为。
收据优于仅仪表盘日志。 签名工件应可独立验证。
保持声明范围紧凑。 默认 CLI 路径尚未实现长期架构中的所有功能。
在现有身份验证之上分层。 无需拆除现有堆栈即可添加控制和证据。

基于事件的策略包

与 protect-mcp 一起提供 — 每个包可阻止一次真实攻击：

npx protect-mcp --policy node_modules/protect-mcp/policies/clinejection.json -- node server.js

完整的 OWASP 代理十大映射：scopeblind.com/docs/owasp

BYOPE：外部策略引擎

支持 OPA、Cerbos、Cedar (AWS AgentCore) 以及通用 HTTP 端点：

{
  "policy_engine": "hybrid",
  "external": {
    "endpoint": "http://localhost:8181/v1/data/mcp/allow",
    "format": "cedar",
    "timeout_ms": 200,
    "fallback": "deny"
  }
}

标准与知识产权

IETF 互联网草案：draft-farley-acta-signed-receipts-00 — 机器间访问控制的签名决策收据
专利状态：4 项澳大利亚临时专利申请（2025-2026），涵盖可配置公开的决策收据、工具调用网关、代理清单和可移植身份
验证工具：MIT 许可 — npx @veritasacta/verify --self-test

许可证

MIT — 可自由使用、修改、分发和构建，无限制。

scopeblind.com · npm · GitHub · IETF 草案

`block`	`true`	显式阻止此工具
`require`	`"any"`, `"none"`	基本访问要求
`min_tier`	`"unknown"`, `"signed-known"`, `"evidenced"`, `"privileged"`	如果主机设置了准入状态，则所需的最低层级
`rate_limit`	`"N/unit"`	速率限制（例如 `"5/hour"`、`"100/day"`）

`clinejection.json`	CVE-2025-6514：MCP OAuth 代理劫持（43.7 万个环境）	A01, A03
`terraform-destroy.json`	自主 Terraform 代理销毁生产环境	A05, A06
`github-mcp-hijack.json`	通过精心构造的 GitHub Issue 进行提示注入	A01, A02, A03
`data-exfiltration.json`	代理通过滥用出站工具窃取数据	A02, A04
`financial-safe.json`	未经授权的金融交易	A05, A06

scopeblind-gateway

最受欢迎