webroot-mcp

MCP-сервер для Webroot (OpenText endpoint security / SecureAnywhere, управление через консоль Global Site Manager "GSM"). Предоставляет сайты, конечные точки, группы, политики, историю угроз, статус агентов в реальном времени и методы DNS Protection (DNSP) консоли GSM из Webroot Unity API в виде MCP-инструментов.

Обзор

• Stateless HTTP-сервис. Учетные данные нигде не сохраняются — каждый запрос передает свои собственные учетные данные через заголовки, которые используются только в течение времени выполнения этого единственного запроса.

• Поддерживает конкурентные запросы; изоляция учетных данных на уровне запроса реализована через Python contextvars, а не через глобальный/общий экземпляр клиента.

• Точки входа: POST /mcp (протокол MCP) и GET /health (проверка работоспособности).

• Порт по умолчанию: 8080 (настраивается через MCP_HTTP_PORT).

Related MCP server: kaseya-vsa-mcp

Аутентификация

Webroot Unity API реализует стандартный OAuth2 с использованием предоставления пароля:

POST https://unityapi.webrootcloudav.com/auth/token
  grant_type=password&username=...&password=...&client_id=...&client_secret=...
  &scope=Console.GSM SkyStatus.GSM
-> {"access_token": "...", "expires_in": 299, "refresh_token": "...", ...}

Токен доступа действителен всего ~5 минут, поэтому этот сервер заново аутентифицируется при каждом вызове инструмента, а не кэширует его между MCP-запросами — ничего не кэшируется и не сохраняется. Каждый реальный вызов API затем отправляет Authorization: Bearer <access_token>.

Параметры заголовков

Отсутствие любого заголовка возвращает 401:

{
  "error": "Missing credentials",
  "message": "This server requires the X-Webroot-Username, X-Webroot-Password, X-Webroot-Client-Id, X-Webroot-Client-Secret, X-Webroot-Parent-Keycode headers",
  "required_headers": ["X-Webroot-Username", "X-Webroot-Password", "X-Webroot-Client-Id", "X-Webroot-Client-Secret", "X-Webroot-Parent-Keycode"],
  "optional_headers": []
}

Неверные учетные данные отображаются как структурированная ошибка уровня инструмента (см. «Обработка ошибок» ниже) на этапе внутреннего входа в систему, а не как ошибка HTTP-уровня этого сервера.

Переменные окружения

Конечная точка MCP

• POST /mcp — протокол MCP (потоковый HTTP-транспорт)

• GET /health — проверка работоспособности, возвращает {"status": "ok"} (чисто локальная проверка, не зависит от Webroot API)

Список инструментов

Все 10 инструментов доступны только для чтения (readOnlyHint=True); в этом сервисе нет инструментов записи/удаления.

Ограничения page_size/batch_size: в публичной справочной документации API поставщика не указан максимум для этих параметров ни для одной из вышеуказанных конечных точек, поэтому этот сервер применяет собственное значение по умолчанию (50) и жесткий максимум (200), а не передает неограниченное значение.

Ответы представляют собой JSON поставщика, сериализованный компактно (без форматирования, ensure_ascii=False) и ограниченный 20 000 символов — слишком большое поле списка обрезается с помощью маркеров truncated/original_count, а не возвращается неограниченный блок данных.

Обработка ошибок

Ошибки возвращаются в виде встроенного JSON-конверта (обычная строка результата инструмента, а не ошибка протокола MCP):

{"error": {"code": "not_found", "message": "...", "retryable": false}}

code — одно из фиксированного набора: not_configured, unauthorized, not_found, invalid_argument, rate_limited, upstream_error. retryable сообщает вызывающей стороне, может ли повторная попытка того же вызова увенчаться успехом (true для rate_limited/upstream_error, false в противном случае). Пустой набор результатов (например, сайт без конечных точек) — это обычный успешный результат, а не ошибка not_found.

Исходящие вызовы Webroot API используют таймаут подключения 5 с / таймаут чтения 30 с и повторяют ответы 429/5xx до 3 раз с экспоненциальной задержкой (с учетом Retry-After, максимум 20 с), используя единый пул HTTP-соединений на время жизни процесса.

Примеры тестирования

# Health check
curl -s http://localhost:8080/health

# Call a tool via the MCP protocol (streamable HTTP) — requires an
# initialize handshake first per the MCP spec; abbreviated example below
# shows the tool-call request body only:
curl -s -X POST http://localhost:8080/mcp \
  -H "X-Webroot-Username: admin@example.com" \
  -H "X-Webroot-Password: <your-password>" \
  -H "X-Webroot-Client-Id: <your-client-id>" \
  -H "X-Webroot-Client-Secret: <your-client-secret>" \
  -H "X-Webroot-Parent-Keycode: <your-parent-keycode>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "webroot_get_sites",
      "arguments": {}
    }
  }'

Проверено вживую (2026-07-30) на реальной консоли GSM: все 10 инструментов вызывались сквозным образом через этот запущенный сервер с реальными учетными данными: webroot_get_sites вернул 92 реальных сайта (например, "Pinnacle Technologies", "Hohimer Wealth Management"); webroot_get_policies вернул 11 реальных политик; webroot_get_agent_status вернул реальные данные о статусе каждого устройства; webroot_get_endpoints и webroot_get_groups (с использованием реального идентификатора сайта) оба вернули реальные данные (6 конечных точек, 1 группа с 46 устройствами); webroot_get_threat_history вернул допустимый (пустой) результат для реального диапазона в 2 месяца. Все 4 инструмента DNS Protection (webroot_get_dnsp_categories/_block_reasons/_traffic_summary/_blocked_traffic) корректно обращались к API и возвращали собственную ошибку поставщика dnsp_not_enabled — что доказывает корректность конвейера запросов/аутентификации; DNS Protection просто не включен для консоли GSM этой конкретной тестовой учетной записи (см. «Известные ограничения»).

Справочник по API

• Публичный, без входа в систему: https://unityapi.webrootcloudav.com/Docs/en/APIDoc (Руководство полностью описывает OAuth2-аутентификацию; Справочник по API охватывает параметры и структуру ответов каждого метода)

Известные ограничения

• Область действия ограничена 10 настроенными конечными точками MSPbots, а не полным API поставщика — Unity API также охватывает ECom (заказ/управление лицензиями), уведомления, отправку команд агенту, создание/редактирование сайтов и платформенный API OpenText Secure Cloud; все это выходит за рамки данного проекта.

• 4 инструмента DNS Protection (DNSP) не удалось проверить на реальных данных — DNS Protection является дополнительным продуктом, который не включен для консоли GSM тестовой учетной записи (ошибка dnsp_not_enabled, подтверждено вживую). Остальные 6 инструментов успешно работали с реальными данными, используя тот же самый токен доступа, что подтверждает, что это ограничение учетной записи, а не ошибка реализации.

• webroot_get_endpoints/webroot_get_groups/webroot_get_threat_history требуют site_id, к которому у аутентифицированного пользователя GSM действительно есть доступ — доступ Webroot GSM осуществляется по сайтам; попытка вызова этих методов для сайта, к которому у пользователя нет доступа, возвращает понятную ошибку "User does not have access to this console" (наблюдалось вживую для одного из 92 сайтов во время тестирования), а не ошибку этого сервера.

• webroot_get_threat_history отклоняет диапазоны дат более 3 месяцев (Invalid data entered - Date Range Over 3 Months, подтверждено вживую) — этот сервер не применяет и не разбивает диапазон автоматически; он передает start_date/end_date как есть.