search-rotation
Rotación de búsqueda web y extracción de páginas en los niveles gratuitos de varios proveedores, con un panel local para claves, orden de motores y estado de cuota.
Documentación
Un servidor MCP para búsqueda web y extracción de páginas en múltiples proveedores.
Creado por Robin Bially.
Rota entre las cuotas disponibles, cambia automáticamente a otro proveedor cuando uno no está disponible y devuelve resultados consistentes a tu asistente de IA. Un panel local te permite gestionar claves de API, reordenar motores, consultar cuotas e inspeccionar el historial de solicitudes.
Interfaz real del panel, mostrada en inglés con datos de demostración ilustrativos. Las llamadas y los presupuestos de los proveedores se muestran por separado; las barras de actividad ofrecen detalles por ventana de tiempo y por motor.
Inicio rápido
npm
npx -y search-rotation --http --open
Requiere Node.js 20.3+. Para MCP sobre stdio, configura tu cliente para ejecutar
npx -y search-rotation sin argumentos. El servidor también está listado en el
Registro oficial de MCP
como io.github.robin-bially/search-rotation.
Homebrew
brew install robin-bially/tap/search-rotation
search-rotation --http --open
Homebrew instala el runtime de Node.js requerido. Para MCP sobre stdio, configura tu
cliente para ejecutar search-rotation sin argumentos. Consulta el
tap de Homebrew para actualizaciones y detalles.
Versión fija desde GitHub
npx -y --allow-git=all github:robin-bially/search-rotation-mcp#v0.4.11
Úsalo cuando quieras una versión fija en lugar de la versión actual de npm.
Añade tus claves de proveedor en el panel y luego conecta tu asistente usando la guía de configuración del cliente MCP para Codex, Claude, Cursor u OpenCode.
Lo que obtienes
- Búsqueda y extracción: rotación independiente para búsqueda web y extracción de páginas en Markdown.
- Conmutación automática por error: orden basado en cuotas, períodos de enfriamiento por límite de tasa y tiempos de espera de solicitud.
- Panel local: claves de API, orden de motores mediante arrastrar y soltar, llamadas y errores por motor, saldos de cuota separados e historial interactivo de solicitudes.
- Local o remoto: MCP sobre stdio o Streamable HTTP autenticado.
Proveedores: Tavily · Firecrawl · Parallel · Exa · Google PSE · Jina Reader · DuckDuckGo HTML. Acceso sin clave y contabilidad de cuotas varían según el proveedor.
Herramientas MCP
web_search · fetch_url · engine_status · open_dashboard
La pestaña Herramientas MCP del panel explica cada herramienta, sus parámetros y ejemplos de llamadas copiables.
Interfaz real del panel, mostrada en inglés.
Filtros de tiempo de búsqueda
web_search acepta los siguientes argumentos:
| Parámetro | Significado |
|---|---|
query | Texto de búsqueda requerido. |
numResults | Número de resultados opcional, 1–20; de lo contrario, se aplica la configuración del panel. |
engine | Proveedor preferido, sujeto a la compatibilidad con filtros de tiempo y disponibilidad; la conmutación por error permanece habilitada. |
timeRange | day, week, month o year: ventana de fecha UTC que comienza hace 1, 7, 30 o 365 días, hasta hoy. |
startDate | Límite de fecha inferior opcional en formato YYYY-MM-DD. |
endDate | Límite de fecha superior opcional en formato YYYY-MM-DD. |
Usa timeRange o fechas explícitas. Se permiten límites unilaterales y fechas de inicio y fin iguales; las fechas de calendario inválidas, los límites invertidos y la mezcla de filtros relativos y explícitos se rechazan antes de cualquier solicitud al proveedor.
{"name":"web_search","arguments":{"query":"AI inference research","timeRange":"week","numResults":5}}
{"name":"web_search","arguments":{"query":"AI inference research","startDate":"2026-08-01","endDate":"2026-08-31"}}
Las ventanas relativas se resuelven una vez por solicitud en fechas UTC, incluso durante la conmutación por error. Son filtros de fecha, no ventanas exactas de 24 horas; month y year significan 30 y 365 días, no aritmética de calendario. Exa recibe el inicio del primer día UTC y el final del último día UTC.
Compatibilidad de proveedores y rotación
| Proveedor / acceso | Ventana relativa | Dos límites de fecha | Un límite de fecha |
|---|---|---|---|
| Tavily, con o sin clave | Sí | Sí | Sí |
| Firecrawl, con o sin clave | Sí | Sí | Omitido |
| Exa, API directa con clave | Sí | Sí | Sí |
| Exa, MCP alojado sin clave | Omitido | Omitido | Omitido |
| Parallel, cualquier modo de acceso | Omitido | Omitido | Omitido |
| Google PSE / DuckDuckGo HTML | Omitido | Omitido | Omitido |
Esta tabla describe la compatibilidad implementada en search-rotation, no todas las funciones ascendentes. Tavily recibe start_date / end_date, Firecrawl recibe un rango personalizado tbs y Exa recibe startPublishedDate / endPublishedDate. Firecrawl se excluye de forma conservadora para fechas unilaterales; las otras rutas omitidas no tienen un mapeo de fechas implementado.
El enrutador excluye proveedores incompatibles antes de las verificaciones de cuota y la rotación, incluso cuando se prefiere un engine incompatible. Cada grupo de proveedores elegibles tiene su propio cursor de rotación, por lo que mezclar búsquedas filtradas y sin filtrar no deja sin recursos a los proveedores. Las prioridades de cuota existentes, los períodos de enfriamiento, las reglas estrictas sin costo y la conmutación por error se aplican dentro de ese grupo. Si no hay un proveedor compatible disponible, la búsqueda falla explícitamente; nunca reintenta sin el filtro. Las búsquedas sin argumentos de tiempo conservan el acceso a todos los proveedores elegibles.
Los resultados muestran una fecha de publicación cuando el adaptador la proporciona, y el historial de solicitudes incluye el período solicitado. Los metadatos de fecha del proveedor pueden ser estimados o faltar: Tavily filtra fechas de publicación o actualización, Exa filtra fechas de publicación estimadas y Firecrawl usa la interpretación de fechas de su índice de búsqueda. La inclusión exacta de los límites sigue al proveedor; esto no es una verificación independiente de la fecha de publicación de cada página. Consulta las referencias de Tavily, Firecrawl y Exa.
Después de actualizar, vuelve a conectar tu cliente MCP para cargar el nuevo esquema de herramientas.
Publicación de versiones
VERSION=0.4.10 ./scripts/release.sh --publish
El script verifica el paquete (npm ci, compilación, pruebas, npm run smoke:package), incrementa la versión, apunta los pines de documentos a ella, confirma y etiqueta, empaqueta el tarball con su checksum, crea la versión de GitHub, actualiza la fórmula en robin-bially/homebrew-tap y finalmente espera hasta que el registro npm sirva la nueva versión. Sin --publish solo prepara los artefactos en .build/releases; --dry-run verifica los requisitos previos, --draft crea una versión borrador y --force tolera un árbol de trabajo sucio. El tap se clona temporalmente cuando TAP_DIR no está configurado, por lo que una copia nueva es suficiente.
La publicación en npm ocurre en .github/workflows/publish.yml mediante publicación confiable una vez que la versión de GitHub se publica, por lo que el script en sí no necesita credenciales de npm. El flujo de trabajo requiere un publicador confiable para search-rotation en npmjs.com que apunte a este repositorio y publish.yml.
El mismo flujo de trabajo registra la versión en el Registro oficial de MCP desde server.json. Distribución y listados rastrea cada canal, quién lo mantiene actualizado y qué necesita cada uno.
Aprende más
Configuración del cliente · Operaciones y configuración (DE) · Distribución y listados · Versiones · CI · Licencia MIT