hookshelf-mcp

**给你的编码代理一个真正的 webhook 端点。**一个 MCP 服务器，让 Claude Code、Cursor 和任何 MCP 客户端接收 webhook，检查到达的确切字节，为 7 个提供商发送正确签名的测试事件，并重放任何投递——由本地 hookshelf 实例支持，因此载荷永远不会离开你的机器。

问题

让代理"集成 Stripe webhook"，它只会盲目地编写处理器。它无法接收投递，因此无法看到 Stripe 实际发送的内容，无法对照真实字节检查其签名验证，也无法确定它的修复是否有效。通常的答案——公共隧道和在提供商仪表板中点击——恰恰是代理无法完成的部分。

有了这个服务器，代理自己就能闭环：

agent: create_endpoint(name: "stripe-dev", provider: "stripe", secret: "whsec_...")
  →  http://127.0.0.1:3000/in/f4080sjvz3v6tfd5

agent: send_test_event(endpoint_id: "f4080...")        # signed like the real thing
  →  { received: true, delivery: "a698af65..." }

agent: get_delivery(delivery_id: "a698af65...")
  →  headers as received, exact body, verification: "ok"

agent: send_test_event(endpoint_id: "f4080...", tamper: true)
  →  { error: "invalid_signature", delivery: "eb7c9d8e..." }   # failure path, also stored

编写处理器 → 发送签名事件 → 读取到达内容 → 修复 → 重放。无需第三方服务，无需隧道，无需仪表板。

Related MCP server: hookray-mcp

工具

Twilio 仅验证：它签署的是公共请求 URL 而非正文，因此只有真实的提供商才能产生有效签名。

设置

两部分：hookshelf（保存投递）和此服务器（给代理双手）。

# 1. hookshelf
git clone https://github.com/vinkurov/hookshelf.git && cd hookshelf
docker compose up -d        # dashboard on http://127.0.0.1:3000

# 2. this server
git clone https://github.com/vinkurov/hookshelf-mcp.git && cd hookshelf-mcp
npm install && npm run build

Claude Code — 项目中的 .mcp.json（或 claude mcp add）：

{
  "mcpServers": {
    "hookshelf": {
      "command": "node",
      "args": ["/path/to/hookshelf-mcp/dist/main.js"],
      "env": { "HOOKSHELF_URL": "http://127.0.0.1:3000" }
    }
  }
}

Cursor 和 Claude Desktop 在其 MCP 设置中采用相同的 command/args/env 块。HOOKSHELF_URL 默认为 http://127.0.0.1:3000。

尚未发布到 npm——npx hookshelf-mcp 将在发布后可用；本 README 会在发布后说明，而不是提前。

值得注意的事项

• 签名是根据 webhook-kit 验证所依据的相同规范生成的，并且每个签名都通过 webhook-kit 的实际验证器进行往返测试——只有在测试失败时生成和验证才会出现偏差。

• **密钥仅保存在内存中。**hookshelf 以只写方式存储密钥，因此 send_test_event 仅适用于当前会话中创建的端点；对于其他情况，服务器会明确说明，而不是猜测。

• **被拒绝的投递仍会被存储。**这是 hookshelf 的决定性行为：你无法调试一个被你丢弃的请求。工具会返回投递 ID，无论结果如何，代理都可以检查具体失败的原因。

• 带时间戳的签名使用 Unix 秒，而非毫秒——毫秒级时间戳会产生"有效"签名但无法通过新鲜度检查，这正是该类工具要捕获的那种 bug。

• hookshelf 无认证：保持其绑定到 loopback（其 compose 文件已如此）。

开发

npm test              # 37 tests: every signature round-trips through webhook-kit's verifier
npm run test:e2e      # 11 checks against a real hookshelf instance
npm run lint && npm run typecheck

单元测试通过真实的 MCP 客户端在内存传输上驱动服务器，针对一个模拟的 hookshelf，其响应是从真实 hookshelf 复制的；端到端运行会对照真实情况检查这些副本。它已经抓住过一次漂移：模拟版本在仅捕获的端点上进行了去重，而真实的 hookshelf 仅在转发时去重（否则没有下游需要保护）。

许可证

MIT——见 LICENSE。