serpent

Un backend de metabúsqueda de código abierto creado para flujos de trabajo de agentes de IA / MCP.

Agrega resultados de múltiples motores de búsqueda, devuelve un esquema unificado y expone tanto una API HTTP estándar como un servidor MCP que los agentes LLM pueden llamar directamente.

Por qué existe esto

La mayoría de los agregadores de búsqueda están diseñados para una salida legible por humanos: páginas HTML, tarjetas de resultados, interfaces de paginación. Cuando un agente LLM necesita buscar en la web, necesita algo diferente: JSON estructurado, nombres de campo estables, resultados concurrentes de múltiples fuentes y un manejo de errores predecible.

serpent está diseñado para ese caso de uso. No es un clon de SearXNG.

Posicionamiento

• Backend de metabúsqueda amigable para agentes

• Pasarela de búsqueda centrada en MCP para flujos de trabajo de LLM

• API de búsqueda estructurada diseñada para pipelines de IA

Proveedores compatibles

Google

Google no se rastrea directamente. La razón es práctica: las medidas anti-bot de Google hacen que el rastreo autohospedado sea frágil. Mantener un rastreador confiable frente a la detección en constante evolución de Google significa roturas constantes y un alto costo de mantenimiento. Para casos de uso en producción, los proveedores externos son más confiables y rentables.

Proveedores de Google compatibles actualmente:

Ambas son opciones de bajo costo. Para uso casual o de bajo volumen, serpbase.dev tiende a ser más barato por consulta. Cualquiera funciona; configure la que prefiera, o ambas como respaldo.

Búsqueda web

Los proveedores marcados como mejor esfuerzo utilizan endpoints no documentados o objetivos de rastreo con fuertes medidas anti-bot. Pueden dejar de funcionar sin previo aviso.

Conocimiento / referencia

Desarrollador

Académico

Instalación

# Clone the repository
git clone https://github.com/your-org/serpent
cd serpent

# Install with pip (editable)
pip install -e ".[dev]"

# Or with uv
uv pip install -e ".[dev]"

Configuración

Copie .env.example a .env y rellene sus claves:

cp .env.example .env

# Required for Google search (at least one)
SERPBASE_API_KEY=your_key_here
SERPER_API_KEY=your_key_here

# Optional — omit to use unauthenticated/public access
BRAVE_API_KEY=            # free tier: 2000 req/month
GITHUB_TOKEN=             # raises rate limit from 60 to 5000 req/hour
STACKEXCHANGE_API_KEY=    # raises limit from 300 to 10,000 req/day
NCBI_API_KEY=             # PubMed; raises from 3 to 10 req/sec
SEMANTIC_SCHOLAR_API_KEY= # raises from 1 to 10 req/sec

# Server
HOST=0.0.0.0
PORT=8000

# Restrict which providers are active (comma-separated, empty = all available)
ENABLED_PROVIDERS=
ALLOW_UNSTABLE_PROVIDERS=false

# Timeouts in seconds
DEFAULT_TIMEOUT=10
AGGREGATOR_TIMEOUT=15
MAX_RESULTS_PER_PROVIDER=10

Ejecución

Servidor de API HTTP

python -m serpent.main
# or
serpent

El servidor se inicia en http://localhost:8000. Documentación interactiva en /docs.

Servidor MCP

python -m serpent.mcp_server
# or
serpent-mcp

El servidor MCP se comunica a través de stdio. Úselo con cualquier cliente compatible con MCP (Claude Desktop, cline, continue.dev, etc.).

Docker

Construya la imagen:

docker build -t serpent .

Ejecute la API HTTP:

docker run --rm -p 8000:8000 --env-file .env serpent

O con Docker Compose:

docker compose up --build

El contenedor inicia la API HTTP en http://localhost:8000.

API HTTP

POST /search

Agrega la búsqueda en todos los proveedores habilitados.

curl -X POST http://localhost:8000/search \
  -H "Content-Type: application/json" \
  -d '{"query": "rust async runtime"}'

Con proveedores y parámetros explícitos:

curl -X POST http://localhost:8000/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "rust async runtime",
    "providers": ["duckduckgo", "wikipedia"],
    "params": {"num_results": 5, "language": "en"}
  }'

Respuesta:

{
  "engine": "serpent",
  "query": "rust async runtime",
  "results": [
    {
      "title": "Tokio - An asynchronous Rust runtime",
      "url": "https://tokio.rs",
      "snippet": "Tokio is an event-driven, non-blocking I/O platform...",
      "source": "tokio.rs",
      "rank": 1,
      "provider": "duckduckgo",
      "published_date": null,
      "extra": {}
    }
  ],
  "related_searches": ["tokio vs async-std", "rust futures"],
  "suggestions": [],
  "answer_box": null,
  "timing_ms": 843.2,
  "providers": [
    {"name": "duckduckgo", "success": true, "result_count": 10, "latency_ms": 840.1, "error": null},
    {"name": "wikipedia", "success": true, "result_count": 3, "latency_ms": 320.5, "error": null}
  ],
  "errors": []
}

POST /search/google

curl -X POST http://localhost:8000/search/google \
  -H "Content-Type: application/json" \
  -d '{"query": "site:github.com rust tokio"}'

GET /health

curl http://localhost:8000/health
# {"status": "ok"}

GET /providers

curl http://localhost:8000/providers

{
  "available": [
    {"name": "google_serpbase", "tags": ["google", "web"]},
    {"name": "duckduckgo", "tags": ["web", "privacy"]},
    {"name": "wikipedia", "tags": ["web", "academic", "knowledge"]},
    {"name": "github", "tags": ["code", "web"]},
    {"name": "arxiv", "tags": ["academic", "web"]}
  ],
  "count": 5
}

Uso de MCP

Configure su cliente MCP para ejecutar serpent-mcp (o python -m serpent.mcp_server).

Ejemplo de configuración de Claude Desktop (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "serpent": {
      "command": "serpent-mcp",
      "env": {
        "SERPBASE_API_KEY": "your_key",
        "SERPER_API_KEY": "your_key"
      }
    }
  }
}

Herramientas MCP disponibles

search_web

Búsqueda web general en todos los proveedores habilitados.

{
  "query": "fastapi vs flask performance 2024",
  "num_results": 10
}

search_google

Búsqueda en Google a través de un proveedor externo configurado.

{
  "query": "site:docs.python.org asyncio",
  "provider": "google_serpbase"
}

search_academic

Búsqueda en arXiv y Wikipedia.

{
  "query": "transformer architecture attention mechanism",
  "num_results": 8
}

search_github

Búsqueda en repositorios de GitHub.

{
  "query": "python mcp server implementation",
  "num_results": 5
}

compare_engines

Ejecute la misma consulta en múltiples proveedores y devuelva los resultados agrupados por motor.

{
  "query": "vector database comparison",
  "providers": ["duckduckgo", "brave"],
  "num_results": 5
}

Referencia del esquema de resultados

Cada objeto de resultado tiene estos campos:

Desarrollo

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with auto-reload
uvicorn serpent.main:app --reload

Hoja de ruta

• [ ] Capa de caché (en memoria / Redis) para consultas repetidas

• [ ] Re-clasificación de relevancia entre proveedores

• [ ] Más proveedores: Bing (API oficial), Kagi, Tavily

• [ ] Limitación de tasa por proveedor con retroceso

• [ ] Respuestas en streaming (SSE) para agregaciones largas

• [ ] Imagen de Docker y configuración de Compose

• [ ] Endpoint de monitoreo de salud del proveedor

• [ ] Puntuación de resultados y señales de confianza

Licencia

MIT