web-basics-mcp

Herramientas web pequeñas y fiables para agentes. Sin claves API ni infraestructura incluida.

Herramientas

fetch_url devuelve Markdown limpio para páginas HTML y publicaciones de Reddit, texto seleccionable para PDFs, contenido directo para respuestas de texto/Markdown/JSON/XML, y contenido de imagen MCP nativo para imágenes PNG, JPEG, WebP y GIF.

El texto largo se lee en fragmentos limitados. Llame a la misma URL nuevamente con el next_start_index devuelto:

{
  "url": "https://example.com/long-page",
  "start_index": 8000,
  "max_length": 8000
}

Las obtenciones exitosas se almacenan en caché en memoria durante cinco minutos, por lo que las lecturas offset normalmente usan el mismo documento extraído. Los resultados de búsqueda se almacenan en caché durante dos minutos para evitar repetir trabajo idéntico de SearXNG durante una ejecución del agente. Ambas cachés están limitadas, fusionan solicitudes duplicadas concurrentes y pueden descartarse en cualquier momento; la corrección de las herramientas nunca depende de ellas.

Related MCP server: Basic MCP Tools

Requisitos

• Node.js 20.18.1 o superior

• Una instancia existente de SearXNG con respuestas JSON habilitadas

Establezca su URL base en el entorno o en el archivo .env de este paquete:

SEARXNG_URL=http://127.0.0.1:8088

El servidor se inicia incluso cuando SearXNG no está disponible, por lo que fetch_url sigue siendo utilizable. Las llamadas a web_search devuelven un error de conexión claro hasta que SearXNG sea accesible.

Instalación

git clone https://github.com/yoloyash/web-basics-mcp.git
cd web-basics-mcp
npm install
npm run build

Configure un cliente MCP para ejecutar build/index.js sobre stdio. Por ejemplo:

codex mcp add web-basics -- node /absolute/path/to/web-basics-mcp/build/index.js

Entradas de las herramientas

web_search

{
  "query": "Model Context Protocol",
  "limit": 5
}

limit por defecto es 5 y acepta valores del 1 al 10. Los resultados usan la forma estable {link, title, snippet}.

fetch_url

{
  "url": "https://example.com",
  "start_index": 0,
  "max_length": 8000
}

• start_index por defecto es 0.

• max_length por defecto es 8000 y está limitado a 20000.

• Las respuestas de texto informan total_chars, returned_chars, truncated y, cuando queda más contenido, next_start_index.

• HTML usa Defuddle primero y Mozilla Readability como respaldo controlado. La respuesta informa el extractor seleccionado y el motivo del respaldo cuando corresponda.

• Los extractores opcionales respaldados por red de Defuddle están deshabilitados. Cada solicitud remota permanece en la ruta HTTP validada de este servidor.

• Las URLs de publicaciones de Reddit se obtienen a través del feed RSS de Reddit e incluyen la publicación más los comentarios disponibles en ese feed. RSS puede contener menos comentarios que el sitio web.

Seguridad y límites

• Solo se aceptan URLs HTTP(S) públicas.

• Se rechazan credenciales en URL, nombres de host privados, resultados DNS privados y redirecciones no seguras.

• Cada redirección se valida de forma independiente.

• Las solicitudes usan tiempos de espera, reintentos limitados, límites de tamaño de respuesta y un agente de usuario estable.

• Las respuestas estándar e imágenes están limitadas a 5 MiB; los PDFs están limitados a 15 MiB.

• El almacenamiento en caché de obtención respeta Cache-Control: no-store, no-cache y max-age=0.

Este servidor intencionalmente no proporciona automatización de navegador, renderizado de JavaScript, rastreo, autenticación, cookies, enrutamiento proxy/VPN ni síntesis de respuestas.

Desarrollo

npm test
npm pack --dry-run

Las pruebas usan fixtures guardados y stubs locales en lugar de consultar repetidamente servicios públicos.