MCP 服务器

hitl-gate-mcp

Human-in-the-Loop approval gate for AI agents to assess risky operations and require user approval via Cursor forms.

README

hitl-gate-mcp

给 AI Agent 用的 Human-in-the-Loop 审批门 MCP：危险操作先评估、再在 Cursor 里点选批准/拒绝，并可在对话中查看审批记录。

运行时：Node.js ≥ 18
传输：stdio MCP
默认审批：Cursor 内建表单（MCP elicitation），无需浏览器

方式一：npm / npx（包发布后推荐）

在 Cursor 打开 Settings → MCP，编辑 mcp.json：

{
  "mcpServers": {
    "hitl_mcp": {
      "command": "npx",
      "args": ["-y", "hitl-gate-mcp"],
      "env": {
        "HITL_ELICIT": "1",
        "HITL_ENABLE_PANEL": "0"
      }
    }
  }
}

保存后确认 hitl_mcp 为已连接（绿灯）。

也可全局安装：

npm install -g hitl-gate-mcp

然后把 command / args 改成直接调用 hitl-gate-mcp（或仍用上面的 npx 写法）。

方式二：下载源码，在本地运行

适合尚未发布到 npm，或你要改策略代码时。

1. 获取代码并构建

git clone <本仓库地址>
cd <克隆下来的目录名>
npm install
npm run build

构建成功后会生成 dist/index.js。

2. 配置 Cursor MCP

打开 Cursor → Settings → MCP，添加服务器（或编辑 mcp.json）。
路径必须换成你机器上的绝对路径：

{
  "mcpServers": {
    "hitl_mcp": {
      "command": "node",
      "args": ["/绝对路径/到/本项目/dist/index.js"],
      "env": {
        "HITL_DATA_DIR": "/绝对路径/到/本项目/data",
        "HITL_ELICIT": "1",
        "HITL_ENABLE_PANEL": "0"
      }
    }
  }
}

保存后确认 hitl_mcp 显示为已连接 / 绿灯。

可用 pwd（macOS/Linux）或资源管理器地址栏查看项目绝对路径。
HITL_DATA_DIR 建议固定为绝对路径，避免 Cursor 工作目录变化导致审批记录读不到。

也可参考：

mcp.json.example — npx 用法
mcp.local.example.json — 本地 node + 绝对路径（请改成你的路径）

怎么用

危险操作审批

Agent 在副作用操作前应调用 assess_and_gate
Cursor 弹出审批表单 → 选择「批准并继续」或「拒绝」
仅当返回 ticket.status === "approved" 时才可继续执行；拒绝/取消则停止

在对话里随便说「可以」不算正式批准；以工单状态为准。

查看审批记录

对 Agent 说：「看审批记录」。
会调用 list_approval_history，并在对话里展示摘要。

可用工具

工具	作用
`assess_and_gate`	风险评估；危险则开单并走 Cursor 审批
`list_dangerous_ops`	查看内置危险操作表
`request_approval`	手动开单（一般用上面主路径即可）
`get_approval_status`	查询某张工单状态
`list_pending`	列出待审工单
`list_approval_history`	审批历史（对话展示）

常见危险类型（摘要）

删除文件 / .env、Git 强推或硬重置、DROP/TRUNCATE、生产发布、密钥外传、curl|bash、chmod 777、npm publish、群发或批量支付等。
完整规则见 builtin/SKILL.md 与 src/policy.ts。

环境变量

变量	默认	说明
`HITL_ELICIT`	`1`	是否使用 Cursor 内审批表单
`HITL_ENABLE_PANEL`	`0`	是否启用本机网页备用面板
`HITL_DATA_DIR`	`./data`	审批数据目录（建议绝对路径）
`HITL_PANEL_PORT`	`8787`	面板端口（仅开启面板时）
`HITL_OPEN_BROWSER`	`0`	面板启动时是否自动打开浏览器