covedataprotection-mcp

MCP-сервер для Cove Data Protection (платформа резервного копирования/BDR от N-able, ранее N-able Backup / Backup Manager). Предоставляет API JSON-RPC Management Service Backup Manager в виде MCP-инструментов.

Обзор

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

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

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

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

Related MCP server: spanning-mcp

Область применения

26 инструментов, урезанных из исходной сборки полной схемы на 247 инструментов (2026-08-04). Собственная интеграция Cove Data Protection от MSPbots (подтверждённая вживую через /web/int/sys/integration/api/list на производственной платформе) настроена ровно на 6 API, которые сопоставлены со следующими нижележащими методами JSON-RPC:

Остальные 5 методов, подтверждённых как реальные, были оставлены как есть, плюс базовые CRUD-операции той же категории (Add/Get/Modify/Remove) для каждого из трёх типов ресурсов, которых они касаются, — accounts (9 инструментов), partners (9 инструментов), users (7 инструментов) — а также GetServerInfo (1 инструмент, самопроверка связности, использовавшийся для исходной live-проверки ниже). Все остальные категории из исходной сборки на 247 инструментов (notifications, storage_nodes, contacts, storage, view_delivery, labels, jobs, custom_columns, branding, products, eula, locations, countries, audit, email, regions, features, permissions, templates — 19 категорий, ~221 инструмент) были удалены полностью как неиспользуемые MSPbots и выходящие за рамки назначения этого сервера.

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

В Cove нет статического долгоживущего API-ключа. Вместо этого каждая сессия начинается с вызова Login (partner + username + password), который возвращает недолговечный токен visa (действителен ~15 минут), и этот токен должен сопровождать каждый последующий вызов.

Этот сервер не кэширует visa между запросами — кэширование означало бы сохранение состояния сессии, что противоречит требованию «никакого хранения учётных данных». Вместо этого api_client.CoveClient.call() выполняет новый Login при каждом вызове инструмента и отбрасывает полученную visa после завершения, ценой одного дополнительного HTTP-запроса на каждый вызов ради полной независимости от состояния.

Описание параметров авторизации в заголовках

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

{
  "error": "Missing credentials",
  "message": "This server requires the X-CoveDataProtection-Partner, X-CoveDataProtection-Username, and X-CoveDataProtection-Password headers",
  "required_headers": ["X-CoveDataProtection-Partner", "X-CoveDataProtection-Username", "X-CoveDataProtection-Password"],
  "optional_headers": []
}

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

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

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

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

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

Имена инструментов следуют шаблону covedataprotection_<snake_case_method_name> — например, метод JSON-RPC EnumerateAccountStatistics становится covedataprotection_enumerate_account_statistics. Имена параметров повторяют имена параметров самого метода JSON-RPC (camelCase → snake_case); сложные параметры с типами struct/enum принимаются как dict/str и передаются в API вендора как есть — о том, что это означает на практике, см. Known Gaps.

Тестовый пример

# 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-CoveDataProtection-Partner: <your-partner-name>" \
  -H "X-CoveDataProtection-Username: <your-username>" \
  -H "X-CoveDataProtection-Password: <your-password>" \
  -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": "covedataprotection_get_server_info",
      "arguments": {}
    }
  }'

Ожидается: 200 с версией сервера при действительных учётных данных; при недействительных учётных данных сам вызов Login завершается ошибкой, и каждый инструмент возвращает структурированный JSON-конверт ошибки, например:

{"error":{"code":"unauthorized","message":"<vendor error message>","retryable":false}}

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

Проверено вживую (2026-07-29): covedataprotection_get_server_info (ноль параметров) был вызван end-to-end через этот запущенный сервер с реальными partner/username/password и вернул фактическую версию сервера Cove — подтверждая, что цепочка Login → visa → вызов метода работает с живым API, а не только структурно.

Справочник API

• Начало работы: https://developer.n-able.com/n-able-cove/docs/getting-started

• Авторизация: https://developer.n-able.com/n-able-cove/docs/authorization

• Построение вызова: https://developer.n-able.com/n-able-cove/docs/construct-a-json-rpc-api-call

• Полная схема методов/структур/перечислений (JSON): https://documentation.n-able.com/covedataprotection/Schema_23.3.json

Известные пробелы

• Сокращено с 247 до 26 инструментов 2026-08-04. Первоначальная сборка покрывала каждый метод в схеме Management Service. Согласно более позднему решению о границах охвата, набор был сокращён до того, что реально вызывает собственная производственная конфигурация интеграции MSPbots (проверено вживую через /web/int/sys/integration/api/list на app.mspbots.ai, id интеграции 2026570354981494786) плюс базовые CRUD той же категории — см. раздел Scope выше для точного соответствия API→метод и полного списка удалённых категорий. Удалено ~221 инструмент (notifications, storage_nodes, contacts, storage, view_delivery, labels, jobs, custom_columns, branding, products, eula, locations, countries, audit, email, regions, features, permissions, templates); в этой сборке их нет вообще; если в будущем понадобится один из них, исходная схема (Schema_23.3.json, ссылка ниже) по-прежнему документирует его точную сигнатуру метода, и его можно добавить тем же способом, которым были сгенерированы сохранённые инструменты.

• Это покрывает только Management Service. Руководство по началу работы с Cove описывает вторую, отдельную Reporting Service ({host}/repserv_json, работает на каждом узле хранения), которая предоставляет статистику сеансов резервного копирования/восстановления. Собственная конфигурация MSPbots вызывает отчёт «Query Sessions» в этой Reporting Service — она не является частью схемы Management Service, из которой генерируется этот MCP, и публичной схемы для Reporting Service найдено не было. Это единственный настроенный в MSPbots endpoint, который этот MCP не покрывает; его можно добавить, если станет доступен список методов/схема Reporting Service.

• Сложные параметры структур/перечислений нетипизированы (dict/str), а не полностью смоделированы. Схема определяет 106 структур и 78 перечислений; полностью воспроизвести каждую из них как типизированный параметр Python было вне рамок для механически сгенерированного сервера. Вызывающим нужно формировать эти dict-аргументы в соответствии со схемой вендора (см. раздел Structs в Schema_23.3.json для точных имён полей) — описание каждого такого параметра называет структуру, которой он соответствует, и указывает на этот файл схемы.

• Нет кэширования visa — см. раздел Authentication выше. Каждый вызов инструмента выполняет собственный Login, что просто и полностью без сохранения состояния, но означает 2 HTTP-запроса к вендору на каждый вызов инструмента вместо 1.

• Все 26 инструментов были сгенерированы кодом напрямую из собственного файла схемы вендора, а не написаны вручную — имена/типы параметров настолько точны, насколько точна эта схема. covedataprotection_get_server_info был единственным инструментом, проверенным вживую end-to-end; остальные структурно корректны (схема проверена, tools/list MCP-протокола подтверждён), но не проходили индивидуальное смоук-тестирование на реальных данных.

Примечания о соответствии вендорскому MCP SOP

• Количество инструментов (26) превышает рекомендацию SOP «должно быть ≤20». Уже сокращено с 247 до 26 (см. выше); оставшиеся 26 сопоставляются 1:1 с отдельными методами JSON-RPC в 3 доменах ресурсов (accounts/partners/users), которые нельзя объединить без потери различий в обязательных параметрах (например, get_*_info по name+password и get_*_info_by_id по числовому ID — это разные ключи поиска, а не один инструмент с необязательным параметром).

• Ни на одном инструменте нет скалярного параметра limit / page_size. Ни один из 26 методов не предоставляет полноценный числовой параметр размера страницы — единственное поле, похожее на пагинацию (range в EnumerateChildPartners), является непрозрачной структурой вендора и передаётся как есть, а children_limit в GetPartnerTree точно так же передаётся вендору без интерпретации. Этому серверу нечего ограничивать в соответствии с рекомендацией SOP «по умолчанию 50 / жёсткий предел 200»; если окажется, что структуры range/limit в схеме вендора имеют собственный документированный максимум на страницу, то здесь следует применять именно его, а не общий запасной потолок из SOP.

• Нет запасного варианта с переменными окружения для учётных данных. В config.Settings нет поля partner/username/password; get_client_from_context возвращает None (→ конверт not_configured) всякий раз, когда контекстная переменная запроса не установлена. Не существует пути кода, который откатывался бы к переменной окружения.

• Аннотации инструментов: каждый инструмент чтения (get_*, enumerate_*) помечен readOnlyHint=True, idempotentHint=True; инструменты add_* имеют readOnlyHint=False, idempotentHint=False (создание дважды — не no-op); инструменты modify_*/set_*/remove_* имеют readOnlyHint=False, destructiveHint=True, idempotentHint=True.