Nahook Mcp

nahook-mcp

Nahook 的官方 Model Context Protocol 服务 Nahook——通过 Claude Desktop、Cursor、Cline 及其他任何兼容 MCP 的 AI 助手，驱动 Webhook 投递、端点和事件触发器。

MCP 服务以 nahook CLI 的子命令形式提供。一个二进制文件、一个凭据文件、一种安装方式。

功能

安装并完成身份验证后，AI 助手可以：

• 检查端点、投递记录和每次尝试的日志，以调试失败的 Webhook。
• 重试失败或进入死信队列的投递。
• 触发事件，并将其分发给所有订阅端点。
• 发送 Webhook，直接发送到单个端点。
• 管理端点（创建、更新、暂停、恢复）——按设计，无法删除。

写入操作带有 MCP destructiveHint/readOnlyHint 注解，因此 MCP 客户端会在任何状态变更前，针对每次调用显示人工审批提示。

安全防护措施

Webhook 负载属于第三方数据，因此服务会将所有流回模型上下文的内容视为潜在的提示注入渠道：

• 不可信内容会被明确隔离。 所有会传递给模型的、由生产方或接收方编写的值——Webhook 负载（get_delivery 配合 include_payload）、投递幂等键以及接收方错误消息（list_attempts）——都会用明确的 <<<UNTRUSTED CONTENT ...>>> 分隔符包裹，并对其中嵌入的分隔标记进行转义；服务指令还会告知模型将分隔内容视为惰性数据，绝不能当作指令。
• 负载大小有限制。 超过 256 KB 的正文会被截断（通过 payload_truncated 标记），防止恶意生产方塞满模型上下文。可通过 MCP 客户端环境中的 NAHOOK_MCP_PAYLOAD_CAP=<bytes> 调整上限。
• 按设计不提供删除工具。 工具接口中的任何内容都无法销毁数据。
• update_endpoint 标记为破坏性操作。 它会覆盖生效中的端点配置（重新指定其 URL 正是提示注入会利用的操作），因此其 destructiveHint 为 true，客户端会显示醒目的审批提示。
• 写入工具依赖人工审批。 根据 MCP 规范，注解只是建议性提示，并非访问控制——安全边界是客户端针对每次调用显示的审批提示，它适用于所有非只读工具。新增的写入工具（create_endpoint、send_to_endpoint、trigger_event）根据规范语义标注为 destructiveHint: false；请在 MCP 客户端中启用人工参与审批，不要将这些工具一概设为允许。如果需要确保不发生写入，请在不提供摄取密钥的情况下运行服务（这会禁用发送），并将管理工具视为需要审批的工具。
• 机密信息永远不会传递给模型。 所有工具输出都会省略端点签名密钥和身份验证令牌；whoami 仅返回令牌的公开 ID。
• 凭据分离。 发送（trigger_event、send_to_endpoint）需要单独的摄取密钥——省略该密钥后，服务将只能用于管理或只读摄取。

客户端措施无法彻底杜绝提示注入——请配合 MCP 客户端的工具审批提示使用。

安装

MCP 服务是 nahook CLI 的子命令。先安装 CLI，再将其添加到 AI 客户端。

1. 安装 CLI

macOS / Linux（Homebrew）：

brew install getnahook/tap/nahook

Linux / macOS（安装脚本）：

curl -fsSL https://cli.nahook.com/install.sh | sh

其他安装方式请参阅 getnahook/nahook-cli。

2. 登录一次

nahook login

这会打开浏览器，引导你完成设备授权身份验证，并将凭据写入 ~/.nahook/config.toml。

3. 将 MCP 服务接入 AI 客户端

Claude Desktop 和 Claude Code CLI：

claude mcp add nahook -- nahook mcp serve

Cursor — 编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "nahook": {
      "command": "nahook",
      "args": ["mcp", "serve"]
    }
  }
}

Cline（VS Code） — Cline → Settings → MCP Servers → 添加：

{
  "nahook": {
    "command": "nahook",
    "args": ["mcp", "serve"]
  }
}

Zed — 添加到 settings.json：

{
  "assistant": {
    "mcp_servers": {
      "nahook": {
        "command": "nahook",
        "args": ["mcp", "serve"]
      }
    }
  }
}

其他兼容 MCP 的客户端（Continue、Windsurf、Goose，……）遵循相同的 command + args 格式。

工具

工具	功能
whoami	本地配置检查 — 工作区、区域、令牌 ID、有效期。
list_endpoints	列出当前工作区中的所有端点。
get_endpoint	按 ep_xxx 获取一个端点。
create_endpoint	创建新端点。默认使用工作区的默认环境；也接受 production 这样的 slug。
update_endpoint	部分更新 — 暂停／恢复、更改 URL、更新描述。
list_environments	列出工作区中的所有环境。
list_deliveries	按时间从新到旧分页列出某个端点的投递记录。
get_delivery	按 del_xxx 获取一条投递记录。传入 include_payload: true 还可获取原始 webhook 请求体 — 这对调试至关重要。
list_attempts	列出针对某条投递的所有尝试（有助于调试失败问题）。
retry_delivery	将失败或进入死信队列的投递重新排队。
trigger_event	按类型触发事件 — 后端会将事件分发给所有订阅者。
send_to_endpoint	直接向一个端点发送 webhook。

身份验证模型

MCP 服务使用两种独立凭证：

• CLI 登录令牌（nhc_…）— 由 nahook login 写入。用于读取工具，以及管理端点／投递记录／环境的操作。
• 摄取密钥（nhk_…）— 与 SDK 使用的密钥相同。用于 trigger_event 和 send_to_endpoint。可通过在 MCP 客户端环境中设置 NAHOOK_INGESTION_KEY=nhk_...，或在 ~/.nahook/config.toml 中添加 ingestion_key = "nhk_..." 来配置。未配置该密钥时调用写入工具，服务会明确报错。

权限会根据你的工作区角色按请求进行评估 — MCP 令牌拥有的权限与你在控制面板中的权限完全相同，不多也不少。

代码所在位置

MCP 服务实现属于 nahook CLI 源代码树。此仓库用于便于发现 — 包含 README、MCP 目录条目和打包元数据。无需维护独立代码库。

如需提交 bug、申请工具或参与贡献，请前往 getnahook/nahook-cli 提交 issue。

许可证

MIT — 与 CLI 相同。