ntfy-cf

ntfy-cf는 ntfy API의 비공개 Workers 네이티브 하위 집합입니다. 배포된 Worker의 이름은 ntfy-kyeshimizu입니다.

아키텍처

공개 NtfyWorker는 토픽, 라우트, 요청 크기, Authorization: Bearer ... 토큰을 검증합니다. 각 토픽은 getByName(topic)을 통해 하나의 SQLite Durable Object(Topic)에 매핑됩니다. 이 객체는 최대 100개의 메시지를 최대 7일 동안 저장하고, 폴링 요청을 처리하며, 새 메시지를 하이버네이팅 WebSocket에 브로드캐스트합니다.

HTTP API는 게시, 폴링, WebSocket 구독에 bearer 토큰을 요구합니다. Worker 서비스 바인딩은 NtfyWorker에서 타입이 지정된 publish() RPC를 호출합니다. 이 비공개 경로는 HTTP 토큰을 요구하지 않습니다.

에이전트는 /mcp에 있는 인증된 Streamable HTTP 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: ntfy-me-mcp

로컬 개발

로컬 전용 .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"]}'

제한된 토픽 히스토리를 newline으로 구분된 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 이벤트로 도착합니다.

Bearer 토큰

토큰은 단일 Worker 시크릿이며 ntfy 사용자/계정 자격 증명이 아닙니다. Wrangler 인증 후에 구성합니다:

npx wrangler secret put PUBLISH_TOKEN --name ntfy-kyeshimizu

Wrangler가 프롬프트를 표시할 때만 토큰을 붙여넣습니다. 이 명령은 CI 로그나 커밋된 파일에 포함되어서는 안 됩니다. 구성된 bearer 토큰과 정확히 일치하지 않는 요청은 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"
    }
  ]
}

게시자 Worker의 구성과 이 Worker의 구성이 별도 프로젝트인 경우 이를 포함하여 Wrangler로 소비 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 핸드셰이크를 수행합니다. bearer 토큰이 없거나 잘못된 요청이 401을 반환하고 잘못된 라우트가 404를 반환하는지 확인합니다.

Workers Observability는 전체 헤드 샘플링과 함께 wrangler.jsonc에서 활성화됩니다. Cloudflare 대시보드 또는 Wrangler 로그를 사용하여 publish, websocket_error 같은 구조화된 이벤트를 검사합니다. Durable Object 히스토리는 제한되어 있으며 감사 로그나 아카이브 저장소를 대체하지 않습니다.

호환성 제한

이것은 업스트림 Go 서버를 대체하는 드롭인 솔루션이 아닙니다. v1은 다음을 구현하지 않습니다:

• 업스트림 웹 애플리케이션, 사용자 계정, 액세스 제어 목록, 토픽 관리.

• Android FCM, iOS/APNs 전달, UnifiedPush 또는 기타 모바일 전송.

• SSE, 무기한 HTTP 스트리밍 또는 롱폴링 구독.

• 첨부 파일/업로드, 첨부 파일 저장, 이메일 전송, 음성 통화 또는 R2 통합.

• 예약 또는 지연 전송. delay 필드는 거부됩니다.

• 이 README에 나열되지 않은 업스트림 서버 기능(전체 인증 및 관리 API 포함).

이 서비스는 프로세스 내 알림 히스토리와 실시간 WebSocket 전송만 제공합니다. 메타데이터 필드는 알림 객체에 포함되어 전달되며 외부 전송 제공자를 활성화하지 않습니다.