kubectl-mcp-server 1.15.0__py3-none-any.whl → 1.17.0__py3-none-any.whl

kubectl_mcp_tool/config/loader.py

@@ -0,0 +1,386 @@
+"""Configuration loader with TOML support, drop-in directories, and SIGHUP reload.
+
+This module handles:
+- Loading main config from ~/.config/kubectl-mcp-server/config.toml
+- Merging drop-in configs from ~/.config/kubectl-mcp-server/config.d/*.toml
+- Environment variable overrides
+- SIGHUP signal handling for runtime reloads
+"""
+
+import logging
+import os
+import signal
+import sys
+from dataclasses import fields
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Union
+
+from .schema import (
+    BrowserConfig,
+    Config,
+    KubernetesConfig,
+    LoggingConfig,
+    MetricsConfig,
+    SafetyConfig,
+    ServerConfig,
+    validate_config,
+)
+
+logger = logging.getLogger(__name__)
+
+# Try to import tomli/tomllib for TOML parsing
+try:
+    import tomllib  # Python 3.11+
+except ImportError:
+    try:
+        import tomli as tomllib  # type: ignore
+    except ImportError:
+        tomllib = None  # type: ignore
+
+# Global config instance
+_config: Optional[Config] = None
+_config_callbacks: List[Callable[[Config], None]] = []
+
+
+def get_config_paths() -> Dict[str, Path]:
+    """Get standard configuration paths.
+
+    Returns:
+        Dictionary with paths for config_dir, main_config, and drop_in_dir
+    """
+    # Check XDG_CONFIG_HOME first, then fall back to ~/.config
+    xdg_config = os.environ.get("XDG_CONFIG_HOME")
+    if xdg_config:
+        base_dir = Path(xdg_config)
+    else:
+        base_dir = Path.home() / ".config"
+
+    config_dir = base_dir / "kubectl-mcp-server"
+
+    return {
+        "config_dir": config_dir,
+        "main_config": config_dir / "config.toml",
+        "drop_in_dir": config_dir / "config.d",
+    }
+
+
+def _load_toml_file(path: Path) -> Dict[str, Any]:
+    """Load a TOML file and return its contents as a dictionary.
+
+    Args:
+        path: Path to the TOML file
+
+    Returns:
+        Dictionary containing the TOML data
+
+    Raises:
+        RuntimeError: If tomllib/tomli is not available
+        FileNotFoundError: If the file doesn't exist
+        ValueError: If the TOML is invalid
+    """
+    if tomllib is None:
+        raise RuntimeError(
+            "TOML parsing requires Python 3.11+ or the 'tomli' package. "
+            "Install with: pip install tomli"
+        )
+
+    with open(path, "rb") as f:
+        return tomllib.load(f)
+
+
+def _deep_merge(base: Dict[str, Any], override: Dict[str, Any]) -> Dict[str, Any]:
+    """Deep merge two dictionaries, with override taking precedence.
+
+    Args:
+        base: Base dictionary
+        override: Override dictionary (takes precedence)
+
+    Returns:
+        Merged dictionary
+    """
+    result = base.copy()
+
+    for key, value in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = _deep_merge(result[key], value)
+        else:
+            result[key] = value
+
+    return result
+
+
+def _apply_env_overrides(config_dict: Dict[str, Any]) -> Dict[str, Any]:
+    """Apply environment variable overrides to configuration.
+
+    Environment variables follow the pattern:
+    MCP_<SECTION>_<KEY>=value
+
+    Examples:
+        MCP_SERVER_PORT=9000
+        MCP_SAFETY_MODE=read-only
+        MCP_BROWSER_ENABLED=true
+
+    Args:
+        config_dict: Configuration dictionary
+
+    Returns:
+        Configuration with environment overrides applied
+    """
+    result = config_dict.copy()
+
+    env_mappings = {
+        # Server settings
+        "MCP_SERVER_TRANSPORT": ("server", "transport"),
+        "MCP_SERVER_HOST": ("server", "host"),
+        "MCP_SERVER_PORT": ("server", "port", int),
+        "MCP_DEBUG": ("server", "debug", lambda x: x.lower() in ("true", "1", "yes")),
+        "MCP_LOG_FILE": ("server", "log_file"),
+        "MCP_LOG_LEVEL": ("server", "log_level"),
+        # Safety settings
+        "MCP_SAFETY_MODE": ("safety", "mode"),
+        # Browser settings
+        "MCP_BROWSER_ENABLED": ("browser", "enabled", lambda x: x.lower() in ("true", "1", "yes")),
+        "MCP_BROWSER_PROVIDER": ("browser", "provider"),
+        "MCP_BROWSER_HEADED": ("browser", "headed", lambda x: x.lower() in ("true", "1", "yes")),
+        "BROWSERBASE_API_KEY": ("browser", "browserbase_api_key"),
+        "BROWSERBASE_PROJECT_ID": ("browser", "browserbase_project_id"),
+        "BROWSER_USE_API_KEY": ("browser", "browseruse_api_key"),
+        "MCP_BROWSER_CDP_URL": ("browser", "cdp_url"),
+        # Metrics settings
+        "MCP_METRICS_ENABLED": ("metrics", "enabled", lambda x: x.lower() in ("true", "1", "yes")),
+        "MCP_TRACING_ENABLED": ("metrics", "tracing_enabled", lambda x: x.lower() in ("true", "1", "yes")),
+        "OTEL_EXPORTER_OTLP_ENDPOINT": ("metrics", "otlp_endpoint"),
+        "OTEL_SERVICE_NAME": ("metrics", "service_name"),
+        # Kubernetes settings
+        "KUBECONFIG": ("kubernetes", "kubeconfig"),
+        "MCP_K8S_CONTEXT": ("kubernetes", "context"),
+        "MCP_K8S_NAMESPACE": ("kubernetes", "default_namespace"),
+    }
+
+    for env_var, mapping in env_mappings.items():
+        value = os.environ.get(env_var)
+        if value is not None:
+            section = mapping[0]
+            key = mapping[1]
+            converter = mapping[2] if len(mapping) > 2 else str
+
+            if section not in result:
+                result[section] = {}
+
+            try:
+                result[section][key] = converter(value)
+            except (ValueError, TypeError) as e:
+                logger.warning(f"Invalid value for {env_var}: {value} ({e})")
+
+    return result
+
+
+def _dict_to_config(config_dict: Dict[str, Any]) -> Config:
+    """Convert a configuration dictionary to a Config dataclass.
+
+    Args:
+        config_dict: Configuration dictionary
+
+    Returns:
+        Config dataclass instance
+    """
+
+    def make_dataclass(cls, data: Dict[str, Any]):
+        """Create a dataclass instance from a dictionary, ignoring extra keys."""
+        valid_keys = {f.name for f in fields(cls)}
+        filtered = {k: v for k, v in data.items() if k in valid_keys}
+        return cls(**filtered)
+
+    server = make_dataclass(ServerConfig, config_dict.get("server", {}))
+    safety = make_dataclass(SafetyConfig, config_dict.get("safety", {}))
+    browser = make_dataclass(BrowserConfig, config_dict.get("browser", {}))
+    metrics = make_dataclass(MetricsConfig, config_dict.get("metrics", {}))
+    logging_config = make_dataclass(LoggingConfig, config_dict.get("logging", {}))
+    kubernetes = make_dataclass(KubernetesConfig, config_dict.get("kubernetes", {}))
+
+    # Collect custom/unknown sections
+    known_sections = {"server", "safety", "browser", "metrics", "logging", "kubernetes"}
+    custom = {k: v for k, v in config_dict.items() if k not in known_sections}
+
+    return Config(
+        server=server,
+        safety=safety,
+        browser=browser,
+        metrics=metrics,
+        logging=logging_config,
+        kubernetes=kubernetes,
+        custom=custom,
+    )
+
+
+def load_config(
+    config_file: Optional[Union[str, Path]] = None,
+    skip_env: bool = False,
+) -> Config:
+    """Load configuration from files and environment.
+
+    Loading order (later takes precedence):
+    1. Default values
+    2. Main config file (~/.config/kubectl-mcp-server/config.toml)
+    3. Drop-in files (~/.config/kubectl-mcp-server/config.d/*.toml) in sorted order
+    4. Custom config file (if specified)
+    5. Environment variables (unless skip_env=True)
+
+    Args:
+        config_file: Optional path to a specific config file
+        skip_env: If True, skip environment variable overrides
+
+    Returns:
+        Loaded Config instance
+    """
+    global _config
+
+    config_dict: Dict[str, Any] = {}
+    paths = get_config_paths()
+
+    # 1. Load main config file if it exists
+    main_config = paths["main_config"]
+    if main_config.exists():
+        try:
+            loaded = _load_toml_file(main_config)
+            config_dict = _deep_merge(config_dict, loaded)
+            logger.debug(f"Loaded config from {main_config}")
+        except Exception as e:
+            logger.warning(f"Failed to load {main_config}: {e}")
+
+    # 2. Load drop-in configs in sorted order
+    drop_in_dir = paths["drop_in_dir"]
+    if drop_in_dir.exists() and drop_in_dir.is_dir():
+        drop_in_files = sorted(drop_in_dir.glob("*.toml"))
+        for drop_in_file in drop_in_files:
+            try:
+                loaded = _load_toml_file(drop_in_file)
+                config_dict = _deep_merge(config_dict, loaded)
+                logger.debug(f"Loaded drop-in config from {drop_in_file}")
+            except Exception as e:
+                logger.warning(f"Failed to load {drop_in_file}: {e}")
+
+    # 3. Load custom config file if specified
+    if config_file:
+        config_path = Path(config_file)
+        if config_path.exists():
+            try:
+                loaded = _load_toml_file(config_path)
+                config_dict = _deep_merge(config_dict, loaded)
+                logger.debug(f"Loaded custom config from {config_path}")
+            except Exception as e:
+                logger.warning(f"Failed to load {config_path}: {e}")
+        else:
+            logger.warning(f"Config file not found: {config_path}")
+
+    # 4. Apply environment variable overrides
+    if not skip_env:
+        config_dict = _apply_env_overrides(config_dict)
+
+    # 5. Validate configuration
+    errors = validate_config(config_dict)
+    if errors:
+        for error in errors:
+            logger.error(f"Config validation error: {error}")
+
+    # 6. Convert to Config dataclass
+    _config = _dict_to_config(config_dict)
+
+    return _config
+
+
+def get_config() -> Config:
+    """Get the current configuration, loading if necessary.
+
+    Returns:
+        Current Config instance
+    """
+    global _config
+    if _config is None:
+        _config = load_config()
+    return _config
+
+
+def reload_config() -> Config:
+    """Reload configuration from files.
+
+    This is called by the SIGHUP handler for runtime config updates.
+
+    Returns:
+        Newly loaded Config instance
+    """
+    global _config
+
+    logger.info("Reloading configuration...")
+    old_config = _config
+
+    try:
+        _config = load_config()
+        logger.info("Configuration reloaded successfully")
+
+        # Notify callbacks
+        for callback in _config_callbacks:
+            try:
+                callback(_config)
+            except Exception as e:
+                logger.error(f"Config reload callback failed: {e}")
+
+    except Exception as e:
+        logger.error(f"Failed to reload configuration: {e}")
+        _config = old_config
+        raise
+
+    return _config
+
+
+def register_reload_callback(callback: Callable[[Config], None]) -> None:
+    """Register a callback to be called when configuration is reloaded.
+
+    Args:
+        callback: Function that takes the new Config as argument
+    """
+    _config_callbacks.append(callback)
+
+
+def unregister_reload_callback(callback: Callable[[Config], None]) -> None:
+    """Unregister a previously registered reload callback.
+
+    Args:
+        callback: The callback function to remove
+    """
+    try:
+        _config_callbacks.remove(callback)
+    except ValueError:
+        pass
+
+
+def _sighup_handler(signum: int, frame: Any) -> None:
+    """Handle SIGHUP signal for configuration reload."""
+    logger.info("Received SIGHUP, reloading configuration...")
+    try:
+        reload_config()
+    except Exception as e:
+        logger.error(f"Configuration reload failed: {e}")
+
+
+def setup_sighup_handler() -> bool:
+    """Set up SIGHUP handler for runtime configuration reload.
+
+    Returns:
+        True if handler was set up, False if not supported (e.g., Windows)
+    """
+    if sys.platform == "win32":
+        logger.debug("SIGHUP not supported on Windows")
+        return False
+
+    try:
+        signal.signal(signal.SIGHUP, _sighup_handler)
+        logger.debug("SIGHUP handler installed for config reload")
+        return True
+    except (OSError, AttributeError) as e:
+        logger.warning(f"Could not install SIGHUP handler: {e}")
+        return False
+
+
+# Re-export Config from schema
+Config = Config

kubectl_mcp_tool/config/schema.py

@@ -0,0 +1,184 @@
+"""Configuration schema definitions for kubectl-mcp-server.
+
+Defines dataclasses for type-safe configuration with validation.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ServerConfig:
+    """MCP server configuration."""
+
+    transport: str = "streamable-http"
+    host: str = "127.0.0.1"
+    port: int = 8000
+    debug: bool = False
+    log_file: Optional[str] = None
+    log_level: str = "INFO"
+
+    def __post_init__(self):
+        """Validate configuration values."""
+        valid_transports = {"stdio", "sse", "streamable-http"}
+        if self.transport not in valid_transports:
+            raise ValueError(f"Invalid transport: {self.transport}. Must be one of {valid_transports}")
+
+        if not 1 <= self.port <= 65535:
+            raise ValueError(f"Invalid port: {self.port}. Must be between 1 and 65535")
+
+        valid_log_levels = {"DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"}
+        if self.log_level.upper() not in valid_log_levels:
+            raise ValueError(f"Invalid log_level: {self.log_level}. Must be one of {valid_log_levels}")
+
+
+@dataclass
+class SafetyConfig:
+    """Safety mode configuration."""
+
+    mode: str = "normal"
+
+    # Additional safety settings
+    confirm_destructive: bool = False
+    max_delete_count: int = 10
+    blocked_namespaces: List[str] = field(default_factory=lambda: ["kube-system", "kube-public"])
+
+    def __post_init__(self):
+        """Validate safety mode."""
+        valid_modes = {"normal", "read-only", "disable-destructive"}
+        if self.mode not in valid_modes:
+            raise ValueError(f"Invalid safety mode: {self.mode}. Must be one of {valid_modes}")
+
+
+@dataclass
+class BrowserConfig:
+    """Browser automation configuration."""
+
+    enabled: bool = False
+    provider: str = "local"
+    headed: bool = False
+    timeout: int = 60
+    max_retries: int = 3
+
+    # Provider-specific settings
+    browserbase_api_key: Optional[str] = None
+    browserbase_project_id: Optional[str] = None
+    browseruse_api_key: Optional[str] = None
+    cdp_url: Optional[str] = None
+
+    def __post_init__(self):
+        """Validate browser configuration."""
+        valid_providers = {"local", "browserbase", "browseruse", "cdp"}
+        if self.provider not in valid_providers:
+            raise ValueError(f"Invalid browser provider: {self.provider}. Must be one of {valid_providers}")
+
+
+@dataclass
+class MetricsConfig:
+    """Metrics and observability configuration."""
+
+    enabled: bool = False
+    endpoint: str = "/metrics"
+
+    # Tracing settings
+    tracing_enabled: bool = False
+    otlp_endpoint: Optional[str] = None
+    service_name: str = "kubectl-mcp-server"
+    sample_rate: float = 1.0
+
+    def __post_init__(self):
+        """Validate metrics configuration."""
+        if not 0.0 <= self.sample_rate <= 1.0:
+            raise ValueError(f"Invalid sample_rate: {self.sample_rate}. Must be between 0.0 and 1.0")
+
+
+@dataclass
+class LoggingConfig:
+    """Logging configuration."""
+
+    level: str = "INFO"
+    format: str = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    file: Optional[str] = None
+    max_size_mb: int = 10
+    backup_count: int = 5
+
+    def __post_init__(self):
+        """Validate logging configuration."""
+        valid_levels = {"DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"}
+        if self.level.upper() not in valid_levels:
+            raise ValueError(f"Invalid log level: {self.level}. Must be one of {valid_levels}")
+
+
+@dataclass
+class KubernetesConfig:
+    """Kubernetes client configuration."""
+
+    context: Optional[str] = None
+    kubeconfig: Optional[str] = None
+    in_cluster: bool = False
+    default_namespace: str = "default"
+    timeout: int = 30
+
+
+@dataclass
+class Config:
+    """Root configuration container."""
+
+    server: ServerConfig = field(default_factory=ServerConfig)
+    safety: SafetyConfig = field(default_factory=SafetyConfig)
+    browser: BrowserConfig = field(default_factory=BrowserConfig)
+    metrics: MetricsConfig = field(default_factory=MetricsConfig)
+    logging: LoggingConfig = field(default_factory=LoggingConfig)
+    kubernetes: KubernetesConfig = field(default_factory=KubernetesConfig)
+
+    # Custom settings from drop-in configs
+    custom: Dict[str, Any] = field(default_factory=dict)
+
+
+def validate_config(config_dict: Dict[str, Any]) -> List[str]:
+    """Validate configuration dictionary and return list of errors.
+
+    Args:
+        config_dict: Configuration dictionary to validate
+
+    Returns:
+        List of validation error messages (empty if valid)
+    """
+    errors = []
+
+    # Validate server section
+    if "server" in config_dict:
+        server = config_dict["server"]
+        valid_transports = {"stdio", "sse", "streamable-http"}
+        if server.get("transport") and server["transport"] not in valid_transports:
+            errors.append(f"Invalid server.transport: {server['transport']}")
+
+        port = server.get("port")
+        if port is not None and not (1 <= port <= 65535):
+            errors.append(f"Invalid server.port: {port}")
+
+    # Validate safety section
+    if "safety" in config_dict:
+        safety = config_dict["safety"]
+        valid_modes = {"normal", "read-only", "disable-destructive"}
+        if safety.get("mode") and safety["mode"] not in valid_modes:
+            errors.append(f"Invalid safety.mode: {safety['mode']}")
+
+    # Validate browser section
+    if "browser" in config_dict:
+        browser = config_dict["browser"]
+        valid_providers = {"local", "browserbase", "browseruse", "cdp"}
+        if browser.get("provider") and browser["provider"] not in valid_providers:
+            errors.append(f"Invalid browser.provider: {browser['provider']}")
+
+    # Validate metrics section
+    if "metrics" in config_dict:
+        metrics = config_dict["metrics"]
+        sample_rate = metrics.get("sample_rate")
+        if sample_rate is not None and not (0.0 <= sample_rate <= 1.0):
+            errors.append(f"Invalid metrics.sample_rate: {sample_rate}")
+
+    return errors