SmartFetch V1.8 — Descubribilidad de MCP

SmartFetch toma una URL web pública y devuelve texto limpio listo para agentes, Markdown, enlaces, metadatos y el método de recuperación utilizado. Primero intenta una recuperación HTTP económica y recurre a un navegador Chromium real cuando es necesario.

Cambios en V1.8

• La herramienta de MCP de pago fetch_webpage ahora declara metadatos oficiales de x402 Bazaar para el descubrimiento por parte de agentes sin cambiar su comportamiento de ejecución ni de pago.

• El server.json raíz anuncia el endpoint existente /mcp Streamable HTTP como un servidor exclusivamente remoto para el Registro Oficial de MCP.

• No se realiza ninguna publicación en el Registro, despliegue, cambio de variables de Railway ni pago con esta actualización del repositorio.

Todo el comportamiento de pago HTTP, Bazaar y MCP nativo de V1.7 permanece sin cambios:

• Base Sepolia sigue siendo la red x402 predeterminada y continúa usando https://x402.org/facilitator sin credenciales CDP.

• La mainnet de Base puede usar el facilitador CDP autenticado de Coinbase cuando se selecciona explícitamente.

• El arranque en mainnet requiere ambas credenciales de CDP y se bloquea (fail closed) ante credenciales no válidas o falta de soporte del facilitador.

• /meta distingue los modos de pago de testnet y mainnet habilitados.

• cdp-sdk, FastAPI, Uvicorn y x402 están fijados exactamente para que las actualizaciones de infraestructura sean explícitas.

El motor de recuperación, el comportamiento de extracción/navegador, las protecciones SSRF, los límites de solicitudes, la limitación de frecuencia y los controles de concurrencia no cambian.

Related MCP server: SteadyFetch

API

GET /health

Devuelve el estado/versión del servicio.

GET /meta

Descripción del servicio legible por máquina.

POST /fetch

{
  "url": "https://example.com/article",
  "max_chars": 20000,
  "force_browser": false
}

max_chars es opcional (mínimo 1.000; predeterminado 20.000; máximo 50.000).

Campos de ejemplo de la respuesta:

{
  "success": true,
  "requested_url": "https://example.com/article",
  "final_url": "https://example.com/article",
  "status_code": 200,
  "render_method": "http",
  "title": "…",
  "content": "…",
  "markdown": "…",
  "links": [],
  "word_count": 1000,
  "content_hash": "…",
  "truncated": false,
  "elapsed_ms": 350,
  "request_id": "…",
  "service_version": "1.8.0"
}

Cuando la protección de pago x402 está habilitada, el encabezado PAYMENT-REQUIRED para POST /fetch incluye una declaración Bazaar con el contrato de entrada url, max_chars y force_browser, además de una respuesta exitosa representativa. /, /health y /meta siguen siendo gratuitos y no anuncian metadatos Bazaar.

MCP

Los clientes MCP remotos se conectan a /mcp mediante Streamable HTTP. El servidor expone exactamente una herramienta:

fetch_webpage
  url: required string
  max_chars: optional integer (default 20000, minimum 1000, maximum 50000)
  force_browser: optional boolean (default false)

La herramienta lee, obtiene, hace scraping o extrae páginas web públicas para agentes y devuelve el texto, Markdown, enlaces y metadatos de recuperación existentes de SmartFetch. Usa la misma validación SSRF, ejecutor, tiempo de espera de solicitud, límite de concurrencia, límite de salida, recuperación HTTP y respaldo de navegador que POST /fetch; no realiza una solicitud HTTP de vuelta a la API pública.

Cuando x402 está habilitado, una llamada tools/call no pagada devuelve el desafío de pago x402 nativo de MCP. Un pago válido se verifica antes de la recuperación y se liquida una vez tras la ejecución exitosa de la herramienta. La red, el beneficiario público y el precio provienen de X402_NETWORK, X402_PAY_TO y X402_PRICE. No se acepta ni se requiere ninguna clave privada de vendedor ni secreto de cartera.

El desafío de pago MCP no pagado incluye una declaración Bazaar para fetch_webpage con transporte streamable-http, el contrato de entrada existente y una salida representativa de SmartFetch. Su recurso de pago sigue siendo mcp://tool/fetch_webpage. El recurso HTTP Bazaar existente para POST /fetch es independiente y no cambia.

El server.json raíz describe el endpoint remoto público en https://smartfetch-production-ea53.up.railway.app/mcp. La publicación en el Registro es una acción de operador autenticada separada; agregar el manifiesto no publica ni despliega el servicio.

Ejecutar localmente

python -m pip install -r requirements.txt
python -m smartfetch.server

Luego:

curl http://127.0.0.1:8787/health
curl -X POST http://127.0.0.1:8787/fetch \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com"}'

Los usuarios de Windows pueden ejecutar setup_windows.bat y luego start_windows.bat.

Con X402_ENABLED sin establecer o en false, el arranque no requiere ajustes de pago y /fetch sigue siendo gratuito para pruebas locales y remotas.

Modos de pago x402

El pago permanece deshabilitado a menos que se habilite explícitamente. Base Sepolia es la opción predeterminada y solo requiere la dirección pública receptora:

X402_ENABLED=true
X402_PAY_TO=0xYOUR_PUBLIC_RECEIVING_ADDRESS
X402_PRICE=$0.005
X402_NETWORK=eip155:84532

X402_PRICE y X402_NETWORK usan los valores mostrados cuando se omiten. El precio predeterminado sigue siendo $0.005.

La mainnet de Base debe seleccionarse explícitamente y usa el facilitador CDP autenticado de Coinbase:

X402_ENABLED=true
X402_PAY_TO=0xYOUR_PUBLIC_RECEIVING_ADDRESS
X402_PRICE=$0.005
X402_NETWORK=eip155:8453
CDP_API_KEY_ID=YOUR_CDP_API_KEY_ID
CDP_API_KEY_SECRET=YOUR_CDP_API_KEY_SECRET

La mainnet requiere ambas credenciales CDP. Las credenciales ausentes, no válidas o inutilizables, los pagos exactos no admitidos en la mainnet de Base o cualquier fallo de inicialización del facilitador/middleware abortan el arranque. SmartFetch nunca recurre al acceso gratuito ni al facilitador de testnet cuando se selecciona mainnet. Cualquier red distinta de Base Sepolia y la mainnet de Base es rechazada.

Solo POST /fetch está protegido. /health, / y /meta siempre permanecen gratuitos. Las respuestas /meta habilitadas informan x402-enabled-testnet o x402-enabled-mainnet sin exponer valores de configuración.

SmartFetch usa X402_PAY_TO como dirección pública receptora y no necesita CDP_WALLET_SECRET. Nunca proporcione una clave privada de vendedor de MetaMask ni una frase de recuperación: SmartFetch no requiere, lee, acepta, registra ni almacena ninguna de las dos.

Validación local

python tests/security_smoke.py
python tests/api_local_smoke.py

api_local_smoke.py habilita intencionadamente el acceso a la red privada solo dentro del proceso de prueba para poder usar una fixture de localhost.

Contenedor

docker build -t smartfetch:v1.8 .
docker run --rm -p 8787:8787 smartfetch:v1.8

El contenedor instala Chromium automáticamente.

Despliegue público

Este paquete está listo para Docker. Railway puede desplegar el Dockerfile y railway.json incluidos; cualquier host Docker que proporcione HTTPS saliente y suficiente RAM para un proceso de Chromium también debería funcionar.

Variables de entorno iniciales recomendadas:

MAX_CONCURRENT_BROWSERS=1
MAX_CONCURRENT_FETCHES=4
DEFAULT_MAX_OUTPUT_CHARS=20000
MAX_OUTPUT_CHARS=50000
FETCH_TIMEOUT_SECONDS=12
BROWSER_TIMEOUT_SECONDS=15
TOTAL_REQUEST_TIMEOUT_SECONDS=25
RATE_LIMIT_PER_MINUTE=30
RATE_LIMIT_BURST=10
X402_ENABLED=false

No establezca ALLOW_PRIVATE_NETWORK=1 en producción.

Nota importante sobre SSRF en el despliegue

La validación de URL a nivel de aplicación está incluida, pero el renderizado del navegador puede ejecutar subrecursos de la página. Para un despliegue público de pago, el contenedor del navegador debe aislarse adicionalmente mediante una política de salida de host/red de los metadatos de la nube y de las redes privadas RFC1918. Reforzaremos esto de nuevo antes de eliminar el límite de frecuencia temporal y antes del lanzamiento de x402.

Probar el despliegue público

En Windows, ejecute test_remote_windows.bat, pegue la URL pública y cargue tests/remote_20_results.json.

O bien:

python tests/remote_20.py https://YOUR-PUBLIC-URL

Nuestro umbral de despliegue sigue siendo mínimo 18/20, incluidas las cinco solicitudes forzadas de navegador.

Estado del lanzamiento de pago

V1.8 conserva la configuración de pago existente de Base Sepolia y de la mainnet de Base. Este cambio del repositorio no publica por sí mismo en el Registro MCP, no despliega el servicio ni modifica las variables de Railway. La red de pago activa está controlada por X402_NETWORK: eip155:84532 para Base Sepolia o eip155:8453 para la mainnet de Base.