mcp-cloudnex 1.0.0__py3-none-any.whl

app/__init__.py

@@ -0,0 +1,3 @@
+"""CloudNex MCP Server package."""
+
+__version__ = "1.0.0"

app/client/__init__.py

@@ -0,0 +1,5 @@
+"""HTTP clients for CloudNex API and Hub."""
+
+from app.client.backend_client import BackendClient, HubClient
+
+__all__ = ["BackendClient", "HubClient"]

app/client/backend_client.py

@@ -0,0 +1,479 @@
+"""
+HTTP clients for CloudNex Backend API and CloudNex Hub.
+
+Authentication: Tenant API Key (Authorization: Api-Key {prefix.key})
+- Uses Authorization: Api-Key header per CloudNex JSON:API backend
+- API key is tenant-scoped; RBAC filters data by role and provider group assignments
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, Dict, Optional
+from urllib.parse import urljoin
+
+import httpx
+
+from app.client.jsonapi import build_query_params
+from app.core.config import settings
+from app.core.exceptions import (
+    AccessForbiddenError,
+    AuthenticationError,
+    BackendConnectionError,
+    MCPServerError,
+    ResourceNotFoundError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def mask_api_key(api_key: str) -> str:
+    """Mask API key for logging — show prefix only (before first dot)."""
+    if not api_key:
+        return "***"
+    if "." in api_key:
+        return f"{api_key.split('.', 1)[0]}.***"
+    if len(api_key) > 8:
+        return f"{api_key[:8]}***"
+    return "***"
+
+
+class BackendClient:
+    """HTTP client for CloudNex JSON:API backend."""
+
+    def __init__(self, api_key: Optional[str] = None):
+        self.base_url = (settings.cloudnex_api_url or "").strip().rstrip("/")
+        self.api_key = (api_key if api_key is not None else settings.cloudnex_api_key or "").strip()
+        self.timeout = settings.cloudnex_backend_timeout
+        self.retry_attempts = settings.cloudnex_backend_retry_attempts
+        self.retry_delay = settings.cloudnex_backend_retry_delay
+
+        if self.api_key:
+            logger.info("BackendClient initialized with API key: %s", mask_api_key(self.api_key))
+        else:
+            logger.warning("BackendClient: CLOUDNEX_API_KEY not set.")
+
+        if self.base_url:
+            logger.info("BackendClient base URL: %s", self.base_url[:80])
+        else:
+            logger.warning("BackendClient: CLOUDNEX_API_URL not set.")
+
+    def _require_backend_config(self) -> None:
+        if not self.base_url:
+            raise MCPServerError(
+                "CLOUDNEX_API_URL is not set. Set this environment variable to your "
+                "CloudNex API base URL (e.g. https://api.example.com/api/v1)."
+            )
+        if not self.api_key:
+            raise MCPServerError(
+                "CLOUDNEX_API_KEY is not set. Set this environment variable to a "
+                "tenant API key (format: prefix.key)."
+            )
+
+    def _build_headers(self, api_key_override: Optional[str] = None) -> Dict[str, str]:
+        key = (api_key_override or self.api_key).strip()
+        return {
+            "Authorization": f"Api-Key {key}",
+            "Accept": "application/vnd.api+json",
+            "Content-Type": "application/vnd.api+json",
+            "User-Agent": f"{settings.cloudnex_mcp_server_name}/{settings.cloudnex_mcp_server_version}",
+        }
+
+    async def _make_request(
+        self,
+        method: str,
+        endpoint: str,
+        *,
+        params: Optional[Dict[str, str]] = None,
+        api_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Make HTTP request with retry on timeout/connect errors only."""
+        self._require_backend_config()
+        url = urljoin(f"{self.base_url}/", endpoint.lstrip("/"))
+        headers = self._build_headers(api_key)
+
+        logger.debug("Request %s %s params=%s", method, url, params)
+
+        last_error: Optional[Exception] = None
+        for attempt in range(self.retry_attempts + 1):
+            try:
+                async with httpx.AsyncClient(timeout=self.timeout) as client:
+                    response = await client.request(method, url, headers=headers, params=params)
+
+                    if response.status_code == 401:
+                        raise AuthenticationError("Invalid API key")
+                    if response.status_code == 403:
+                        raise AccessForbiddenError(response.text or "Access denied (forbidden)")
+                    if response.status_code == 404:
+                        raise ResourceNotFoundError(response.text or "Resource not found")
+                    if response.status_code >= 400:
+                        raise BackendConnectionError(f"HTTP {response.status_code}: {response.text}")
+
+                    if response.status_code == 204 or not response.content:
+                        return {}
+                    return response.json()
+
+            except httpx.TimeoutException as exc:
+                last_error = exc
+                if attempt < self.retry_attempts:
+                    logger.warning("Request timeout, retrying in %ss", self.retry_delay)
+                    await asyncio.sleep(self.retry_delay)
+                    continue
+                raise BackendConnectionError("Request timeout after retries") from exc
+
+            except httpx.ConnectError as exc:
+                last_error = exc
+                if attempt < self.retry_attempts:
+                    logger.warning("Connection failed, retrying in %ss", self.retry_delay)
+                    await asyncio.sleep(self.retry_delay)
+                    continue
+                raise BackendConnectionError("Failed to connect to CloudNex API") from exc
+
+            except (AuthenticationError, AccessForbiddenError, ResourceNotFoundError):
+                raise
+
+            except MCPServerError:
+                raise
+
+            except Exception as exc:
+                last_error = exc
+                if attempt < self.retry_attempts:
+                    logger.warning("Request failed: %s, retrying", exc)
+                    await asyncio.sleep(self.retry_delay)
+                    continue
+                raise MCPServerError(f"Backend request failed: {exc}") from exc
+
+        raise MCPServerError(f"Backend request failed: {last_error}")
+
+    async def get_scans(
+        self,
+        *,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        sort: Optional[str] = None,
+        filters: Optional[Dict[str, Any]] = None,
+        include: Optional[str] = None,
+        api_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        params = build_query_params(
+            page=page,
+            page_size=page_size,
+            sort=sort,
+            filters=filters,
+            include=include,
+            allowed_filters={
+                "state", "provider_id", "search",
+                "filter[state]", "filter[provider_id]", "filter[search]",
+            },
+        )
+        return await self._make_request("GET", "/scans", params=params, api_key=api_key)
+
+    async def get_scan(self, scan_id: str, *, include: Optional[str] = None, api_key: Optional[str] = None) -> Dict[str, Any]:
+        params = build_query_params(include=include) if include else None
+        return await self._make_request("GET", f"/scans/{scan_id}", params=params, api_key=api_key)
+
+    async def get_latest_scan_id(self, *, api_key: Optional[str] = None) -> Optional[str]:
+        """Return the most recent scan ID for the tenant, if any."""
+        data = await self.get_scans(page_size=1, sort="-inserted_at", api_key=api_key)
+        resources = data.get("data")
+        if isinstance(resources, list) and resources:
+            return str(resources[0]["id"])
+        if isinstance(resources, dict):
+            return str(resources["id"])
+        return None
+
+    async def get_findings(
+        self,
+        *,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        sort: Optional[str] = None,
+        filters: Optional[Dict[str, Any]] = None,
+        include: Optional[str] = "resources,scan.provider",
+        api_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        params = build_query_params(
+            page=page,
+            page_size=page_size,
+            sort=sort,
+            filters=filters,
+            include=include,
+            allowed_filters={
+                "status", "severity", "provider_type", "service", "region", "search",
+                "scan", "scan_id",
+                "inserted_at", "inserted_at__gte", "inserted_at__lte",
+                "status__in", "severity__in", "provider_type__in", "service__in",
+                "filter[status]", "filter[severity]", "filter[provider_type]",
+                "filter[service]", "filter[region]", "filter[search]",
+                "filter[scan]", "filter[scan_id]",
+                "filter[inserted_at]", "filter[inserted_at__gte]", "filter[inserted_at__lte]",
+                "filter[status__in]", "filter[severity__in]", "filter[provider_type__in]",
+            },
+        )
+        return await self._make_request("GET", "/findings", params=params, api_key=api_key)
+
+    async def get_findings_metadata(
+        self,
+        *,
+        filters: Optional[Dict[str, Any]] = None,
+        api_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        params = build_query_params(
+            filters=filters,
+            allowed_filters={
+                "scan", "scan_id",
+                "inserted_at", "inserted_at__gte", "inserted_at__lte",
+                "filter[scan]", "filter[scan_id]",
+                "filter[inserted_at]", "filter[inserted_at__gte]", "filter[inserted_at__lte]",
+            },
+        )
+        return await self._make_request("GET", "/findings/metadata", params=params or None, api_key=api_key)
+
+    async def get_latest_findings(
+        self,
+        *,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        sort: Optional[str] = None,
+        filters: Optional[Dict[str, Any]] = None,
+        include: Optional[str] = "resources,scan.provider",
+        api_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        params = build_query_params(
+            page=page,
+            page_size=page_size,
+            sort=sort,
+            filters=filters,
+            include=include,
+            allowed_filters={
+                "status", "severity", "provider_type", "service", "region", "search",
+                "filter[status]", "filter[severity]", "filter[provider_type]",
+                "filter[service]", "filter[region]", "filter[search]",
+            },
+        )
+        return await self._make_request("GET", "/findings/latest", params=params, api_key=api_key)
+
+    async def get_providers(
+        self,
+        *,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        sort: Optional[str] = None,
+        filters: Optional[Dict[str, Any]] = None,
+        include: Optional[str] = None,
+        api_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        params = build_query_params(
+            page=page,
+            page_size=page_size,
+            sort=sort,
+            filters=filters,
+            include=include or "provider_groups",
+            allowed_filters={"provider", "alias", "search", "filter[provider]", "filter[alias]", "filter[search]"},
+        )
+        return await self._make_request("GET", "/providers", params=params, api_key=api_key)
+
+    async def get_provider(
+        self,
+        provider_id: str,
+        *,
+        include: Optional[str] = None,
+        api_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        params = build_query_params(include=include or "provider_groups")
+        return await self._make_request("GET", f"/providers/{provider_id}", params=params, api_key=api_key)
+
+    async def get_compliance_overviews(
+        self,
+        *,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        sort: Optional[str] = None,
+        filters: Optional[Dict[str, Any]] = None,
+        api_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        params = build_query_params(
+            page=page,
+            page_size=page_size,
+            sort=sort,
+            filters=filters,
+            allowed_filters={"scan_id", "filter[scan_id]"},
+        )
+        return await self._make_request("GET", "/compliance-overviews", params=params, api_key=api_key)
+
+    async def get_compliance_requirements(
+        self,
+        *,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        sort: Optional[str] = None,
+        filters: Optional[Dict[str, Any]] = None,
+        api_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        params = build_query_params(
+            page=page,
+            page_size=page_size,
+            sort=sort,
+            filters=filters,
+            allowed_filters={
+                "scan_id", "compliance_id", "filter[scan_id]", "filter[compliance_id]",
+            },
+        )
+        return await self._make_request("GET", "/compliance-overviews/requirements", params=params, api_key=api_key)
+
+    async def get_providers_overview(self, *, api_key: Optional[str] = None) -> Dict[str, Any]:
+        return await self._make_request("GET", "/overviews/providers", api_key=api_key)
+
+    async def get_findings_by_status(
+        self,
+        *,
+        filters: Optional[Dict[str, Any]] = None,
+        api_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        params = build_query_params(
+            filters=filters,
+            allowed_filters={"provider_id", "filter[provider_id]"},
+        )
+        return await self._make_request("GET", "/overviews/findings", params=params or None, api_key=api_key)
+
+    async def get_findings_by_severity(
+        self,
+        *,
+        filters: Optional[Dict[str, Any]] = None,
+        api_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        params = build_query_params(
+            filters=filters,
+            allowed_filters={"status", "provider_id", "filter[status]", "filter[provider_id]"},
+        )
+        return await self._make_request("GET", "/overviews/findings_severity", params=params or None, api_key=api_key)
+
+    async def get_users(
+        self,
+        *,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        sort: Optional[str] = None,
+        filters: Optional[Dict[str, Any]] = None,
+        include: Optional[str] = None,
+        api_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        params = build_query_params(
+            page=page,
+            page_size=page_size,
+            sort=sort,
+            filters=filters,
+            include=include,
+            allowed_filters={"search", "filter[search]"},
+        )
+        return await self._make_request("GET", "/users", params=params, api_key=api_key)
+
+    async def get_my_profile(self, *, include: Optional[str] = "roles", api_key: Optional[str] = None) -> Dict[str, Any]:
+        params = build_query_params(include=include) if include else None
+        return await self._make_request("GET", "/users/me", params=params, api_key=api_key)
+
+    async def get_roles(
+        self,
+        *,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        sort: Optional[str] = None,
+        filters: Optional[Dict[str, Any]] = None,
+        api_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        params = build_query_params(
+            page=page,
+            page_size=page_size,
+            sort=sort,
+            filters=filters,
+            allowed_filters={"name", "filter[name]"},
+        )
+        return await self._make_request("GET", "/roles", params=params, api_key=api_key)
+
+    async def get_role(self, role_id: str, *, api_key: Optional[str] = None) -> Dict[str, Any]:
+        return await self._make_request("GET", f"/roles/{role_id}", api_key=api_key)
+
+    async def get_resources(
+        self,
+        *,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        sort: Optional[str] = None,
+        filters: Optional[Dict[str, Any]] = None,
+        include: Optional[str] = None,
+        api_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        params = build_query_params(
+            page=page,
+            page_size=page_size,
+            sort=sort,
+            filters=filters,
+            include=include,
+            allowed_filters={
+                "provider_id", "service", "region", "search",
+                "scan", "scan_id",
+                "updated_at", "updated_at__gte", "updated_at__lte",
+                "filter[provider_id]", "filter[service]", "filter[region]", "filter[search]",
+                "filter[scan]", "filter[scan_id]",
+                "filter[updated_at]", "filter[updated_at__gte]", "filter[updated_at__lte]",
+            },
+        )
+        return await self._make_request("GET", "/resources", params=params, api_key=api_key)
+
+    async def get_resource(self, resource_id: str, *, include: Optional[str] = None, api_key: Optional[str] = None) -> Dict[str, Any]:
+        params = build_query_params(include=include) if include else None
+        return await self._make_request("GET", f"/resources/{resource_id}", params=params, api_key=api_key)
+
+    async def health_check(self, *, api_key: Optional[str] = None) -> bool:
+        """Lightweight health check via GET /users/me."""
+        try:
+            await self.get_my_profile(api_key=api_key)
+            return True
+        except Exception:
+            return False
+
+
+class HubClient:
+    """Public CloudNex Hub client (no authentication required)."""
+
+    def __init__(self):
+        self.base_url = (settings.cloudnex_hub_url or "https://hub.cloudnex.com").strip().rstrip("/")
+        self.timeout = settings.cloudnex_backend_timeout
+
+    async def _make_request(
+        self,
+        method: str,
+        endpoint: str,
+        *,
+        params: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        url = urljoin(f"{self.base_url}/", endpoint.lstrip("/"))
+        headers = {
+            "Accept": "application/json",
+            "User-Agent": f"{settings.cloudnex_mcp_server_name}/{settings.cloudnex_mcp_server_version}",
+        }
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            try:
+                response = await client.request(method, url, headers=headers, params=params)
+            except httpx.RequestError as exc:
+                raise BackendConnectionError(
+                    f"CloudNex Hub unreachable at {self.base_url}: {exc}. "
+                    "Check network connectivity or set CLOUDNEX_HUB_URL."
+                ) from exc
+            if response.status_code >= 400:
+                raise BackendConnectionError(f"Hub HTTP {response.status_code}: {response.text}")
+            if not response.content:
+                return {}
+            return response.json()
+
+    async def get_compliance_frameworks(self, *, provider: Optional[str] = None) -> Dict[str, Any]:
+        params = {"provider": provider} if provider else None
+        return await self._make_request("GET", "/api/compliance-frameworks", params=params)
+
+    async def get_provider_checks(self, provider: str) -> Dict[str, Any]:
+        return await self._make_request("GET", f"/api/providers/{provider}/checks")
+
+    async def get_check_details(self, provider: str, check_id: str) -> Dict[str, Any]:
+        return await self._make_request("GET", f"/api/checks/{provider}/{check_id}")

app/client/jsonapi.py

@@ -0,0 +1,174 @@
+"""JSON:API query building and response formatting utilities."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Iterable, Optional
+
+MAX_PAGE_SIZE = 100
+
+SENSITIVE_FIELD_NAMES = frozenset(
+    {
+        "api_key",
+        "secret",
+        "password",
+        "token",
+        "credentials",
+        "private_key",
+        "access_key",
+        "secret_key",
+        "client_secret",
+    }
+)
+
+
+def clamp_page_size(page_size: Optional[int], default: int = 25) -> int:
+    """Clamp page size to JSON:API maximum."""
+    if page_size is None:
+        return min(default, MAX_PAGE_SIZE)
+    return max(1, min(int(page_size), MAX_PAGE_SIZE))
+
+
+def build_query_params(
+    *,
+    page: Optional[int] = None,
+    page_size: Optional[int] = None,
+    sort: Optional[str] = None,
+    filters: Optional[Dict[str, Any]] = None,
+    include: Optional[str] = None,
+    allowed_filters: Optional[Iterable[str]] = None,
+) -> Dict[str, str]:
+    """Build JSON:API query parameters with whitelisted filters."""
+    params: Dict[str, str] = {}
+
+    if page is not None:
+        params["page[number]"] = str(max(1, int(page)))
+    if page_size is not None:
+        params["page[size]"] = str(clamp_page_size(page_size))
+    if sort:
+        params["sort"] = sort
+    if include:
+        params["include"] = include
+
+    allowed = set(allowed_filters or [])
+    for key, value in (filters or {}).items():
+        if value is None or value == "":
+            continue
+        filter_key = key if key.startswith("filter[") else f"filter[{key}]"
+        if allowed_filters is not None and filter_key not in allowed and key not in allowed:
+            continue
+        params[filter_key] = str(value)
+
+    return params
+
+
+def _is_jsonapi_resource(data: Dict[str, Any]) -> bool:
+    return "type" in data and ("attributes" in data or "relationships" in data)
+
+
+def redact_sensitive_fields(data: Any, *, _redact_keys: bool = False) -> Any:
+    """Recursively redact sensitive attribute keys from dict/list structures."""
+    if isinstance(data, dict):
+        if _is_jsonapi_resource(data):
+            redacted = dict(data)
+            if isinstance(data.get("attributes"), dict):
+                redacted["attributes"] = redact_sensitive_fields(
+                    data["attributes"], _redact_keys=True
+                )
+            return redacted
+
+        redacted: Dict[str, Any] = {}
+        for key, value in data.items():
+            key_lower = key.lower()
+            if _redact_keys and any(sensitive in key_lower for sensitive in SENSITIVE_FIELD_NAMES):
+                redacted[key] = "***REDACTED***"
+            else:
+                redacted[key] = redact_sensitive_fields(value, _redact_keys=_redact_keys)
+        return redacted
+    if isinstance(data, list):
+        return [redact_sensitive_fields(item, _redact_keys=_redact_keys) for item in data]
+    return data
+
+
+def _format_resource(resource: Dict[str, Any]) -> str:
+    """Format a single JSON:API resource for LLM consumption."""
+    lines = []
+    resource_type = resource.get("type", "unknown")
+    resource_id = resource.get("id", "")
+    lines.append(f"## {resource_type} ({resource_id})")
+
+    attributes = resource.get("attributes") or {}
+    for key, value in attributes.items():
+        if value is None:
+            continue
+        if isinstance(value, (dict, list)):
+            lines.append(f"- {key}: {value}")
+        else:
+            lines.append(f"- {key}: {value}")
+
+    relationships = resource.get("relationships") or {}
+    for rel_name, rel_data in relationships.items():
+        if not isinstance(rel_data, dict):
+            continue
+        rel_payload = rel_data.get("data")
+        if isinstance(rel_payload, list):
+            ids = [f"{item.get('type')}:{item.get('id')}" for item in rel_payload if item]
+            if ids:
+                lines.append(f"- related {rel_name}: {', '.join(ids)}")
+        elif isinstance(rel_payload, dict) and rel_payload:
+            lines.append(
+                f"- related {rel_name}: {rel_payload.get('type')}:{rel_payload.get('id')}"
+            )
+
+    return "\n".join(lines)
+
+
+def format_jsonapi_for_ai(data: Any) -> str:
+    """Convert JSON:API response to readable text for LLM consumption."""
+    if not isinstance(data, dict):
+        return str(data)
+
+    data = redact_sensitive_fields(data)
+    lines: list[str] = []
+
+    if "meta" in data:
+        meta = data["meta"]
+        if isinstance(meta, dict):
+            pagination = meta.get("pagination") or meta
+            if isinstance(pagination, dict):
+                page = pagination.get("page") or pagination
+                if isinstance(page, dict):
+                    lines.append(
+                        "Pagination: "
+                        f"page {page.get('number', '?')} of {page.get('pages', '?')} "
+                        f"({page.get('count', '?')} total records)"
+                    )
+
+    included_index: Dict[str, Dict[str, Any]] = {}
+    for item in data.get("included") or []:
+        if isinstance(item, dict) and "type" in item and "id" in item:
+            included_index[f"{item['type']}:{item['id']}"] = item
+
+    resources = data.get("data")
+    if isinstance(resources, dict):
+        lines.append(_format_resource(resources))
+    elif isinstance(resources, list):
+        if not resources:
+            lines.append("No records found.")
+        else:
+            lines.append(f"Found {len(resources)} record(s):\n")
+            for resource in resources:
+                if isinstance(resource, dict):
+                    lines.append(_format_resource(resource))
+                    lines.append("")
+    elif resources is None and not lines:
+        for key, value in data.items():
+            if key in ("meta", "links", "jsonapi"):
+                continue
+            lines.append(f"{key}: {value}")
+
+    if included_index:
+        lines.append("\nIncluded related resources:")
+        for key, resource in list(included_index.items())[:20]:
+            lines.append(_format_resource(resource))
+
+    return "\n".join(lines).strip() or "Empty response."