mcp-approval-queue

@opafex/mcp-approval-queue

用于 AI Agent 的人工介入审批门，作为 MCP 服务运行。

Agent 在执行有风险的操作前调用 request_approval。系统会评估操作的风险；除非操作符合你设置的规则，否则由你决定是否批准——通过 MCP 客户端显示的表单（MCP elicitation）或终端进行。Agent 会收到可据此采取行动的 proceed: true|false。

Agent 可以请求；只有人类才能批准。 模型没有可调用的批准、拒绝或添加规则工具。由受限 Agent 自己打开的审批门，就不是真正的审批门。

需要 Node.js 20+。

快速开始

将其添加到客户端的 MCP 配置中（对于 Claude Code，添加到项目根目录下的 .mcp.json）：

{
  "mcpServers": {
    "approval-queue": {
      "command": "npx",
      "args": ["-y", "@opafex/mcp-approval-queue"]
    }
  }
}

然后在项目说明等位置告诉 Agent 何时使用，例如：

删除数据、发送电子邮件、花费资金或部署之前，调用 request_approval，并且仅在 proceed 为 true 时继续。

如何决定是否批准请求

1. 根据操作名称评估风险——无论 bulk_delete_users 中的 delete 出现在哪里，它都会被视为删除操作——并结合 params.estimatedCost 评估。Agent 可以传入 category，但它只能提高风险评分，不能降低。

2. 规则可能会自动批准请求——仅限低或中风险，且只能使用人类创建的规则。高风险和严重风险始终需要由人审批。

3. 否则由人决定：

   • 在客户端中——如果客户端支持 elicitation，服务会直接向你询问操作、风险、参数和 Agent 给出的理由，并等待你的答复。答复会发送给服务，而不是模型。你可以批准、拒绝，或勾选 始终批准（仅限低／中风险）以创建规则。关闭表单会使请求保持待处理状态。

   • 在终端中——否则，请求会保持等待状态，并提示 Agent 轮询 check_status：

     npx @opafex/mcp-approval-queue pending
     npx @opafex/mcp-approval-queue approve appr_3f9c1a2b4d5e --reason "checked the recipient list"
     npx @opafex/mcp-approval-queue reject  appr_3f9c1a2b4d5e
     

4. 未答复的请求将在 24 小时后过期（APPROVAL_QUEUE_TTL_HOURS），过期后无法再批准。

同一操作获得人类批准五次且没有遭到拒绝后，下一个表单会提示你选择 始终批准。自动批准不会计入次数——系统自我认同并不能作为依据。

工具（Agent 可见）

工具	描述
request_approval	提交操作（action、可选的 params、context、category、wait）。返回 status、proceed、风险等级及后续操作说明。
check_status	根据 id 重新读取请求。
list_pending	按时间从新到旧列出仍在等待人类处理的请求。
list_rules	查看人类设置的自动批准规则（只读）。

status 的取值为 pending、approved、rejected、auto_approved、expired。只有当 proceed 为 true 时才继续。

资源

URI	内容
approval://stats	按状态统计的数量，以及人类作出决定所用的平均时间
approval://rules	当前的自动批准规则
approval://history	最近 50 条决定记录

CLI

mcp-approval-queue                       start the MCP server (stdio)
mcp-approval-queue pending               list requests waiting for a decision
mcp-approval-queue show <id>             one request in full
mcp-approval-queue approve <id> [--always] [--reason <text>]
mcp-approval-queue reject <id> [--reason <text>]
mcp-approval-queue rules                 list rules
mcp-approval-queue rules add <pattern> --max-risk <low|medium> [--description <text>]
mcp-approval-queue rules remove <id>
mcp-approval-queue history [limit]

模式使用 glob：* 匹配任意内容，? 匹配一个字符，且不区分大小写。规则绝不能涵盖高风险或严重风险。

配置

变量	默认值	描述
APPROVAL_QUEUE_STATE_DIR	~/.opafex/approval-queue	state.json（请求、规则、历史记录）的存放位置。服务和 CLI 必须指向同一目录。
APPROVAL_QUEUE_TTL_HOURS	24	未决定的请求过期前的小时数

状态保存在单个 JSON 文件中，并通过锁文件以原子方式写入，因此服务和 CLI 可以同时运行。

它无法防护的情况

在依赖它之前，请务必了解以下几点：

• 拥有 shell 或文件访问权限的 Agent 可以访问终端通道。 只有当 Agent 无法运行命令或写入文件时，CLI 和 state.json 才是仅供人工使用的通道。Claude Code 等编码 Agent 通常具备这些权限。在这种情况下，请依赖 elicitation 通道，并在客户端的权限设置中禁止 Agent 使用 CLI 和访问状态目录——对于 Claude Code，禁止 Bash(npx @opafex/mcp-approval-queue approve:*)、Bash(npx @opafex/mcp-approval-queue rules:*)，并禁止编辑 ~/.opafex/ 下的文件。
• 它只会限制 Agent 询问的内容。 Agent 必须调用 request_approval，并遵守 proceed: false。这是面向配合型 Agent 的协议，也是对获准事项的记录，而不是沙箱。对于任何必须强制执行的事项，请配合使用客户端自身的工具权限。
• Elicitation 由客户端显示。 答案确实来自人工的保证，取决于客户端对表单的呈现方式。

在库中使用

import { ApprovalQueueService, StateStore, assessRisk } from '@opafex/mcp-approval-queue';

const queue = new ApprovalQueueService(new StateStore('/var/lib/my-app/approvals'));
const { request } = await queue.requestApproval({ action: 'refund_order', params: { estimatedCost: 40 } });

开发

npm install
npm run build
npm test

许可证

MIT — 请参阅 LICENSE。