guardian-mcp

@odingard/guardian-mcp

MCP 服务会通过 Guardian 路由 Agent 的工具调用。Guardian 是面向自主 AI 的人类权限基础设施。每次工具调用在执行任何操作之前，都会获得确定性的 ALLOW / ASK / DENY 决策；DENY 表示操作永远不会执行，ASK 则会暂缓操作，直到人类批准。

安装

npm i -g @odingard/guardian-mcp

配置 MCP 客户端

{
  "mcpServers": {
    "guardian": {
      "command": "guardian-mcp",
      "env": {
        "GUARDIAN_BASE_URL": "https://guardian-api.odingard.com",
        "GUARDIAN_AGENT_CREDENTIAL": "gak_…",
        "GUARDIAN_CONNECTION_ID": "con_…"
      }
    }
  }
}

GUARDIAN_ADAPTER_ID 可用于覆盖工具适配器。

工具

工具	功能
guardian_invoke_tool	提议一次工具调用。ALLOW 会执行并返回回执；ASK 会返回一个等待人类批准的 requestId；DENY 会拒绝请求并提供原因代码。
guardian_claim	根据 requestId 领取已批准的 ASK，执行调用并返回回执。
guardian_receipt	获取某个请求的机器可读证据回执。

没有 Guardian 权限凭证，任何操作都不会执行——模型的输出只是提议，而非操作。

管理现有 MCP 服务：guardian-mcp proxy (0.3)

将 Guardian 部署在你已使用的任何 stdio MCP 服务前面，例如 WhatsApp、Stripe、Shopify、文件系统或数据库。客户端看到的上游服务工具保持不变，且每次调用都会先经过决策：

{
  "mcpServers": {
    "whatsapp-governed": {
      "command": "guardian-mcp",
      "args": ["proxy", "--", "npx", "-y", "your-whatsapp-mcp-server"],
      "env": {
        "GUARDIAN_BASE_URL": "https://guardian-api.odingard.com",
        "GUARDIAN_AGENT_CREDENTIAL": "gac1.…",
        "GUARDIAN_CONNECTION_ID": "con_…",
        "WHATSAPP_TOKEN": "…"
      }
    }
  }
}

决策	处理方式
ALLOW	调用会转发到上游服务，然后兑换权限凭证并记录回执。
ASK	不会转发任何内容。确切的调用会通过 requestId 暂存；人类批准后，guardian_claim 会将该调用原样转发一次。
DENY	永远不会转发任何内容。Guardian 无法访问时也一样。

• 工具列表中会添加 guardian_claim 和 guardian_receipt。
• 上游服务不会收到 GUARDIAN_* 设置，因此无法看到 Agent 凭证。
• **决策门控：**允许的调用会先在上游执行，然后再兑换权限凭证。如果兑换时遭到拒绝，会将其报告为事件（localEffectRan: true），绝不会报告为成功。
• **首次运行设置：**在 Guardian 控制台中，连接一个工具服务，并将每个上游工具添加为“My own code (record-only)”。然后为 Agent 授权这些工具。
  • 从 0.3.1 起，代理不会尝试自行注册工具。
  • GUARDIAN_AUTO_REGISTER=true 可重新启用此功能，但除非 Agent 的授权中固定了 mcp.install，否则会被拒绝。
  • Guardian 拒绝请求时，结果会说明需要修复什么。
• 暂存的调用保存在代理进程中。重启代理会丢弃这些调用，且不会转发任何内容。

guardian-mcp --help 会显示用法。缺少设置时会显示一行指出缺少项的消息，而不是堆栈跟踪。

查看即将由你管控的内容：guardian-mcp tools

将服务置于代理后面之前，先列出它的工具以及每个工具建议采用的 Guardian 模式。此操作不需要 Guardian 凭据：

npx -y @odingard/guardian-mcp tools -- npx -y @modelcontextprotocol/server-filesystem ./data

Tool            Suggested     Why
read_file       Allow         server marks it read-only
write_file      Ask me first  "write" may change something
delete_branch   Ask me first  server marks it destructive
createIssue     Ask me first  "create" may change something  ⚠ name not accepted by Guardian

建议模式的生成方式：

• 首先使用服务自身的 MCP 注解（readOnlyHint、destructiveHint）。
• 否则根据工具的动词判断。get、list 和 search 建议设为 Allow；其他工具建议设为 Ask。

这些仅是建议：你需要在控制台中设置实际模式。违反 Guardian 命名规则的工具名称会被标记，因为对这些工具的每次调用都会被拒绝。添加 --json 以输出机器可读的结果。

许可证

Apache-2.0。规范开发在 Odingard Guardian monorepo 中进行。