three.ws Herald

@three-ws/herald-mcp

让你的 Agent 当面告诉你一件事。

这是一个只有一个理念的 MCP 服务：当 Agent 完成了重要任务，或遇到阻碍时，它不该只在你永远不会回头查看的日志里添上一行。它应该走到你面前，告诉你。

接入后，它就会这么做。你专属的 3D 伙伴会出现在当前打开的任意浏览器标签页角落，做出手势，并大声说出这句话，同时提供一个可点击的链接。

you: run the migration, then the backfill, and tell me when it's done
agent: [runs for 22 minutes]
       [calls announce_result: task "the backfill", outcome succeeded, 1320s]
your browser: your avatar walks on: "the backfill finished in 22m"

工具

工具	功能
announce	说一句话，并设置重要性（0-100）、语气、手势和可选链接。
announce_result	报告任务已完成。紧急程度会根据结果选择，因此失败通知会穿透安静时段，而成功通知不会。
check_rail	验证密钥和通道是否正常工作，同时不打扰任何人（以重要性 0 排队，所有客户端都会丢弃此通知）。

安装

npx -y @three-ws/herald-mcp

Claude Code：

claude mcp add herald -e THREE_WS_API_KEY=sk_live_... -- npx -y @three-ws/herald-mcp

Claude Desktop / Cursor（mcp.json）：

{
  "mcpServers": {
    "herald": {
      "command": "npx",
      "args": ["-y", "@three-ws/herald-mcp"],
      "env": { "THREE_WS_API_KEY": "sk_live_..." }
    }
  }
}

密钥

在 three.ws/dashboard/developers 创建一个密钥，并授予 herald:announce 权限，然后将其放入 THREE_WS_API_KEY。

公告始终会发送给密钥所有者自己的在线会话。 没有接收者参数：此服务无法指定给其他任何人，因此密钥泄露后，最坏的情况也只是惹恼泄露密钥的人。可在同一页面撤销密钥。

变量	必填	默认值	说明
THREE_WS_API_KEY	是		具有 herald:announce 权限的 API 密钥，或 OAuth 访问令牌。别名：THREE_WS_TOKEN、THREE_WS_BEARER。
THREE_WS_BASE	否	https://three.ws	用于自托管或预览部署的覆盖值。
THREE_WS_TIMEOUT_MS	否	20000	每次请求的超时时间。

何时使用（以及何时不使用）

公告之所以稀少，是刻意为之。接收客户端会应用重要性下限、速率限制、去重、安静时段和时效窗口，因此未达到门槛的内容会被丢弃，而不会排队。这正是它的特点：只有在打扰足够少见时，打断才有效。

适合：耗时任务已完成、任务失败、需要做决定、出现故障、资金发生变动。

不适合：进度更新、“开始第 3 步，共 7 步”之类的内容，以及任何之后可以阅读的信息。这些内容应放在通知收件箱中（@three-ws/notifications-mcp）。

如果没有打开任何页面接收通知，这句话会在约五分钟后过期。此通道是实时通道，不是存档。

调用示例

// something broke, and it should wake somebody up
{ "name": "announce", "arguments": {
    "text": "The payments worker has been failing for 10 minutes",
    "from": "watchdog", "importance": 95, "tone": "error",
    "url": "https://three.ws/dashboard", "key": "payments-worker-down" } }

// a long task finished, and it should not
{ "name": "announce_result", "arguments": {
    "task": "the nightly backfill", "outcome": "succeeded", "seconds": 1320 } }

// wiring check
{ "name": "check_rail", "arguments": { "note": "claude-code" } }

如何将消息发送到浏览器

POST /api/herald/announce 会将这句话排入账户的通道；页面通过 SSE 监听，并将其交给 @three-ws/herald，由它判断是否符合用户自己的规则，然后通过 3D 伙伴发送通知（如果没有 GPU，则显示无障碍卡片）。

可在 three.ws/herald 试用完整流程，包括规则引擎。

许可证

Apache-2.0。