hitl-gate-mcp

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

• 运行时：Node.js ≥ 18
• 传输：stdio MCP
• 默认审批：IDE 内建表单（MCP elicitation）；不可用时走聊天文案 / 可选网页面板
• 客户端：Cursor 与 VS Code（GitHub Copilot） 同一套接入步骤

推荐接入（两步，双端相同）

① 配置 MCP（让工具连上）

两边最终都跑：npx -y hitl-gate-mcp。差异只在配置文件路径。

Cursor（macOS 推荐，复制即用） — .cursor/mcp.json：

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

用登录 shell 启动，自动带上 nvm / Homebrew 的 Node，不必写绝对路径。
若写裸 "command": "npx"，Cursor 从图标启动时经常报 spawn npx ENOENT。

VS Code — .vscode/mcp.json：

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

VS Code 若同样 ENOENT，把 command/args 改成与上面 Cursor 相同的 /bin/zsh + -lic 写法即可。

init 也会生成示例：.cursor/mcp.json.example、.vscode/mcp.json.example。

保存后在 MCP 面板确认 hitl_mcp 已连接。

② 手动 init（装上硬约束，提高遵从率）

在目标项目根目录：

hitl-gate-mcp init
# 或
npx hitl-gate-mcp init

默认 --client all，一次写入 Cursor + VS Code 钩子：

| 客户端 | 写入内容 | |--------|----------| | Cursor | .cursor/rules/hitl-auto-gate.mdc、.cursor/skills/hitl-gate/SKILL.md | | VS Code / Copilot | .github/instructions/hitl-gate.instructions.md |

只要其中一个客户端：

hitl-gate-mcp init --client cursor
hitl-gate-mcp init --client vscode

已存在则跳过；覆盖加 --force。预览 --dry-run。

npm install -g hitl-gate-mcp   # 一次
hitl-gate-mcp init             # 任意项目

诚实边界：只配 MCP、不跑 init → 依赖模型遵从 instructions，不保证每次都调闸门。
MCP 不能拦截 IDE 原生 Delete/Terminal。

审批弹窗不可用时（VS Code 更常见）

1. Agent 应把返回的 user_prompt_zh 贴到对话里，停止执行
2. 可选：MCP env 设 HITL_ENABLE_PANEL=1，浏览器打开 http://127.0.0.1:8787 批/拒
3. 再调 get_approval_status，仅 approved 后继续

方式二：源码本地运行

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

把 MCP 的 command/args 改成：

node /绝对路径/到/本项目/dist/index.js

HITL_DATA_DIR 建议用绝对路径。示例见 mcp.local.example.json。

怎么用

危险操作审批

1. Agent 在副作用前调用 assess_and_gate（带 code_context）
2. 五档风险；仅 高/致命 开审批
3. 表单批准 / 拒绝；聊天「可以」不算批准
4. 高/致命附带 爆炸半径；执行后 submit_execution_report

查看审批记录

说：「看审批记录」 → list_approval_history → 展示 summary_zh 表格。

可用工具

| 工具 | 作用 | |------|------| | assess_and_gate | 五档风险 + 爆炸半径；仅高/致命开单 | | submit_execution_report | 批后计划 vs 实际对照 | | list_dangerous_ops | 内置危险操作表 | | request_approval | 手动开单 | | get_approval_status | 查工单 | | list_pending | 待审列表 | | list_approval_history | 审批历史 |

环境变量

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

本地自检

npm run smoke

License

MIT