Fresh402

npx add-mcp 'https://fresh402.kirilllabs.workers.dev/mcp'

Fresh402

Un oráculo de frescura de bajo costo para agentes de IA, impulsado por x402.

Fresh402 permite que un agente de IA registre un recurso web una sola vez y luego verifique de forma económica si ha cambiado materialmente antes de gastar dinero en una sesión de navegador, un scraper, una llamada a una API o contexto de LLM.

• Registro de línea base gratuito
• $0.005 USDC por verificación de frescura
• API REST
• Soporte MCP
• Pagos x402 en la red principal de Base
• IDs de vigilancia persistentes
• Monitoreo de HTML, JSON y texto
• Filtrado de ruido y diferencias deterministas

¿Por qué Fresh402?

Los agentes de IA a menudo necesitan responder una pregunta simple:

¿Ha cambiado este recurso desde la última vez que lo miré?

Obtener, renderizar, analizar y enviar una página completa a través de un LLM puede costar mucho más que responder esa pregunta.

Fresh402 actúa como un primer paso económico:

1. Registra un recurso de forma gratuita.
2. Recibe un watch_id persistente.
3. Pregunta a Fresh402 si ha cambiado.
4. Solo realiza trabajo costoso posterior cuando sea necesario.

API en vivo

Producción:

https://fresh402.kirilllabs.workers.dev

Salud y metadatos del servicio:

GET /

Precios

Operación	Precio
Registrar línea base	Gratis
Verificación de frescura	$0.005 USDC
Red	Red principal de Base
Protocolo de pago	x402

Inicio rápido

1. Registrar una línea base

El registro es gratuito.

curl -X POST \
  https://fresh402.kirilllabs.workers.dev/v1/register \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

Ejemplo de respuesta:

{
  "watch_id": "w_0123456789abcdef0123456789abcdef",
  "url": "https://example.com",
  "created": true,
  "baseline_created": true,
  "content_kind": "html"
}

Registrar el mismo recurso nuevamente devuelve la línea base existente sin volver a obtenerlo.

Eso evita que el endpoint de registro gratuito se use como una verificación de frescura repetida gratuita.

2. Verificar el recurso

curl -X POST \
  https://fresh402.kirilllabs.workers.dev/v1/check \
  -H "Content-Type: application/json" \
  -d '{"watch_id":"w_0123456789abcdef0123456789abcdef","include_diff":true}'

Sin pago, Fresh402 devuelve un requisito de pago x402.

El precio actual es $0.005 USDC en la red principal de Base (eip155:8453).

Un cliente compatible con x402 puede satisfacer el requisito de pago y reintentar la solicitud automáticamente.

API REST

POST /v1/register

Crea o recupera una línea base persistente de forma gratuita.

Ejemplo con alcance HTML:

{
  "url": "https://example.com/pricing",
  "selector": "#pricing",
  "ignore_selectors": [
    ".timestamp",
    ".advertisement"
  ]
}

Para recursos JSON:

{
  "url": "https://api.example.com/data",
  "ignore_json_paths": [
    "/generated_at",
    "/items/*/last_seen"
  ]
}

Se admiten segmentos de puntero JSON con comodín *.

POST /v1/check

Verificación de frescura de pago.

{
  "watch_id": "w_0123456789abcdef0123456789abcdef",
  "max_age_seconds": 300,
  "include_diff": true
}

Las entradas admitidas incluyen:

• watch_id
• url
• previous_hash
• selector
• ignore_selectors
• ignore_json_paths
• max_age_seconds
• include_diff

max_age_seconds permite que los agentes reutilicen el estado de Fresh402 compartido suficientemente fresco en lugar de forzar otra obtención ascendente.

GET /v1/history

Recupera el historial de instantáneas almacenado usando un watch_id o URL.

GET /v1/diff

Recupera información de cambios para un recurso vigilado.

GET /v1/stats

Recupera estadísticas públicas de uso del servicio.

MCP

Fresh402 expone un endpoint MCP HTTP transmisible:

https://fresh402.kirilllabs.workers.dev/mcp

Herramientas disponibles:

fresh402_register

Gratis.

Crea o recupera una línea base persistente y devuelve un watch_id.

fresh402_check

Cuesta $0.005 USDC.

Verifica si un recurso registrado o proporcionado por el llamador ha cambiado.

La herramienta expone metadatos de pago x402 para que los agentes compatibles puedan descubrir y pagar la operación programáticamente.

Detección de cambios

Fresh402 está diseñado para reducir falsos positivos provenientes de ruido irrelevante en la página.

Alcance de selector HTML

Monitorea solo una parte de la página:

{
  "url": "https://example.com/pricing",
  "selector": "#pricing"
}

Filtrado de ruido HTML

Elimina elementos volátiles antes de la huella digital:

{
  "ignore_selectors": [
    ".timestamp",
    ".visitor-counter",
    ".advertisement"
  ]
}

JSON canónico

El JSON se canonicaliza antes de aplicar hash, por lo que el orden de las claves del objeto no causa cambios falsos.

Ignorar punteros JSON

Los campos JSON volátiles conocidos se pueden eliminar antes de la huella digital.

{
  "ignore_json_paths": [
    "/generated_at",
    "/items/*/last_seen"
  ]
}

Revalidación HTTP condicional

Fresh402 puede usar metadatos ETag y Last-Modified ascendentes cuando estén disponibles.

Diferencia determinista

Cuando existe contenido anterior comparable, include_diff: true puede devolver un resumen de cambios determinista y compacto.

Vigilancias persistentes

Fresh402 v1.1 introdujo vigilancias persistentes para agentes.

Un recurso registrado recibe un identificador estable:

w_0123456789abcdef0123456789abcdef

Fresh402 almacena el estado de vigilancia y un historial de instantáneas limitado en Cloudflare D1.

El registro gratuito repetido no actualiza una vigilancia existente. Se requiere una verificación de pago para obtener el estado ascendente fresco.

Arquitectura

Fresh402 actualmente usa:

• Cloudflare Workers
• Cloudflare D1
• Infraestructura x402 de Coinbase / CDP
• Red principal de Base
• USDC
• Protocolo de Contexto de Modelo (MCP)
• TypeScript

El objetivo es mantener las verificaciones de frescura lo suficientemente económicas para que los agentes puedan usar Fresh402 antes de trabajos más costosos de navegación, scraping o razonamiento.

Seguridad

Fresh402 valida los destinos salientes e incluye protecciones destinadas a reducir el riesgo de SSRF.

Las credenciales de pago y los secretos de implementación se suministran a través de la configuración del entorno en tiempo de ejecución y no se almacenan en este repositorio.

Límites de recursos

• Los nuevos registros gratuitos (REST y MCP combinados) están limitados a 10 intentos por nombre de host de destino y 60 intentos en total por 60 segundos, en cada ubicación de Cloudflare. Las rutas, consultas, puertos y variantes de reglas de selector/ignorar comparten el límite del nombre de host. Los intentos ascendentes fallidos también consumen cuota. Las vigilancias existentes se devuelven sin una obtención ni cargo de cuota; las verificaciones de pago no usan estos límites.
• REST devuelve 429 registration_rate_limited con Retry-After: 60 cuando se alcanza un límite. Los enlaces de límite de tasa faltantes o no disponibles devuelven 503 registration_unavailable para nuevos registros. MCP informa estos a través de la ruta de error de herramienta existente.
• Cada cuerpo POST entrante está limitado a 65,536 bytes antes del análisis JSON, manejo de pago, despacho MCP o clonación (413 request_too_large). Leer un cuerpo entrante tiene un plazo de 10 segundos (408 request_timeout).
• Los cuerpos de respuesta ascendentes se transmiten con un límite de 5,000,000 bytes (413 content_too_large), incluso cuando Content-Length está ausente o es engañoso. Un solo plazo de 10 segundos cubre redirecciones, encabezados y lectura del cuerpo (504 upstream_timeout). Las transmisiones no utilizadas y rechazadas se cancelan.
• La creación concurrente de la misma vigilancia guarda solo una línea base y una instantánea inicial. Un registro gratuito perdedor devuelve la línea base almacenada; las solicitudes iniciales superpuestas aún pueden realizar obtenciones ascendentes separadas, sujetas a los límites de registro.

Los dos enlaces de límite de tasa y sus umbrales se declaran en wrangler.jsonc; mantén sus IDs de espacio de nombres únicos dentro de la cuenta de Cloudflare. Estos límites de Cloudflare son locales a cada ubicación y eventualmente consistentes. Mitigan ráfagas pero no son una cuota mundial estricta ni un límite de almacenamiento/facturación. Los usuarios legítimos que comparten un nombre de host de destino también comparten su asignación. El indicador de compatibilidad global_fetch_strictly_public permanece habilitado para proteger contra direcciones privadas alcanzadas a través de DNS.

Verificación local

Usa Node.js 24 y luego ejecuta:

npm ci
npx tsc --noEmit
npx tsc --noEmit -p test/tsconfig.json
npm test -- --run

Las pruebas usan un entorno de ejecución de Workers local, datos D1 aislados y solicitudes ascendentes simuladas. No requieren credenciales de pago ni acceden a producción. GitHub Actions ejecuta estas mismas verificaciones en solicitudes de extracción y envíos a main; el flujo de trabajo no tiene paso de implementación.

Versión actual

v1.1.1

Aspectos destacados:

• watch_id persistente
• Registro de línea base gratuito
• Comportamiento anti-refresco gratuito
• Alcance de selector HTML
• Selectores de ignorar HTML
• Monitoreo JSON canónico
• Rutas de ignorar puntero JSON con comodín
• Caché de frescura compartida
• previous_hash proporcionado por el llamador
• Diferencia en línea determinista
• Revalidación ETag / Last-Modified
• Retención de instantáneas limitada
• Soporte REST y MCP

Estado

Fresh402 está en vivo y usable hoy.

El proyecto aún es temprano y la API puede evolucionar a medida que los patrones de uso real de agentes se aclaren.

Autor

Construido y mantenido por Kirill Radchenko.

Los problemas, integraciones, comentarios y casos de uso de agentes de IA son bienvenidos.