内容
# @hooksense/mcp
HookSense 的模型上下文协议（MCP）服务器 —— 为 AI 代理提供 webhook 和回调层。允许 Claude Desktop、Cursor、Claude Code、Continue 等 MCP 客户端创建回调 URL，**等待结果而不是轮询**，并验证其签名 —— 所有操作均在代理会话中完成。
## 为什么使用
启动异步工作的代理（如部署、渲染、人工审核、长时间工具调用、另一个代理）需要返回结果，而不希望在轮询循环中消耗上下文。有了这个服务器，代理可以创建回调端点，将 URL 交给作业，然后调用 `wait_for_callback`，在 webhook 到达时立即唤醒，验证签名并解密。停止为异步结果轮询；改为等待。
## 设置
1. 在 <https://hooksense.com/account/tokens> 获取 API token
2. 配置你的 MCP 客户端（以下提供示例）
### Claude Desktop / Claude Code
在 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）中添加：
```json
{
"mcpServers": {
"hooksense": {
"command": "npx",
"args": ["-y", "@hooksense/mcp"],
"env": {
"HOOKSENSE_TOKEN": "hsk_你的_token_在此"
}
}
}
}
```
### Cursor
在 `~/.cursor/mcp.json` 中添加：
```json
{
"mcpServers": {
"hooksense": {
"command": "npx",
"args": ["-y", "@hooksense/mcp"],
"env": {
"HOOKSENSE_TOKEN": "hsk_你的_token_在此"
}
}
}
}
```
## 回调示例（60 秒）
配置完成后，向你的代理提问：
1. **创建** — "创建回调端点。" → 代理调用 `create_callback_endpoint` 并获取回调 URL，如 `https://hooksense.com/w/ab12cd`。
2. **发送** — 将任何作业指向该 URL（或在另一个终端使用 `curl -X POST <callbackUrl> -d '{"status":"done"}'`）。
3. **等待** — "等待回调。" → 代理调用 `wait_for_callback` 并阻塞，直到 webhook 到达，然后接收 `{ status: "received", request: { body, headers, … } }`。
4. **验证**（可选）— 在端点上设置 webhook 密钥，然后 "验证签名。" → `verify_signature` 确认有效载荷真实，然后代理对其采取行动。
无需轮询，无需仪表盘，无需复制粘贴。
## 工具
| 工具 | 描述 |
|---|---|
| `create_callback_endpoint` | 创建回调端点；返回 `callbackUrl` |
| `wait_for_callback` | 阻塞直到下一个回调到达，然后返回它（`timeoutMs`、`after` 光标） |
| `list_callbacks` | 列出端点接收的回调（摘要视图） |
| `get_callback_payload` | 获取一个回调，附带完整的头部 + 解密正文 |
| `verify_signature` | 针对端点配置的密钥进行计时安全 HMAC 检查 |
| `replay_callback` | 将接收的回调 POST 到任意目标 URL |
| `list_endpoints` | 列出您的端点 |
| `get_endpoint` | 获取一个端点的完整设置 |
## 环境
| 变量 | 默认值 | 备注 |
|---|---|---|
| `HOOKSENSE_TOKEN` | _(必填)_ | 来自 /account/tokens 的 API token |
| `HOOKSENSE_API` | `https://hooksense.com` | 自托管/预发布环境的覆盖 |
## 示例代理提示
> "创建一个回调端点，用作我的 Replicate 预测的 webhook，并等待结果 — 然后总结输出。"
> "打开一个回调 URL，将其交给审批步骤，并在继续之前阻塞，直到人类审批。"
> "等待 `payments-prod` 上的下一个 Stripe 回调，验证其签名，然后告诉我金额。"
## 许可证
MIT
