three.ws Herald

@three-ws/herald-mcp

エージェントが直接あなたに何かを伝えられるようにします。

ひとつのアイデアを軸にした MCP サーバーです。エージェントが重要な作業を終えたときや行き詰まったとき、二度と見返さないログに一行追加するのではなく、あなたのもとへ歩み寄って知らせるべきです。

これを組み込めば、そのとおりに動作します。開いているブラウザータブの隅にあなた専用の 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）に適しています。

聞くために開いているものがなければ、メッセージは約 5 分で期限切れになります。レールはライブチャンネルであり、アーカイブではありません。

呼び出し例

// 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 に渡します。@three-ws/herald は、その人自身のルールを満たしているかを判定したうえで、3D コンパニオン（GPU がない場合はアクセシブルなカード）を通じて配信します。

ルールエンジンも含めた一連の動作は、three.ws/heraldでお試しいただけます。

ライセンス

Apache-2.0。