ntfy-cf

ntfy-cf は、ntfy API のプライベートな Workers ネイティブサブセットです。デプロイされた Worker の名前は ntfy-kyeshimizu です。

アーキテクチャ

公開されている NtfyWorker は、トピック、ルート、リクエストサイズ、および Authorization: Bearer ... トークンを検証します。各トピックは、getByName(topic) を持つ 1 つの SQLite Durable Object（Topic）にマッピングされます。このオブジェクトは最大 100 件のメッセージを最大 7 日間保存し、ポーリングリクエストに応答し、新しいメッセージをハイバネーション中の WebSocket にブロードキャストします。

HTTP API は、パブリッシュ、ポーリング、WebSocket サブスクリプションにベアラートークンを要求します。Worker サービスバインディングは、NtfyWorker 上の型付き publish() RPC を呼び出します。このプライベートパスは HTTP トークンを必要としません。

エージェントは、認証付き Streamable HTTP MCP エンドポイント /mcp を通じて同じサービスを利用できます。publish_notification と get_notifications を公開しています。

トピックは [A-Za-z0-9._-]+ に一致し、128 文字以下である必要があります。HTTP ボディと RPC 通知は 64 KiB に制限されています。公開されるメッセージは、event、id、time、topic、message と、title、tags、priority、click、actions、attach、filename、email、call、icon などのオプションのメタデータを持つ ntfy スタイルの JSON オブジェクトを使用します。

Related MCP server: mcp-gotify

ローカル開発

ローカルのみの .dev.vars ファイルを作成します（Wrangler によって無視されます）：

PUBLISH_TOKEN=replace-with-a-local-random-token

Worker を起動します：

npm install
npm run types
npx wrangler dev

以下の例では、.dev.vars と同じ値を使用してください。.dev.vars をコミットしたり、トークンをソースコード、シェル履歴、またはドキュメントに配置したりしないでください。

HTTP API

ローカルで作成したトークンまたはシークレットマネージャーに保存したトークンをシェル変数に設定します：

export NTFY_TOKEN='replace-with-the-token-from-your-local-environment'
export NTFY_URL='http://localhost:8787'

ntfy 互換のヘッダーでプレーンテキストを公開します：

curl -sS -X POST "$NTFY_URL/alerts" \
  -H "Authorization: Bearer $NTFY_TOKEN" \
  -H 'Title: Build finished' \
  -H 'Tags: white_check_mark,ci' \
  -H 'Priority: 4' \
  --data-raw 'release 42 is ready'

JSON メタデータを公開します：

curl -sS -X POST "$NTFY_URL/alerts" \
  -H "Authorization: Bearer $NTFY_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"message":"Deploy finished","title":"Production","priority":3,"tags":["deploy"]}'

境界付きトピック履歴を改行区切り JSON としてポーリングします。since=all（または since なし）は保持された履歴を返します。Unix タイムスタンプはそれ以降のメッセージを返します。既存のメッセージ ID はその ID 以降のメッセージを返します。

curl -sS "$NTFY_URL/alerts/json?poll=1&since=all" \
  -H "Authorization: Bearer $NTFY_TOKEN"

準備状態を確認します：

curl -i "$NTFY_URL/healthz"

WebSocket エンドポイントは /<topic>/ws です。curl によるハンドシェイクはスモークチェックに便利ですが、curl は WebSocket クライアントではないため、後続のフレームを簡単に消費することはできません：

curl --http1.1 -i -N "$NTFY_URL/alerts/ws" \
  -H "Authorization: Bearer $NTFY_TOKEN" \
  -H 'Connection: Upgrade' \
  -H 'Upgrade: websocket' \
  -H 'Sec-WebSocket-Version: 13' \
  -H 'Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==' \
  --max-time 5

ライブサブスクリプションには、websocat などの WebSocket クライアントを使用し、Authorization ヘッダー付きで ws://localhost:8787/alerts/ws を使用します。最初のフレームは open イベントです。以降のパブリッシュは message イベントとして届きます。

ベアラートークン

トークンは単一の Worker シークレットであり、ntfy のユーザー/アカウント資格情報ではありません。Wrangler の認証後に設定します：

npx wrangler secret put PUBLISH_TOKEN --name ntfy-kyeshimizu

Wrangler がプロンプトを表示したときのみトークンを貼り付けてください。このコマンドは CI ログやコミットされたファイルに含めるべきではありません。設定されたベアラートークンと正確に一致しないリクエストは 401 Unauthorized を受け取ります。

デプロイ

チェックイン済みの Wrangler 設定は、すでにサービス ntfy-kyeshimizu に名前を付け、Workers Observability を有効にし、Topic SQLite Durable Object マイグレーションを宣言しています。デプロイは次のように行います：

npx wrangler deploy
npx wrangler secret put PUBLISH_TOKEN --name ntfy-kyeshimizu

デプロイされた HTTPS URL を NTFY_URL として使用し、WebSocket スモークチェックには ws:// の代わりに wss:// を使用します。シークレットを印刷したりコミットしたりしないでください。

サービスバインディングと型付き RPC

利用側の Worker の wrangler.jsonc で、名前付き RPC エントリポイントをバインドします：

{
  "services": [
    {
      "binding": "NTFY",
      "service": "ntfy-kyeshimizu",
      "entrypoint": "NtfyWorker"
    }
  ]
}

Wrangler を使用して利用側 Worker のバインディング型を生成します。パブリッシャー Worker の設定とこの Worker の設定が別々のプロジェクトである場合は、両方を含めます：

npx wrangler types -c wrangler.jsonc

生成された Env.NTFY は、エクスポートされた NtfyWorker エントリポイントから型付けされます。HTTP 資格情報なしで呼び出します：

const notification = await env.NTFY.publish("alerts", {
  message: "Published from another Worker",
  title: "Internal job",
  tags: ["worker"],
  priority: 3,
});

完全なパブリッシャーエントリポイントについては、examples/worker-publisher.ts を参照してください。サービスバインディングはプライベートな Worker 間呼び出しです。バインディングオブジェクトを信頼できないリクエストデータに公開しないでください。

OpenCode プラグイン、MCP、エージェントスキル

このリポジトリには、プロジェクトローカルの OpenCode プラグイン、MCP 設定、およびスキルが含まれています：

• .opencode/plugins/ntfy-cf.js はライフサイクル通知を自動的に送信します。

• opencode.jsonc はデプロイされた /mcp エンドポイントに接続します。

• .opencode/skills/ntfy-cf/SKILL.md は、エージェントにいつどのように通知するかを教えます。

このリポジトリから OpenCode を起動する前にトークンを設定します：

export NTFY_CF_TOKEN='replace-with-your-worker-secret'
export NTFY_CF_TOPIC='agent-status'
opencode2

OpenCode はプラグイン、ntfy-cf スキル、および ntfy MCP サーバーを自動的に検出します。プラグインは、ルートセッションが終了したとき、エラーが発生したとき、または権限を要求したときに通知を送信します。子セッションの完了イベントとエラーイベントは抑制されます。NTFY_CF_URL を設定して、デプロイされた Worker URL を上書きします。配信失敗はログに記録され、OpenCode セッションを中断することはありません。プラグインは OpenCode の V2 イベント API を対象としています。ctx.event.subscribe() をまだ公開していないプレビュービルドでは、プラグインは読み込まれますが、自動イベントは無効になります。

MCP は OAuth ではなくヘッダー認証を使用し、ステートレスな Streamable HTTP JSON-RPC リクエストをサポートします。トークンを OpenCode 設定にコミットしないでください。

他の MCP クライアントは以下に接続できます：

https://ntfy-kyeshimizu.kyeshimizu.workers.dev/mcp

すべてのリクエストで Authorization: Bearer <token> を送信します。エンドポイントは MCP の initialize、ping、tools/list、tools/call を実装しています。ランタイムの MCP フレームワーク依存関係はなく、Zod もバンドルしていません。

検証と運用

ローカルの自動スモークスイートと型チェックを実行します：

npm test
npm run typecheck

デプロイされたスモークテストでは、/healthz を確認し、使い捨てトピックに公開し、since=all でポーリングし、WebSocket ハンドシェイクを実行します。ベアラートークンが欠落しているか誤っているリクエストが 401 を返し、無効なルートが 404 を返すことを確認します。

Workers Observability は wrangler.jsonc でフルヘッドサンプリングで有効になっています。Cloudflare ダッシュボードまたは Wrangler ログを使用して、publish や websocket_error などの構造化イベントを検査します。Durable Object の履歴は境界があり、監査ログやアーカイブストアの代わりにはなりません。

互換性の制限

これはアップストリームの Go サーバーのドロップイン代替品ではありません。v1 は以下を実装していません：

• アップストリームの Web アプリケーション、ユーザーアカウント、アクセス制御リスト、トピック管理。

• Android FCM、iOS/APNs 転送、UnifiedPush、その他のモバイル配信。

• SSE、無期限の HTTP ストリーミング、ロングポールサブスクリプション。

• 添付ファイル/アップロード、添付ファイルストレージ、メール配信、音声通話、R2 統合。

• スケジュールまたは遅延配信。delay フィールドは拒否されます。

• この README に記載されていないアップストリームサーバー機能（完全な認証および管理 API を含む）。

このサービスは、プロセス内の通知履歴とライブ WebSocket 配信のみを提供します。メタデータフィールドは通知オブジェクトに含まれますが、外部の配信プロバイダーを有効化することはありません。