ntfy-cf

ntfy-cf es un subconjunto privado y nativo de Workers de la API de ntfy. El Worker desplegado se llama ntfy-kyeshimizu.

Arquitectura

El NtfyWorker público valida los temas, las rutas, los tamaños de las solicitudes y el token Authorization: Bearer .... Cada tema se asigna a un Durable Object de SQLite (Topic) mediante getByName(topic). El objeto almacena como máximo 100 mensajes durante un máximo de 7 días, atiende solicitudes de polling y difunde mensajes nuevos a los WebSockets hibernados.

La API HTTP requiere el token bearer para publicar, hacer polling y suscribirse por WebSocket. Un service binding de Worker invoca la RPC tipada publish() en NtfyWorker; esa ruta privada no requiere el token HTTP.

Los agentes pueden usar el mismo servicio a través del endpoint MCP Streamable HTTP autenticado en /mcp. Expone publish_notification y get_notifications.

Los temas deben coincidir con [A-Za-z0-9._-]+ y no tener más de 128 caracteres. Los cuerpos HTTP y las notificaciones RPC están limitados a 64 KiB. Los mensajes publicados usan objetos JSON de estilo ntfy con event, id, time, topic, message y metadatos opcionales como title, tags, priority, click, actions, attach, filename, email, call e icon.

Related MCP server: ntfy-me-mcp

Desarrollo local

Cree un archivo .dev.vars solo local (Wrangler lo ignora):

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

Inicie el Worker:

npm install
npm run types
npx wrangler dev

Use el mismo valor de .dev.vars en los ejemplos siguientes. No haga commit de .dev.vars ni coloque un token en código fuente, historial de shell o documentación.

API HTTP

Defina una variable de shell con un token que haya creado localmente o que tenga almacenado en su gestor de secretos:

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

Publique texto plano con cabeceras compatibles con 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'

Publique metadatos 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"]}'

Consulte el historial acotado del tema como JSON delimitado por nuevas líneas. since=all (o la ausencia de since) devuelve el historial retenido; una marca de tiempo Unix devuelve los mensajes posteriores; un ID de mensaje existente devuelve los mensajes posteriores a ese ID.

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

Compruebe la disponibilidad:

curl -i "$NTFY_URL/healthz"

El endpoint WebSocket es /<topic>/ws. Un handshake con curl es útil para una comprobación rápida, pero curl no es un cliente WebSocket y no consumirá cómodamente los frames posteriores:

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

Para una suscripción en vivo, use un cliente WebSocket como websocat y utilice ws://localhost:8787/alerts/ws con una cabecera Authorization. El primer frame es un evento open; las publicaciones posteriores llegan como eventos message.

Token bearer

El token es un secreto único de Worker, no una credencial de usuario/cuenta de ntfy. Configúrelo después de autenticar Wrangler:

npx wrangler secret put PUBLISH_TOKEN --name ntfy-kyeshimizu

Pegue el token solo cuando Wrangler lo solicite. El comando no debe aparecer en registros de CI ni en archivos incluidos en un commit. Las solicitudes sin el token bearer configurado exactamente reciben 401 Unauthorized.

Despliegue

La configuración de Wrangler incluida en el repositorio ya da nombre al servicio ntfy-kyeshimizu, habilita Workers Observability y declara la migración del Durable Object SQLite Topic. Despliegue con:

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

Use la URL HTTPS desplegada como NTFY_URL y wss:// en lugar de ws:// para la comprobación de WebSocket. Nunca imprima ni haga commit del secreto.

Service bindings y RPC tipada

En el wrangler.jsonc de un Worker consumidor, enlace el entrypoint RPC nombrado:

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

Genere los tipos de binding del Worker consumidor con Wrangler, incluidos la configuración del Worker publicador y la configuración de este Worker cuando son proyectos separados:

npx wrangler types -c wrangler.jsonc

El Env.NTFY generado se tipa a partir del entrypoint exportado NtfyWorker. Llámelo sin credenciales HTTP:

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

Consulte examples/worker-publisher.ts para ver un entrypoint de publicador completo. Los service bindings son llamadas privadas de Worker a Worker; no exponga el objeto de binding a datos de solicitudes no confiables.

Plugin de OpenCode, MCP y skill de agente

El repositorio incluye un plugin de OpenCode local al proyecto, una configuración de MCP y una skill:

• .opencode/plugins/ntfy-cf.js envía automáticamente notificaciones de ciclo de vida.

• opencode.jsonc conecta el endpoint /mcp desplegado.

• .opencode/skills/ntfy-cf/SKILL.md enseña a los agentes cuándo y cómo notificar.

Defina el token antes de iniciar OpenCode desde este repositorio:

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

OpenCode descubre automáticamente el plugin, la skill ntfy-cf y el servidor MCP ntfy. El plugin envía notificaciones cuando una sesión raíz termina, encuentra un error o solicita permiso. La finalización de sesiones hijas y los eventos de error se suprimen. Defina NTFY_CF_URL para sobrescribir la URL del Worker desplegado. Los fallos de entrega se registran y nunca interrumpen la sesión de OpenCode. El plugin apunta a la API de eventos V2 de OpenCode; las versiones preliminares que aún no exponen ctx.event.subscribe() cargan el plugin pero desactivan los eventos automáticos.

El MCP usa autenticación mediante cabecera en lugar de OAuth y admite solicitudes JSON-RPC sin estado a través de Streamable HTTP. No haga commit del token en la configuración de OpenCode.

Otros clientes MCP pueden conectarse a:

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

Envíe Authorization: Bearer <token> en cada solicitud. El endpoint implementa los métodos MCP initialize, ping, tools/list y tools/call; no tiene dependencia de ningún framework MCP en tiempo de ejecución y no incluye Zod.

Verificación y operaciones

Ejecute la suite de pruebas de humo automatizada local y la comprobación de tipos:

npm test
npm run typecheck

Para una prueba de humo del despliegue, verifique /healthz, publique en un tema desechable, consúltelo con since=all y realice el handshake por WebSocket. Confirme que una solicitud con un token bearer ausente o incorrecto devuelve 401 y que una ruta no válida devuelve 404.

Workers Observability está habilitado en wrangler.jsonc con muestreo head completo. Use el panel de Cloudflare o los registros de Wrangler para inspeccionar eventos estructurados como publish y websocket_error. El historial de Durable Objects está acotado y no sustituye a un registro de auditoría ni a un almacén de archivo.

Límites de compatibilidad

Esto no es un reemplazo directo del servidor Go original. v1 no implementa:

• La aplicación web original, las cuentas de usuario, las listas de control de acceso o la gestión de temas.

• Reenvío de Android FCM, iOS/APNs, UnifiedPush u otras entregas móviles.

• SSE, streaming HTTP indefinido o suscripciones de long-poll.

• Adjuntos/subidas, almacenamiento de adjuntos, entrega de correo electrónico, llamadas de voz o integración con R2.

• Entrega programada o retrasada. Un campo delay es rechazado.

• Funciones del servidor original no enumeradas en este README, incluidas las API completas de autenticación y administración.

El servicio solo proporciona historial de notificaciones en proceso y entrega en vivo por WebSocket. Los campos de metadatos se transportan en los objetos de notificación; no activan proveedores de entrega externos.