MCP Augment

mcp增强

为没有安全挂钩的AI编码工具添加安全挂钩。

______________________________________________________________________

本次发布内容

______________________________________________________________________

问题

你的AI编码助手可以删除文件、泄露秘密，并在没有护栏的情况下运行破坏性命令。Claude Code有钩子来防止这种情况。Windsurf在2026年初增加了自己的Cascade挂钩，但这些挂钩只在Windsurf内部工作。Cursor、Kilo Code、Aider和Cline仍然没有。而且这些钩子系统都不能跨工具移植。

解决方案

此MCP服务器公开 强制代理工具 (safe_write, safe_edit, safe_bash, safe_read, safe_delete)在执行之前，通过可配置的钩子链验证每个操作。将其连接到任何兼容MCP的AI编码工具，它添加了客户端本机没有的更安全的工具层。

这不仅仅是“更安全的工具”。它是一种便携式工具 能力注入+工具调用校正+执行层:

• 为没有安全替换工具的客户端添加更安全的替换工具
• 在工具运行之前修复错误的输入
• 在不良输出到达模型之前进行清理或转换
• 使行为比单独提示更具确定性和可预测性
• 让用户在需要时使用钩子、配置和手动监督

______________________________________________________________________

演示

$ kilo  # launch Kilo Code CLI with mcp-augment connected

Agent> safe_write .env "API_KEY=sk-..."
=> BLOCKED: Protected file (.env matches sensitive file pattern)

Agent> safe_write src/app.py "print('hello')"
=> ALLOWED: wrote src/app.py (16 bytes)

Agent> safe_delete .env
=> BLOCKED: Protected file

Agent> safe_bash "rm -rf /"
=> BLOCKED: Destructive command detected

______________________________________________________________________

快速开始

1.克隆并安装

git clone https://github.com/JoeyBe1/mcp-augment.git
cd mcp-augment

# Create and activate the virtual environment (required — all deps live here)
python3 -m venv .venv && source .venv/bin/activate

# Install all dependencies
pip install -e .          # installs mcp + all deps from pyproject.toml
brew install jq           # required by the default hook scripts (macOS)

注： start-servers.sh 用途 .venv/bin/python3 自动。始终从repo根目录中运行，以便venv路径正确解析。

2.启动服务器并配置客户端

./project-tools/mcp-hooks-server/setup.sh

这可以完成所有操作：启动服务器（默认端口为8200，如果占用，会自动找到下一个空闲端口），对其进行健康检查，并将正确的MCP URL写入 mcp_config.json。端口更改时，请重新运行。

对于stdio模式（支持它的MCP客户端）： python3 project-tools/mcp-hooks-server/mcp-augment.py

3.连接您的AI编码工具

Kilo Code命令行界面 — ~/.config/kilo/opencode.json

注意：Kilo CLI从该全局路径读取。项目级别 .kilo/kilo.json 被忽略。

{
  "mcp": {
    "mcp-augment": {
      "type": "remote",
      "url": "http://localhost:8200/mcp",
      "enabled": true
    }
  }
}

克劳德代码 — .claude/settings.json

{
  "mcpServers": {
    "mcp-augment": {
      "command": "python3",
      "args": ["-u", "project-tools/mcp-hooks-server/mcp-augment.py"]
    }
  }
}

光标 — ~/.cursor/mcp.json （已在macOS上验证，2026-04-01）

{
  "mcpServers": {
    "mcp-augment": {
      "command": "python3",
      "args": [
        "-u",
        "${workspaceFolder}/project-tools/mcp-hooks-server/mcp-augment-http.py",
        "--stdio"
      ],
      "env": {
        "PROJECT_DIR": "${workspaceFolder}"
      }
    }
  }
}

Cursor注释：经过实时验证的安装程序使用全局Cursor配置 ~/.cursor/mcp.json 并发射 mcp-augment-http.py --stdio.在这方面 环境、项目级 .cursor/mcp.json 没有可靠地实例化。

帆板运动 — .codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-augment": {
      "command": "python3",
      "args": ["-u", "./project-tools/mcp-hooks-server/mcp-augment.py"]
    }
  }
}

克莱恩 --VS代码设置→ 临床MCP服务器

{
  "mcp-augment": {
    "command": "python3",
    "args": ["-u", "./project-tools/mcp-hooks-server/mcp-augment.py"],
    "disabled": false
  }
}

教唆者 --HTTP模式（Aider通过HTTP支持MCP）：

./project-tools/mcp-hooks-server/start-servers.sh
# Then in aider: /mcp add http://localhost:8200/mcp

所有线束共享相同的挂钩脚本(.kilo/hooks/*.sh).这些脚本是 可移植性——它们使用与Claude Code的原生挂钩系统相同的stdin JSON格式。 如果挂钩在Claude Code中有效，那么它在这里也有效。

______________________________________________________________________

模式：注射+拦截

mcp-auction做了两件现有mcp解决方案没有做的事情：

1.能力注入 --创建宿主工具中不存在的强制工具版本。 safe_write, safe_edit, safe_bash, safe_read, safe_delete 替换本地等效项。 在单个MCP调用中，验证和执行是原子性的。代理无法验证然后绕过。

2.工具调用拦截 --在执行前后在语义层操作。 这种模式源于修复较弱模型的错误工具调用：模型留下尾随 JSON中的逗号，您可以在输入到达工具之前重写输入。网络搜索使用去年的日期， 在执行查询之前更正查询。然后，如果输出有噪声、有毒、格式错误或 只是不方便，你可以在它回到模型之前对其进行转换。预验证和 执行后钩子在这一层运行，使您可以完全控制实际到达工具的内容 以及什么会回来。

这与在传输时拦截的MCP网关（锁存器、Bifrost、mcproxy）不同 客户端和现有服务器之间的层。与Claude Code的原生钩子不同 只能在Claude Code内部工作。mcp-auction在工具执行层运行，并在任何 MCP兼容主机，适用于任何型号。

AI Coding Tool (Kilo, Cursor, Windsurf, Cline, Aider, Claude Code...)
    │
    │ MCP protocol (stdio or HTTP)
    │
    ▼
┌──────────────────────────────────────────────────┐
│                 mcp-augment                      │
│                                                  │
│  [PreToolUse hooks run here — can mutate input]  │
│                                                  │
│  safe_write  ──► hook chain ──► write file       │
│  safe_edit   ──► hook chain ──► edit file        │
│  safe_bash   ──► hook chain ──► execute command  │
│  safe_read   ──► hook chain ──► read file        │
│  safe_delete ──► hook chain ──► delete file      │
│                                                  │
│  [PostToolUse hooks run here — can act on output]│
│                                                  │
│  Atomic: validate THEN execute in one call       │
│  Hook chain: config.yaml ──► *.sh scripts        │
└──────────────────────────────────────────────────┘
    │
    ▼
Shell hooks (.kilo/hooks/*.sh) — portable, same format as Claude Code native hooks
  block-sensitive-files.sh  ← blocks .env, credentials, secrets
  validate-bash-command.sh  ← blocks destructive commands, sudo, force-push
  mode-enforcement.sh       ← research/optimize/benchmark/eval modes
  auto-approve-safe.sh      ← auto-approve git status, ls, cat
  auto-format.sh            ← post-edit formatting (async)
  inject-git-context.sh     ← session start context injection

______________________________________________________________________

17可用工具

______________________________________________________________________

它有什么不同

mcp-augment 位于与MCP代理层和Claude Code的本机钩子不同的位置。

• 与Latch、Bifrost或MCPProxy等代理/网关层相比： mcp-augment 不只是坐在现有服务器的前面。它暴露了自己的强制执行 safe_* 工具并围绕这些工具执行运行一个钩子链。网关和代理仍然可以添加策略、过滤、批准或路由，但它们是不同的集成点。
• 与Claude代码挂钩相比：Claude已经有了本机挂钩，包括工具前输入更新和多种处理程序类型。Windsurf还在2026年初增加了Cascade Hooks。 mcp-augment 适用于不公开这些本机挂钩系统，而是需要通过MCP交付挂钩管理工具层的主机。
• mcp-augment 在主机级别仍然是软执行。模型必须使用 safe_* 而不是用原生工具绕过它们。强大的工具描述在实践中有所帮助，但这不是内核级的沙盒。
• 这里的独特主张不是“没有其他人可以执行政策”。独特主张是 mcp-augment 将工具调用前/后的纠正、审查恢复行为和强制替换工具打包到一个可移植的MCP交付层中，该层跨客户端工作，而不依赖于这些客户端具有克劳德风格的原生钩子。

今天，最明确的产品声明是：

mcp-augment 是一个可移植的MCP交付的工具调用前/后校正和执行层，适用于没有本机钩子的AI客户端。

今日修正模式

• 自动校正（已发货）: PreToolUse 钩子可以发射 modifiedInput，该工具使用更正的参数运行，然后同步 PostToolUse 钩子可以发射 modifiedOutput 在结果到达模型之前。这是默认设置 demo_search_backend 演示时不需要用户编辑。
• 咨询监督（已发货）: notify_user 和 open_in_editor 可以提醒用户或提交文件供审查。这只是一个通知/切换层。它本身不会将用户的编辑合并回相同的编辑中 safe_* 电话。
• 协作用户评论-摘要（附带，macOS原生UI+文本编辑回退）：这是真正的相同呼叫循环路径中的人类。钩子返回 reviewInput （预）或 reviewOutput （post）加可选 reviewTitle / reviewInstructions主UI是一个本机AppleScript字段选择器——一个带有接受/编辑/拒绝按钮的格式化对话框，一个字段选择列表，以及出现在所有其他窗口前面的每个字段编辑框。如果本机对话框失败，TextEdit是回退。引擎等待用户，然后使用编辑的有效负载恢复相同的工具调用。无效或放弃的编辑将回退到钩子建议的字典。默认情况下，它会无限期等待；集 MCP_AUGMENT_REVIEW_TIMEOUT 如果您想要强制超时，请将其设置为正数，或 MCP_AUGMENT_SKIP_REVIEW=1 不请编辑就接受这个提议。测试使用 MCAugmentMCP.review_interactive_fn 无头注入编辑。

换句话说：发动机中没有单独的通用“手动模式”标志。发货的协作/手动行为是 reviewInput / reviewOutput 查看恢复路径。

工作双向演示（自动校正）

从存储库根目录（其中 pyproject.toml 生活），把这个贯穿始终 safe_bash 在光标中：

python3 project-tools/mcp-hooks-server/demo_search_backend.py --query "mcp augment release date 2025"

预期的现场结果 mcp-augment MCP服务器已重新启动：

• 预挂钩重写 2025 -> 2026
• 后端使用更正的查询运行
• 柱钩移除 INTERNAL_DEBUG
• 后置钩子前缀 [POST-HOOK FILTERED]
• 可选的通知挂钩提醒用户输出已进行后处理

用户评论简历演示（同一通话，文本编辑）

使用相同的后端，但包含子字符串 REVIEW_DEMO 在 shell 命令 因此，auto-pre/post-demo钩子跳过，而review钩子则运行：

python3 project-tools/mcp-hooks-server/demo_search_backend.py --query "mcp augment release date REVIEW_DEMO 2025"

流量：

1. pre-review-search-query.sh 发射 reviewInput （拟议指挥 2026).TextEdit打开并等待用户；保存并关闭以继续。
2. post-shape-search-output.sh 在以下情况下跳过 REVIEW_DEMO 存在。
3. post-review-search-output.sh 发射 reviewOutput 用于stdout整形；另一个TextEdit过程以相同的方式等待用户。
4. 当提案被接受时，最终的stdout与自动演示相匹配。

验证行为：两个TextEdit审查窗口是连续的。在保存/关闭第一个审核文件并将其合并回同一文件之前，第二个审核不会打开 safe_bash 电话。

______________________________________________________________________

吊钩配置

挂钩配置在 .kilo/hooks/config.yaml:

hooks:
  PreToolUse:
    - matcher: "Edit|Write|MultiEdit|delete_file"
      hooks:
        - type: command
          command: ".kilo/hooks/block-sensitive-files.sh"
          timeout: 10
        - type: command
          command: ".kilo/hooks/mode-enforcement.sh"
          timeout: 10

    - matcher: "Bash"
      hooks:
        - type: command
          command: ".kilo/hooks/validate-bash-command.sh"
          timeout: 10

  PostToolUse:
    - matcher: "Write|Edit|MultiEdit"
      hooks:
        - type: command
          command: ".kilo/hooks/auto-format.sh"
          async: true

编写自定义钩子

Hooks是shell脚本，它：

1. 从stdin读取JSON(tool_name, tool_input, cwd)
2. 退出0表示允许，退出2表示阻止
3. 可选地输出JSON permissionDecisionReason, modifiedInput, modifiedOutput，或查看简历字段(reviewInput, reviewOutput, reviewTitle, reviewInstructions)

#!/bin/bash
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

if [[ "$FILE" == *.env* ]]; then
  echo '{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"Protected file"}}'
  exit 2
fi
exit 0

这些钩子是 便携的 --同样的脚本在Claude Code的原生钩子系统中工作，并在任何其他工具中通过mcp增强。

你今天可以扩展什么

• 定制挂钩：yes--编写shell脚本并向注册 manage_hook
• 自定义工作流：是--使用 hook_event, pre_validate, batch_validate、监视和挂钩配置以塑造运行时行为
• 自定义工具行为：是的——通过围绕现有网络的预/后拦截 safe_* 工具
• 自定义 prompt / agent 吊钩装卸工：尚未-按计划记录，未发货

______________________________________________________________________

自动启动（macOS）

安装launchd plist以自动启动服务器：

PROJECT_DIR="$(pwd)"
sed "s|__PROJECT_DIR__|$PROJECT_DIR|g" \
  project-tools/mcp-hooks-server/com.mcp-augment.plist \
  > ~/Library/LaunchAgents/com.mcp-augment.plist
launchctl load ~/Library/LaunchAgents/com.mcp-augment.plist

验证：

lsof -i :8200  # mcp-augment hooks server

______________________________________________________________________

测试

# Run the full test suite (38 tests, no server required)
python -m pytest tests/ -q

预期： 38 passed.

______________________________________________________________________

路线图

近期：

• 速率限制（RPM强制——状态文件中的令牌桶，可按项目配置）
• macOS安全带/沙盒风格集成 safe_bash （探索性；非MVP）
• 供应商/线束布线（通过配置将不同的工具分配到不同的后端）
• tmux多代理支持（macOS——生成命名会话、发送密钥、捕获输出）
• doctor 工具（配置卫生：钩子合规性检查、日志路径验证、工具交换，例如grep→ripgrep）
• 交叉线束 manage_hook --写信给 settings.json （克劳德代码）除 .kilo/hooks/config.yaml

工具包装 (project-tools/ --存根存在，实现待定）：

• ripgrep、jq、astgrep作为一流的MCP工具

______________________________________________________________________

贡献

1. 分叉存储库
2. 创建要素分支
3. 添加新功能的测试
4. 确保 python3 -m pytest tests/ -q 通过
5. 提交拉取请求

______________________________________________________________________

许可证

麻省理工学院——见 许可证