covedataprotection-mcp

Cove Data Protection(N-able의 백업/BDR 플랫폼, 이전 명칭 N-able Backup / Backup Manager)용 MCP 서버입니다. Backup Manager JSON-RPC Management Service API를 MCP 도구로 노출합니다.

개요

• 무상태(Stateless) HTTP 서비스입니다. 자격 증명이 영구 저장되지 않으며, 각 요청은 헤더를 통해 자체 자격 증명을 제공하고 해당 단일 요청의 수명 동안에만 사용됩니다.

• 동시 요청을 지원합니다. 요청별 자격 증명 격리는 전역/공유 클라이언트 인스턴스가 아닌 Python contextvars를 통해 수행됩니다.

• 진입점: POST /mcp(MCP 프로토콜) 및 GET /health(헬스 체크)입니다.

• 기본 포트: 8080(MCP_HTTP_PORT로 구성 가능).

Related MCP server: spanning-mcp

범위

원래 247개 도구 전체 스키마 빌드(2026-08-04)에서 축소된 26개 도구입니다. MSPbots 자체 Cove Data Protection 통합(프로덕션 플랫폼에 대한 /web/int/sys/integration/api/list를 통해 라이브 확인됨)은 정확히 6개의 API로 구성되며, 다음과 같은 기본 JSON-RPC 메서드에 매핑됩니다:

위의 실존이 확인된 다른 5개 메서드는 그대로 유지했으며, 이들이 다루는 세 가지 리소스 유형 각각에 대한 동일 카테고리 핵심 CRUD(Add/Get/Modify/Remove) — accounts(9개 도구), partners(9개 도구), users(7개 도구) — 와 GetServerInfo(1개 도구, 연결 자체 테스트, 아래 원래 라이브 검증에 사용됨)를 추가했습니다. 원래 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 왕복 1회를 추가로 소비하는 대신 완전한 무상태성을 얻습니다.

HEADER 인증 파라미터 설명

세 헤더 중 하나라도 누락되면 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 오류 봉투(envelope)를 반환합니다. 예:

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

code는 고정 값 not_configured / unauthorized / not_found / invalid_argument / rate_limited / upstream_error 중 하나입니다. retryable은 동일한 호출을 재시도했을 때 성공할 수 있는지 여부를 호출자에게 알려줍니다(rate_limited와 upstream_error에서만 true). 도구는 비즈니스/벤더 오류에 대해 예외를 발생시키지 않으며, 이 봉투가 일반 도구 결과 문자열로 반환됩니다.

라이브 검증됨 (2026-07-29): covedataprotection_get_server_info (매개변수 0개)가 이 실행 중인 서버를 통해 실제 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

알려진 한계

• 2026-08-04에 247개에서 26개 도구로 축소됨. 원래 빌드는 Management Service 스키마의 모든 메서드를 포함했습니다. 이후 범위 결정에 따라 MSPbots 자체 프로덕션 통합 구성이 실제로 호출하는 항목(app.mspbots.ai에 대한 /web/int/sys/integration/api/list로 라이브 검증됨, 통합 ID 2026570354981494786)과 동일 카테고리의 핵심 CRUD로 축소되었습니다. 정확한 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 자체 구성은 이 Reporting Service에 대해 "Query Sessions" 보고서를 호출합니다. 이는 이 MCP가 생성되는 Management Service 스키마의 일부가 아니며, Reporting Service에 대한 공개 스키마도 발견되지 않았습니다. 이것이 이 MCP가 다루지 않는 유일한 MSPbots 구성 엔드포인트입니다. Reporting Service의 메서드 목록/스키마가 제공되면 추가할 수 있습니다.

• 복잡한 구조체/열거형 매개변수는 완전히 모델링되지 않고 타입이 지정되지 않은(dict/str) 상태입니다. 스키마는 106개의 구조체와 78개의 열거형을 정의합니다. 각각을 타입이 지정된 Python 매개변수로 완전히 재현하는 것은 기계적으로 생성된 서버의 범위를 벗어났습니다. 호출자는 이러한 dict 인수를 공급업체 스키마에 맞게 구성해야 합니다(정확한 필드 이름은 Schema_23.3.json의 Structs 섹션 참조). 각 매개변수의 설명은 매핑되는 구조체의 이름을 명시하고 해당 스키마 파일을 가리킵니다.

• visa 캐싱 없음 — 위의 인증 섹션을 참조하세요. 모든 도구 호출은 자체적으로 Login을 수행합니다. 이는 단순하고 완전히 무상태(stateless)이지만 도구 호출당 공급업체에 대한 HTTP 요청이 1회가 아닌 2회 발생함을 의미합니다.

• 26개 도구 모두 공급업체 자체 스키마 파일에서 직접 코드 생성되었으며 수작업으로 작성되지 않았습니다. 매개변수 이름/타입은 해당 스키마만큼만 정확합니다. covedataprotection_get_server_info는 종단 간 라이브 검증이 이루어진 유일한 도구입니다. 나머지는 구조적으로 올바르지만(스키마 검증됨, MCP 프로토콜 tools/list 확인됨) 실제 데이터에 대해 개별적으로 스모크 테스트되지는 않았습니다.

공급업체 MCP SOP 준수 참고 사항

• 도구 수(26)는 SOP의 "≤20이어야 한다"는 지침을 초과합니다. 이미 247 → 26으로 축소했습니다(위 참조). 나머지 26개는 3개 리소스 도메인(accounts/partners/users)에 걸쳐 서로 다른 JSON-RPC 메서드와 1:1로 매핑되며, 필수 매개변수 구분을 잃지 않고는 병합할 수 없습니다(예: 이름+비밀번호로 조회하는 get_*_info와 숫자 ID로 조회하는 get_*_info_by_id는 동일한 도구에 선택적 매개변수를 추가한 것이 아니라 서로 다른 조회 키입니다).

• 어떤 도구에도 limit / page_size 스칼라 매개변수가 없습니다. 26개 메서드 중 어느 것도 일급(first-class) 숫자 페이지 크기 매개변수를 노출하지 않습니다. 페이지네이션 형태의 유일한 필드(EnumerateChildPartners의 range)는 불투명한 공급업체 구조체로 그대로 전달되며, GetPartnerTree의 children_limit도 마찬가지로 해석 없이 공급업체에 직접 전달됩니다. 이 서버가 SOP의 기본 50 / 상한 200 지침에 맞춰 제한할 수 있는 것이 없습니다. 공급업체 스키마의 range/limit 구조체에 자체 문서화된 페이지당 최대값이 있다면, SOP의 일반적인 대체 상한 대신 여기서 적용해야 합니다.

• 자격 증명 환경 변수 폴백 없음. config.Settings에는 partner/username/password 필드가 없습니다. get_client_from_context는 요청별 contextvar가 설정되지 않을 때마다 None을 반환합니다(→ not_configured 엔벨로프). 환경 변수로 폴백하는 코드 경로는 없습니다.

• 도구 주석(annotation): 모든 읽기 도구(get_*, enumerate_*)는 readOnlyHint=True, idempotentHint=True로 표시됩니다. add_* 도구는 readOnlyHint=False, idempotentHint=False입니다(두 번 생성하는 것은 no-op이 아닙니다). modify_*/set_*/remove_* 도구는 readOnlyHint=False, destructiveHint=True, idempotentHint=True입니다.