serpent

Метапоисковый бэкенд с открытым исходным кодом, созданный для рабочих процессов MCP / ИИ-агентов.

Он агрегирует результаты из нескольких поисковых систем, возвращает унифицированную схему и предоставляет как стандартный HTTP API, так и MCP-сервер, к которому могут напрямую обращаться LLM-агенты.

Зачем это нужно

Большинство поисковых агрегаторов разработаны для чтения людьми: HTML-страницы, карточки результатов, интерфейсы пагинации. Когда LLM-агенту нужно выполнить поиск в сети, ему требуется нечто иное: структурированный JSON, стабильные имена полей, параллельное получение результатов из нескольких источников и предсказуемая обработка ошибок.

serpent разработан именно для таких сценариев. Это не клон SearXNG.

Позиционирование

• Дружественный к агентам бэкенд метапоиска

• MCP-ориентированный поисковый шлюз для рабочих процессов LLM

• Структурированный поисковый API, разработанный для ИИ-конвейеров

Поддерживаемые провайдеры

Google

Google не парсится напрямую. Причина практическая: меры Google против ботов делают самохостинг парсинга ненадежным. Поддержание надежного парсера для постоянно меняющихся систем обнаружения Google означает постоянные поломки и высокие затраты на обслуживание. Для промышленного использования сторонние провайдеры более надежны и экономически эффективны.

Текущие поддерживаемые провайдеры Google:

Оба варианта недорогие. Для эпизодического или низкообъемного использования serpbase.dev обычно дешевле за запрос. Работает любой из них; настройте тот, который предпочитаете, или оба для резервирования.

Веб-поиск

Провайдеры, помеченные как best-effort, используют недокументированные эндпоинты или цели для парсинга с сильными мерами защиты от ботов. Они могут перестать работать без предупреждения.

Знания / справочники

Разработка

Академические ресурсы

Установка

# 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]"

Конфигурация

Скопируйте .env.example в .env и заполните свои ключи:

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

Запуск

HTTP API сервер

python -m serpent.main
# or
serpent

Сервер запускается на http://localhost:8000. Интерактивная документация по адресу /docs.

MCP сервер

python -m serpent.mcp_server
# or
serpent-mcp

MCP-сервер обменивается данными через stdio. Используйте его с любым MCP-совместимым клиентом (Claude Desktop, cline, continue.dev и т.д.).

Docker

Соберите образ:

docker build -t serpent .

Запустите HTTP API:

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

Или с помощью Docker Compose:

docker compose up --build

Контейнер запускает HTTP API на http://localhost:8000.

HTTP API

POST /search

Агрегированный поиск по всем включенным провайдерам.

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

С явным указанием провайдеров и параметров:

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"}
  }'

Ответ:

{
  "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
}

Использование MCP

Настройте свой MCP-клиент на запуск serpent-mcp (или python -m serpent.mcp_server).

Пример конфигурации Claude Desktop (~/.claude/claude_desktop_config.json):

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

Доступные инструменты MCP

search_web

Общий веб-поиск по всем включенным провайдерам.

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

search_google

Поиск в Google через настроенного стороннего провайдера.

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

search_academic

Поиск в arXiv и Wikipedia.

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

search_github

Поиск репозиториев GitHub.

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

compare_engines

Выполнение одного и того же запроса через несколько провайдеров и возврат результатов, сгруппированных по движкам.

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

Справочник схемы результатов

Каждый объект результата имеет следующие поля:

Разработка

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

# Run tests
pytest

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

Дорожная карта

• [ ] Уровень кэширования (in-memory / Redis) для повторяющихся запросов

• [ ] Переранжирование релевантности между провайдерами

• [ ] Больше провайдеров: Bing (официальный API), Kagi, Tavily

• [ ] Ограничение частоты запросов (rate limiting) для каждого провайдера с экспоненциальной задержкой

• [ ] Потоковые ответы (SSE) для длительных агрегаций

• [ ] Docker-образ и настройка Compose

• [ ] Эндпоинт мониторинга состояния провайдеров

• [ ] Оценка результатов и сигналы достоверности

Лицензия

MIT