iflow-mcp_enuno-unifi-mcp-server 0.2.1__py3-none-any.whl

src/utils/exceptions.py

@@ -0,0 +1,114 @@
+"""Custom exception classes for UniFi MCP Server."""
+
+from typing import Any
+
+
+class UniFiMCPException(Exception):
+    """Base exception for UniFi MCP Server."""
+
+    def __init__(self, message: str, details: dict[str, Any] | None = None) -> None:
+        """Initialize exception with message and optional details.
+
+        Args:
+            message: Human-readable error message
+            details: Additional context about the error
+        """
+        super().__init__(message)
+        self.message = message
+        self.details = details or {}
+
+
+class ConfigurationError(UniFiMCPException):
+    """Raised when configuration is invalid or missing."""
+
+    pass
+
+
+class AuthenticationError(UniFiMCPException):
+    """Raised when authentication fails."""
+
+    pass
+
+
+class APIError(UniFiMCPException):
+    """Raised when UniFi API returns an error."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        response_data: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize API error.
+
+        Args:
+            message: Human-readable error message
+            status_code: HTTP status code
+            response_data: Raw API response data
+        """
+        super().__init__(message, {"status_code": status_code, "response": response_data})
+        self.status_code = status_code
+        self.response_data = response_data
+
+
+class RateLimitError(APIError):
+    """Raised when API rate limit is exceeded."""
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded",
+        retry_after: int | None = None,
+    ) -> None:
+        """Initialize rate limit error.
+
+        Args:
+            message: Human-readable error message
+            retry_after: Seconds until rate limit resets
+        """
+        super().__init__(message, status_code=429, response_data={"retry_after": retry_after})
+        self.retry_after = retry_after
+
+
+class ResourceNotFoundError(APIError):
+    """Raised when requested resource is not found."""
+
+    def __init__(self, resource_type: str, resource_id: str) -> None:
+        """Initialize resource not found error.
+
+        Args:
+            resource_type: Type of resource (site, device, client, etc.)
+            resource_id: ID of the resource
+        """
+        message = f"{resource_type} '{resource_id}' not found"
+        super().__init__(message, status_code=404)
+        self.resource_type = resource_type
+        self.resource_id = resource_id
+
+
+class ValidationError(UniFiMCPException):
+    """Raised when input validation fails."""
+
+    pass
+
+
+class NetworkError(UniFiMCPException):
+    """Raised when network communication fails."""
+
+    pass
+
+
+class ConfirmationRequiredError(UniFiMCPException):
+    """Raised when mutating operation requires confirmation."""
+
+    def __init__(self, operation: str) -> None:
+        """Initialize confirmation required error.
+
+        Args:
+            operation: Name of the operation requiring confirmation
+        """
+        message = (
+            f"Operation '{operation}' requires confirmation. "
+            "Set confirm=true to proceed with this mutating operation."
+        )
+        super().__init__(message, {"operation": operation})
+        self.operation = operation

src/utils/helpers.py

@@ -0,0 +1,159 @@
+"""Helper utility functions for UniFi MCP Server."""
+
+import time
+from datetime import datetime, timezone
+from typing import Any
+
+
+def get_timestamp() -> int:
+    """Get current Unix timestamp in seconds.
+
+    Returns:
+        Current timestamp
+    """
+    return int(time.time())
+
+
+def get_iso_timestamp() -> str:
+    """Get current ISO 8601 formatted timestamp.
+
+    Returns:
+        ISO formatted timestamp string
+    """
+    return datetime.now(timezone.utc).isoformat()
+
+
+def format_uptime(uptime_seconds: int) -> str:
+    """Format uptime seconds into human-readable string.
+
+    Args:
+        uptime_seconds: Uptime in seconds
+
+    Returns:
+        Formatted uptime string (e.g., "2d 4h 30m")
+    """
+    days = uptime_seconds // 86400
+    hours = (uptime_seconds % 86400) // 3600
+    minutes = (uptime_seconds % 3600) // 60
+
+    parts = []
+    if days > 0:
+        parts.append(f"{days}d")
+        parts.append(f"{hours}h")
+        parts.append(f"{minutes}m")
+    elif hours > 0:
+        parts.append(f"{hours}h")
+        parts.append(f"{minutes}m")
+    else:
+        parts.append(f"{minutes}m")
+
+    return " ".join(parts)
+
+
+def format_bytes(bytes_value: int, precision: int = 2) -> str:
+    """Format bytes into human-readable string.
+
+    Args:
+        bytes_value: Number of bytes
+        precision: Decimal precision
+
+    Returns:
+        Formatted bytes string (e.g., "1.23 GB")
+    """
+    bytes_float = float(bytes_value)
+    for unit in ["B", "KB", "MB", "GB", "TB", "PB"]:
+        if bytes_float < 1024.0:
+            return f"{bytes_float:.{precision}f} {unit}"
+        bytes_float /= 1024.0
+    return f"{bytes_float:.{precision}f} PB"
+
+
+def format_percentage(value: float, precision: int = 1) -> str:
+    """Format value as percentage string.
+
+    Args:
+        value: Decimal value (0.0 to 1.0 or 0 to 100)
+        precision: Decimal precision
+
+    Returns:
+        Formatted percentage string (e.g., "45.3%")
+    """
+    # Handle both 0-1 and 0-100 ranges
+    pct = value if value > 1 else value * 100
+    return f"{pct:.{precision}f}%"
+
+
+def sanitize_dict(data: dict[str, Any], exclude_keys: list[str] | None = None) -> dict[str, Any]:
+    """Remove sensitive keys from dictionary.
+
+    Args:
+        data: Dictionary to sanitize
+        exclude_keys: List of keys to remove (default: common sensitive keys)
+
+    Returns:
+        Sanitized dictionary copy
+    """
+    if exclude_keys is None:
+        exclude_keys = ["password", "api_key", "secret", "token", "x_api_key", "x-api-key"]
+
+    return {k: v for k, v in data.items() if k.lower() not in [e.lower() for e in exclude_keys]}
+
+
+def merge_dicts(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Merge two dictionaries, with override taking precedence.
+
+    Args:
+        base: Base dictionary
+        override: Override dictionary
+
+    Returns:
+        Merged dictionary
+    """
+    result = base.copy()
+    result.update(override)
+    return result
+
+
+def parse_device_type(model: str) -> str:
+    """Parse device type from model string.
+
+    Args:
+        model: Device model string
+
+    Returns:
+        Device type (ap, switch, gateway, etc.)
+    """
+    model_lower = model.lower()
+
+    if "uap" in model_lower or "u6" in model_lower or "u7" in model_lower:
+        return "ap"
+    elif "usw" in model_lower or "switch" in model_lower:
+        return "switch"
+    elif "usg" in model_lower or "udm" in model_lower or "uxg" in model_lower:
+        return "gateway"
+    elif "unvr" in model_lower or "nvr" in model_lower:
+        return "nvr"
+    else:
+        return "unknown"
+
+
+def build_uri(scheme: str, *parts: str, query: dict[str, Any] | None = None) -> str:
+    """Build a URI with optional query parameters.
+
+    Args:
+        scheme: URI scheme (e.g., "sites")
+        *parts: URI path parts
+        query: Optional query parameters
+
+    Returns:
+        Complete URI string
+    """
+    path = "/".join(str(p) for p in parts if p)
+    uri = f"{scheme}://{path}" if path else f"{scheme}://"
+
+    if query:
+        query_str = "&".join(f"{k}={v}" for k, v in query.items() if v is not None)
+        if query_str:
+            uri += f"?{query_str}"
+
+    return uri

src/utils/logger.py

@@ -0,0 +1,105 @@
+"""Structured logging configuration for UniFi MCP Server."""
+
+import logging
+import sys
+from typing import Any
+
+# Configure logging format
+LOG_FORMAT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
+
+
+def get_logger(name: str, level: str | None = None) -> logging.Logger:
+    """Get a configured logger instance.
+
+    Args:
+        name: Logger name (typically __name__ of the module)
+        level: Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+
+    Returns:
+        Configured logger instance
+    """
+    logger = logging.getLogger(name)
+
+    # Set log level from parameter or environment variable
+    log_level = level or "INFO"
+    logger.setLevel(getattr(logging, log_level.upper()))
+
+    # Avoid duplicate handlers
+    if not logger.handlers:
+        # Console handler
+        handler = logging.StreamHandler(sys.stderr)
+        handler.setLevel(logging.DEBUG)
+
+        # Formatter
+        formatter = logging.Formatter(LOG_FORMAT, DATE_FORMAT)
+        handler.setFormatter(formatter)
+
+        logger.addHandler(handler)
+
+    return logger
+
+
+def log_api_request(
+    logger: logging.Logger,
+    method: str,
+    url: str,
+    status_code: int | None = None,
+    duration_ms: float | None = None,
+    **kwargs: Any,
+) -> None:
+    """Log API request details in structured format.
+
+    Args:
+        logger: Logger instance
+        method: HTTP method
+        url: Request URL
+        status_code: Response status code
+        duration_ms: Request duration in milliseconds
+        **kwargs: Additional context to log
+    """
+    context = {
+        "method": method,
+        "url": url,
+        "status_code": status_code,
+        "duration_ms": duration_ms,
+        **kwargs,
+    }
+
+    # Remove None values
+    context = {k: v for k, v in context.items() if v is not None}
+
+    if status_code and status_code >= 400:
+        logger.error(f"API request failed: {context}")
+    else:
+        logger.info(f"API request: {context}")
+
+
+def log_audit_event(
+    logger: logging.Logger,
+    operation: str,
+    resource_type: str,
+    resource_id: str,
+    success: bool,
+    **kwargs: Any,
+) -> None:
+    """Log audit event for mutating operations.
+
+    Args:
+        logger: Logger instance
+        operation: Operation performed (create, update, delete, etc.)
+        resource_type: Type of resource affected
+        resource_id: ID of the resource
+        success: Whether operation succeeded
+        **kwargs: Additional context to log
+    """
+    context = {
+        "operation": operation,
+        "resource_type": resource_type,
+        "resource_id": resource_id,
+        "success": success,
+        **kwargs,
+    }
+
+    level = logging.INFO if success else logging.ERROR
+    logger.log(level, f"Audit event: {context}")

src/utils/sanitize.py

@@ -0,0 +1,244 @@
+"""Data sanitization utilities for logging and audit trails.
+
+Provides functions to sanitize sensitive data before logging to prevent
+exposure of private information such as MAC addresses, IP addresses,
+client identifiers, and network configuration details.
+"""
+
+import re
+from typing import Any
+
+# Sensitive field patterns
+SENSITIVE_FIELDS = {
+    # Network identifiers
+    "mac",
+    "mac_address",
+    "client_mac",
+    "device_mac",
+    "bssid",
+    "oui",
+    # IP and network info
+    "ip",
+    "ip_address",
+    "fixed_ip",
+    "network_id",
+    "subnet",
+    "gateway",
+    "dns",
+    "dhcp_start",
+    "dhcp_stop",
+    # Device identifiers
+    "device_id",
+    "client_id",
+    "user_id",
+    "site_id",
+    "serial",
+    "serial_number",
+    # Authentication
+    "password",
+    "passphrase",
+    "psk",
+    "key",
+    "secret",
+    "token",
+    "api_key",
+    # Personal information
+    "email",
+    "hostname",
+    "name",
+    "username",
+    "user",
+    # Location
+    "latitude",
+    "longitude",
+    "location",
+}
+
+# Partial redaction patterns (show last N characters)
+PARTIAL_REDACT_FIELDS = {
+    "mac",
+    "mac_address",
+    "client_mac",
+    "device_mac",
+    "ip",
+    "ip_address",
+}
+
+
+def _redact_value(key: str, value: Any, partial: bool = True) -> str:
+    """Redact a sensitive value.
+
+    Args:
+        key: Field name
+        value: Value to redact
+        partial: If True, show last few characters for debugging
+
+    Returns:
+        Redacted string representation
+    """
+    if value is None:
+        return "None"
+
+    str_value = str(value)
+
+    # For MAC addresses and IPs, show last segment for debugging
+    if partial and key.lower() in PARTIAL_REDACT_FIELDS:
+        # MAC address: show last octet (XX:XX:XX:XX:XX:AB)
+        if ":" in str_value and len(str_value) == 17:
+            return f"**:**:**:**:**:{str_value[-2:]}"
+        # IP address: show last octet (XXX.XXX.XXX.123)
+        if "." in str_value and re.match(r"^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$", str_value):
+            return f"***.***.***.{str_value.split('.')[-1]}"
+
+    # Full redaction
+    if len(str_value) <= 4:
+        return "***"
+    return f"***{str_value[-2:]}" if partial else "***"
+
+
+def sanitize_dict(data: dict[str, Any], partial: bool = True) -> dict[str, Any]:
+    """Sanitize sensitive fields in a dictionary.
+
+    Args:
+        data: Dictionary potentially containing sensitive data
+        partial: If True, partially redact some fields for debugging
+
+    Returns:
+        Dictionary with sensitive fields redacted
+    """
+    if not isinstance(data, dict):
+        return data
+
+    sanitized = {}
+    for key, value in data.items():
+        key_lower = key.lower()
+
+        # Check if this key is sensitive
+        is_sensitive = any(pattern in key_lower for pattern in SENSITIVE_FIELDS)
+
+        if is_sensitive:
+            # Redact the value
+            sanitized[key] = _redact_value(key_lower, value, partial)
+        elif isinstance(value, dict):
+            # Recursively sanitize nested dictionaries
+            sanitized[key] = sanitize_dict(value, partial)
+        elif isinstance(value, list):
+            # Sanitize lists
+            sanitized[key] = [
+                sanitize_dict(item, partial) if isinstance(item, dict) else item for item in value
+            ]
+        else:
+            # Keep non-sensitive values as-is
+            sanitized[key] = value
+
+    return sanitized
+
+
+def sanitize_list(data: list[Any], partial: bool = True) -> list[Any]:
+    """Sanitize sensitive fields in a list of dictionaries.
+
+    Args:
+        data: List of dictionaries potentially containing sensitive data
+        partial: If True, partially redact some fields for debugging
+
+    Returns:
+        List with sensitive fields redacted
+    """
+    if not isinstance(data, list):
+        return data
+
+    return [sanitize_dict(item, partial) if isinstance(item, dict) else item for item in data]
+
+
+def sanitize_log_message(message: str, context: dict[str, Any] | None = None) -> str:
+    """Sanitize a log message and optional context.
+
+    Args:
+        message: Log message to sanitize
+        context: Optional context dictionary to include
+
+    Returns:
+        Sanitized log message with context
+    """
+    # Sanitize common patterns in the message itself
+    sanitized_msg = message
+
+    # Redact MAC addresses (XX:XX:XX:XX:XX:XX)
+    sanitized_msg = re.sub(
+        r"\b([0-9A-Fa-f]{2}:){5}([0-9A-Fa-f]{2})\b",
+        lambda m: f"**:**:**:**:**:{m.group(2)}",
+        sanitized_msg,
+    )
+
+    # Redact IP addresses (XXX.XXX.XXX.XXX)
+    sanitized_msg = re.sub(
+        r"\b(\d{1,3}\.){3}(\d{1,3})\b",
+        lambda m: f"***.***.***.{m.group(2)}" if m.group(0) != "0.0.0.0" else m.group(0),
+        sanitized_msg,
+    )
+
+    # Add sanitized context if provided
+    if context:
+        sanitized_context = sanitize_dict(context)
+        sanitized_msg = f"{sanitized_msg} | Context: {sanitized_context}"
+
+    return sanitized_msg
+
+
+def is_production() -> bool:
+    """Check if running in production environment.
+
+    Returns:
+        True if production, False otherwise
+    """
+    import os
+
+    return os.getenv("ENVIRONMENT", "development").lower() in ("production", "prod")
+
+
+def sanitize_for_logging(
+    data: dict[str, Any] | list[Any] | str,
+    force_sanitize: bool = False,
+) -> dict[str, Any] | list[Any] | str:
+    """Sanitize data for logging based on environment.
+
+    In production, always sanitizes. In development, only sanitizes if forced.
+
+    Args:
+        data: Data to potentially sanitize
+        force_sanitize: Force sanitization even in development
+
+    Returns:
+        Sanitized or original data based on environment
+    """
+    # Always sanitize in production or when forced
+    if is_production() or force_sanitize:
+        if isinstance(data, dict):
+            return sanitize_dict(data)
+        elif isinstance(data, list):
+            return sanitize_list(data)
+        elif isinstance(data, str):
+            return sanitize_log_message(data)
+
+    # In development, return original data for debugging
+    return data
+
+
+# Convenience function for backward compatibility
+def sanitize_sensitive_data(
+    data: dict[str, Any] | list[Any], partial: bool = True
+) -> dict[str, Any] | list[Any]:
+    """Sanitize sensitive data (legacy function name).
+
+    Args:
+        data: Data to sanitize
+        partial: If True, partially redact some fields for debugging
+
+    Returns:
+        Sanitized data
+    """
+    if isinstance(data, dict):
+        return sanitize_dict(data, partial)
+    elif isinstance(data, list):
+        return sanitize_list(data, partial)
+    return data