Private Search Gateway

Este proyecto es un backend determinista y autoalojado de búsqueda y recuperación de páginas para frontends de IA. Expone un endpoint de búsqueda compatible con SearXNG, descubre fuentes con un pequeño conjunto de motores de búsqueda, abre las páginas más relevantes, extrae su contenido real, sigue un número limitado de enlaces relevantes del mismo sitio, reordena la evidencia localmente y devuelve las URL de las fuentes citadas y el texto derivado de la página.

No utiliza una API de búsqueda de pago ni un modelo de lenguaje interno. El modelo del frontend recibe la evidencia recuperada y redacta la respuesta. Esto mantiene el servicio privado, predecible y utilizable por cualquier frontend que acepte un proveedor de búsqueda SearXNG o JSON personalizado.

Componentes

• search-gateway: el único servicio orientado al cliente, en el puerto interno 8080

• searxng: descubrimiento web, técnico, de noticias, imágenes e investigación

• reranker: clasificación de relevancia local BAAI/bge-reranker-base

• crawl4ai: rastreo con capacidad de JavaScript para páginas difíciles

• web-runner: control aislado de Crawl4AI y Playwright a través de un socket Unix

• pdf-runner: extracción de PDF con aislamiento de red

• safe-egress: bloquea destinos de red privada y metadatos para los navegadores

• redis: caché de respuestas y respaldo de resultados obsoletos

El stack no publica ningún puerto del host. Un frontend lo alcanza a través de una red Docker compartida en:

http://search-gateway:8080/search

Cada contenedor conectado a esa red compartida puede llamar a la puerta de enlace. Utilice una red compartida dedicada si otros contenedores no relacionados no deben tener acceso.

Related MCP server: wigolo

Requisitos

• VPS Linux de 64 bits

• Docker Engine y Docker Compose v2.24.4 o superior

• Aproximadamente 10 GB de espacio libre en disco para imágenes, Chromium y el modelo de reordenación

• Se recomiendan 16 GB de RAM para el stack completo

Los límites proporcionados suman aproximadamente 10.5 GB, excluyendo la memoria compartida y la sobrecarga normal de Docker. Son límites, no reservas, pero dejan un margen útil en un host de 16 GB. La primera compilación es lenta porque descarga Chromium, la imagen de Crawl4AI y el modelo de reordenación.

Instalación limpia

Cree la red Docker una vez si aún no existe:

docker network inspect docker-stacks_app-network >/dev/null 2>&1 || \
  docker network create docker-stacks_app-network

Clone y configure el proyecto:

git clone https://github.com/ZDOSt/Research-MCP.git
cd Research-MCP
cp .env.example .env
chmod 600 .env

Genere dos secretos diferentes:

openssl rand -hex 32
openssl rand -hex 32

Edite .env y reemplace SEARXNG_SECRET y CRAWL4AI_API_TOKEN con esos valores. Cambie CLIENT_DOCKER_NETWORK solo si su frontend utiliza una red Docker externa diferente.

Valide e inicie el stack completo:

docker compose config --quiet
docker compose up -d --build --wait
docker compose ps

No se necesitan entradas ports:. No agregue una a menos que desee exponer intencionalmente la puerta de enlace fuera de Docker.

Verificación

Ejecute una comprobación de estado desde el contenedor de la puerta de enlace:

docker compose exec -T search-gateway python -c \
  "import urllib.request; print(urllib.request.urlopen('http://127.0.0.1:8080/healthz').read().decode())"

Ejecute una búsqueda real desde cualquier contenedor en la red compartida. Reemplace your-frontend-container con anythingllm, librechat u otro nombre de contenedor:

docker exec your-frontend-container sh -lc \
  "wget -qO- 'http://search-gateway:8080/search?q=how+to+install+docker+compose&format=json' | head -c 1000"

La respuesta debe contener results, URL de fuentes, content extraído y diagnósticos. Los fragmentos de búsqueda se utilizan solo como respaldo claramente etiquetado cuando un sitio bloquea la extracción o se alcanza el plazo de la solicitud.

Configuración del frontend

Utilice la siguiente URL base donde el frontend solicite una URL de SearXNG:

http://search-gateway:8080

Si solicita la ruta de búsqueda completa, utilice:

http://search-gateway:8080/search

AnythingLLM requiere la ruta de búsqueda completa aunque su campo esté etiquetado como SearXNG API Base URL. Configúrelo como:

http://search-gateway:8080/search

La solicitud estándar es:

GET /search?q=your+question&format=json

Los parámetros de consulta admitidos incluyen:

• language=auto

• time_range=day|week|month|year

• categories=general,it,news,science,images

• max_results=1..8

• mode=auto|quick|balanced|deep

Cuando no se proporciona ninguna categoría, la puerta de enlace infiere categorías útiles de SearXNG a partir de la solicitud. auto utiliza el modo rápido para búsquedas simples y el modo equilibrado para preguntas técnicas y recomendaciones.

Para integraciones directas, también está disponible un endpoint JSON más completo:

POST /v1/research
Content-Type: application/json

{
  "query": "What are the recommended settings for an AW3426DW?",
  "mode": "balanced",
  "max_results": 5,
  "language": "auto",
  "categories": []
}

Actualización

Desde el directorio del repositorio en el VPS:

git pull --ff-only
docker compose config --quiet
docker compose up -d --build --remove-orphans --wait
docker compose ps

No es necesario ejecutar docker compose down para una actualización normal. El caché de Redis existente y las descargas del reordenador permanecen en volúmenes con nombre.

Operaciones

Comandos útiles:

docker compose ps
docker compose logs --tail=200 search-gateway searxng reranker
docker compose logs --tail=200 crawl4ai web-runner safe-egress pdf-runner
docker compose restart search-gateway
docker compose down
docker compose up -d --wait

docker compose down conserva los volúmenes con nombre. docker compose down -v elimina el caché y el modelo de reordenación descargado y debe usarse solo para un reinicio completo deliberado.

Limitaciones

Esto puede acercarse a las herramientas de búsqueda alojadas para documentación, resolución de problemas, configuraciones de productos, juegos, información actual e investigación general, pero no puede garantizar la misma cobertura que los proveedores comerciales. Los motores sin clave pueden limitar la tasa de IPs de centros de datos, algunos sitios bloquean todos los navegadores automatizados y ningún VPS individual tiene los índices de búsqueda propietarios utilizados por Google, Brave o los motores de respuesta de pago. La puerta de enlace compensa con múltiples proveedores de descubrimiento, extracción concurrente, reordenación local, respaldos de navegador limitados, almacenamiento en caché y resultados parciales honestos en lugar de inventar una respuesta.