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

kubectl_mcp_tool/crd_detector.py

@@ -0,0 +1,247 @@
+"""CRD Auto-Discovery Framework for kubectl-mcp-server.
+
+Detects installed CRDs in the cluster and enables/disables toolsets accordingly.
+"""
+
+import subprocess
+import json
+from typing import Dict, List, Optional, Set
+from functools import lru_cache
+import time
+
+from .k8s_config import _get_kubectl_context_args
+
+
+CRD_GROUPS = {
+    "flux": [
+        "kustomizations.kustomize.toolkit.fluxcd.io",
+        "helmreleases.helm.toolkit.fluxcd.io",
+        "gitrepositories.source.toolkit.fluxcd.io",
+        "helmrepositories.source.toolkit.fluxcd.io",
+    ],
+    "argocd": [
+        "applications.argoproj.io",
+        "applicationsets.argoproj.io",
+        "appprojects.argoproj.io",
+    ],
+    "certmanager": [
+        "certificates.cert-manager.io",
+        "issuers.cert-manager.io",
+        "clusterissuers.cert-manager.io",
+        "certificaterequests.cert-manager.io",
+        "orders.acme.cert-manager.io",
+        "challenges.acme.cert-manager.io",
+    ],
+    "kyverno": [
+        "clusterpolicies.kyverno.io",
+        "policies.kyverno.io",
+        "policyreports.wgpolicyk8s.io",
+        "clusterpolicyreports.wgpolicyk8s.io",
+    ],
+    "gatekeeper": [
+        "constrainttemplates.templates.gatekeeper.sh",
+        "configs.config.gatekeeper.sh",
+    ],
+    "velero": [
+        "backups.velero.io",
+        "restores.velero.io",
+        "schedules.velero.io",
+        "backupstoragelocations.velero.io",
+    ],
+    "keda": [
+        "scaledobjects.keda.sh",
+        "scaledjobs.keda.sh",
+        "triggerauthentications.keda.sh",
+    ],
+    "cilium": [
+        "ciliumnetworkpolicies.cilium.io",
+        "ciliumclusterwidenetworkpolicies.cilium.io",
+        "ciliumendpoints.cilium.io",
+    ],
+    "istio": [
+        "virtualservices.networking.istio.io",
+        "destinationrules.networking.istio.io",
+        "gateways.networking.istio.io",
+    ],
+    "argorollouts": [
+        "rollouts.argoproj.io",
+        "analysistemplates.argoproj.io",
+    ],
+    "kubevirt": [
+        "virtualmachines.kubevirt.io",
+        "virtualmachineinstances.kubevirt.io",
+    ],
+    "capi": [
+        "clusters.cluster.x-k8s.io",
+        "machines.cluster.x-k8s.io",
+        "machinedeployments.cluster.x-k8s.io",
+    ],
+}
+
+
+_crd_cache: Dict[str, Dict[str, bool]] = {}
+_cache_timestamp: Dict[str, float] = {}
+CACHE_TTL = 300
+
+
+def _get_cluster_crds(context: str = "") -> Set[str]:
+    """Get all CRDs installed in the cluster."""
+    try:
+        cmd = ["kubectl"] + _get_kubectl_context_args(context) + [
+            "get", "crds", "-o", "jsonpath={.items[*].metadata.name}"
+        ]
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
+        if result.returncode == 0:
+            return set(result.stdout.split())
+        return set()
+    except Exception:
+        return set()
+
+
+def detect_crds(context: str = "", force_refresh: bool = False) -> Dict[str, bool]:
+    """Detect which CRD groups are installed in the cluster.
+
+    Args:
+        context: Kubernetes context to use
+        force_refresh: Force refresh the cache
+
+    Returns:
+        Dict mapping CRD group name to installed status
+    """
+    cache_key = context or "default"
+
+    if not force_refresh and cache_key in _crd_cache:
+        if time.time() - _cache_timestamp.get(cache_key, 0) < CACHE_TTL:
+            return _crd_cache[cache_key]
+
+    installed_crds = _get_cluster_crds(context)
+
+    result = {}
+    for group_name, crds in CRD_GROUPS.items():
+        result[group_name] = any(crd in installed_crds for crd in crds)
+
+    _crd_cache[cache_key] = result
+    _cache_timestamp[cache_key] = time.time()
+
+    return result
+
+
+def crd_exists(crd_name: str, context: str = "") -> bool:
+    """Check if a specific CRD exists in the cluster.
+
+    Args:
+        crd_name: Full CRD name (e.g., "certificates.cert-manager.io")
+        context: Kubernetes context to use
+
+    Returns:
+        True if CRD exists, False otherwise
+    """
+    try:
+        cmd = ["kubectl"] + _get_kubectl_context_args(context) + [
+            "get", "crd", crd_name, "-o", "name"
+        ]
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=10)
+        return result.returncode == 0
+    except Exception:
+        return False
+
+
+def get_enabled_toolsets(context: str = "") -> List[str]:
+    """Get list of toolsets that should be enabled based on detected CRDs.
+
+    Args:
+        context: Kubernetes context to use
+
+    Returns:
+        List of enabled toolset names
+    """
+    crds = detect_crds(context)
+    enabled = []
+
+    if crds.get("flux") or crds.get("argocd"):
+        enabled.append("gitops")
+    if crds.get("certmanager"):
+        enabled.append("certs")
+    if crds.get("kyverno") or crds.get("gatekeeper"):
+        enabled.append("policy")
+    if crds.get("velero"):
+        enabled.append("backup")
+    if crds.get("keda"):
+        enabled.append("keda")
+    if crds.get("cilium"):
+        enabled.append("cilium")
+    if crds.get("argorollouts"):
+        enabled.append("rollouts")
+    if crds.get("kubevirt"):
+        enabled.append("kubevirt")
+    if crds.get("capi"):
+        enabled.append("capi")
+    if crds.get("istio"):
+        enabled.append("istio")
+
+    return enabled
+
+
+def get_crd_status_summary(context: str = "") -> Dict:
+    """Get a summary of CRD detection status.
+
+    Args:
+        context: Kubernetes context to use
+
+    Returns:
+        Summary dict with detected CRDs and enabled toolsets
+    """
+    crds = detect_crds(context)
+    enabled = get_enabled_toolsets(context)
+
+    return {
+        "context": context or "current",
+        "crd_groups": crds,
+        "enabled_toolsets": enabled,
+        "total_groups_detected": sum(1 for v in crds.values() if v),
+        "total_toolsets_enabled": len(enabled),
+    }
+
+
+class FeatureNotInstalledError(Exception):
+    """Raised when required CRDs are not installed."""
+
+    def __init__(self, toolset: str, required_crds: List[str]):
+        self.toolset = toolset
+        self.required_crds = required_crds
+        super().__init__(
+            f"{toolset} toolset requires one of these CRDs: {', '.join(required_crds)}. "
+            f"Install the required operator to use this feature."
+        )
+
+
+def require_crd(crd_name: str, toolset: str, context: str = ""):
+    """Check if a CRD exists and raise an error if not.
+
+    Args:
+        crd_name: CRD name to check
+        toolset: Toolset name for error message
+        context: Kubernetes context
+
+    Raises:
+        FeatureNotInstalledError: If CRD is not installed
+    """
+    if not crd_exists(crd_name, context):
+        raise FeatureNotInstalledError(toolset, [crd_name])
+
+
+def require_any_crd(crd_names: List[str], toolset: str, context: str = ""):
+    """Check if any of the CRDs exist and raise an error if none are found.
+
+    Args:
+        crd_names: List of CRD names to check
+        toolset: Toolset name for error message
+        context: Kubernetes context
+
+    Raises:
+        FeatureNotInstalledError: If no CRDs are installed
+    """
+    for crd in crd_names:
+        if crd_exists(crd, context):
+            return
+    raise FeatureNotInstalledError(toolset, crd_names)

kubectl_mcp_tool/k8s_config.py

@@ -509,3 +509,22 @@ def context_exists(context: str) -> bool:
     """
     contexts = list_contexts()
     return any(ctx["name"] == context for ctx in contexts)
+
+
+def _get_kubectl_context_args(context: str = "") -> list:
+    """
+    Get kubectl command arguments for specifying a context.
+
+    This utility function returns the appropriate --context flag arguments
+    for kubectl commands when targeting a specific cluster.
+
+    Args:
+        context: Context name (empty string for default context)
+
+    Returns:
+        List of command arguments, e.g., ["--context", "my-cluster"]
+        or empty list if no context specified
+    """
+    if context and context.strip():
+        return ["--context", context.strip()]
+    return []

kubectl_mcp_tool/mcp_server.py

@@ -23,12 +23,49 @@ import logging
 import asyncio
 import os
 import platform
-from typing import List, Optional, Any
+import signal
+from pathlib import Path
+from typing import List, Optional, Any, Dict
 
 # Import k8s_config early to patch kubernetes config for in-cluster support
 # This must be done before any tools are imported
 import kubectl_mcp_tool.k8s_config  # noqa: F401
 
+# Import safety mode for operation control
+from kubectl_mcp_tool.safety import (
+    SafetyMode,
+    set_safety_mode,
+    get_safety_mode,
+    get_mode_info,
+)
+
+# Import observability for metrics and tracing
+from kubectl_mcp_tool.observability import (
+    get_stats_collector,
+    get_metrics,
+    init_tracing,
+    shutdown_tracing,
+    is_prometheus_available,
+    is_tracing_available,
+    record_tool_call_metric,
+    record_tool_duration_metric,
+    record_tool_error_metric,
+)
+
+# Import config loader
+from kubectl_mcp_tool.config import (
+    load_config,
+    get_config,
+    register_reload_callback,
+    setup_sighup_handler,
+)
+
+# Import custom prompts
+from kubectl_mcp_tool.prompts import (
+    load_prompts_from_config,
+    get_builtin_prompts,
+)
+
 from kubectl_mcp_tool.tools import (
     register_helm_tools,
     register_pod_tools,
@@ -45,6 +82,16 @@ from kubectl_mcp_tool.tools import (
     is_browser_available,
     register_ui_tools,
     is_ui_available,
+    register_gitops_tools,
+    register_certs_tools,
+    register_policy_tools,
+    register_backup_tools,
+    register_keda_tools,
+    register_cilium_tools,
+    register_rollouts_tools,
+    register_capi_tools,
+    register_kubevirt_tools,
+    register_istio_tools,
 )
 from kubectl_mcp_tool.resources import register_resources
 from kubectl_mcp_tool.prompts import register_prompts
@@ -106,12 +153,20 @@ except ImportError:
 class MCPServer:
     """MCP server implementation."""
 
-    def __init__(self, name: str, non_destructive: bool = False):
+    def __init__(
+        self,
+        name: str,
+        read_only: bool = False,
+        disable_destructive: bool = False,
+        config_file: Optional[str] = None,
+    ):
         """Initialize the MCP server.
 
         Args:
             name: Server name for identification
-            non_destructive: If True, block destructive operations
+            read_only: If True, block all write operations (read-only mode)
+            disable_destructive: If True, block only destructive operations
+            config_file: Optional path to TOML config file
 
         Environment Variables:
             MCP_AUTH_ENABLED: Enable OAuth 2.1 authentication (default: false)
@@ -121,9 +176,29 @@ class MCPServer:
             MCP_AUTH_REQUIRED_SCOPES: Required scopes (default: mcp:tools)
         """
         self.name = name
-        self.non_destructive = non_destructive
         self._dependencies_checked = False
         self._dependencies_available = None
+        self._stats = get_stats_collector()
+
+        # Persist CLI safety overrides for reloads
+        self._cli_read_only = read_only
+        self._cli_disable_destructive = disable_destructive
+
+        # Load configuration from file and environment
+        self.config = self._load_configuration(config_file)
+
+        # Apply safety mode from config or parameters
+        self._apply_safety_mode(self._cli_read_only, self._cli_disable_destructive)
+
+        # For backward compatibility, expose non_destructive
+        self.non_destructive = get_safety_mode() != SafetyMode.NORMAL
+
+        # Initialize observability (tracing, metrics)
+        self._init_observability()
+
+        # Register config reload callback and set up SIGHUP handler
+        register_reload_callback(self._on_config_reload)
+        setup_sighup_handler()
 
         # Load authentication configuration
         self.auth_config = get_auth_config()
@@ -140,6 +215,71 @@ class MCPServer:
         self.setup_resources()
         self.setup_prompts()
 
+        # Log startup info
+        mode_info = get_mode_info()
+        logger.info(f"MCP Server initialized: {name}")
+        logger.info(f"Safety mode: {mode_info['mode']} - {mode_info['description']}")
+
+    def _load_configuration(self, config_file: Optional[str]) -> Any:
+        """Load configuration from TOML file and environment."""
+        try:
+            config = load_config(config_file=config_file if config_file else None)
+            logger.debug(f"Configuration loaded successfully")
+            return config
+        except Exception as e:
+            logger.warning(f"Failed to load config file: {e}. Using defaults.")
+            return load_config(skip_env=False)
+
+    def _apply_safety_mode(self, read_only: bool, disable_destructive: bool) -> None:
+        """Apply safety mode from config or CLI parameters.
+
+        CLI parameters take precedence over config file settings.
+        """
+        # Check config first
+        config_mode = getattr(self.config.safety, 'mode', 'normal') if hasattr(self.config, 'safety') else 'normal'
+
+        # CLI parameters override config
+        if read_only:
+            set_safety_mode(SafetyMode.READ_ONLY)
+        elif disable_destructive:
+            set_safety_mode(SafetyMode.DISABLE_DESTRUCTIVE)
+        elif config_mode == 'read-only' or config_mode == 'read_only':
+            set_safety_mode(SafetyMode.READ_ONLY)
+        elif config_mode == 'disable-destructive' or config_mode == 'disable_destructive':
+            set_safety_mode(SafetyMode.DISABLE_DESTRUCTIVE)
+        else:
+            set_safety_mode(SafetyMode.NORMAL)
+
+    def _init_observability(self) -> None:
+        """Initialize observability components (tracing, metrics)."""
+        # Check if tracing is enabled in config
+        tracing_enabled = getattr(self.config.metrics, 'tracing_enabled', False) if hasattr(self.config, 'metrics') else False
+        otlp_endpoint = getattr(self.config.metrics, 'otlp_endpoint', None) if hasattr(self.config, 'metrics') else None
+
+        if tracing_enabled or otlp_endpoint or os.environ.get('OTEL_EXPORTER_OTLP_ENDPOINT'):
+            try:
+                init_tracing()
+                logger.info("OpenTelemetry tracing initialized")
+            except Exception as e:
+                logger.warning(f"Failed to initialize tracing: {e}")
+
+        if is_prometheus_available():
+            logger.debug("Prometheus metrics available")
+
+    def _on_config_reload(self, new_config: Any) -> None:
+        """Handle configuration reload (called on SIGHUP)."""
+        logger.info("Configuration reloaded")
+        self.config = new_config
+
+        # Re-apply safety mode from new config, honoring CLI precedence
+        self._apply_safety_mode(self._cli_read_only, self._cli_disable_destructive)
+
+        # Refresh non_destructive flag
+        self.non_destructive = get_safety_mode() != SafetyMode.NORMAL
+
+        mode_info = get_mode_info()
+        logger.info(f"Safety mode after reload: {mode_info['mode']}")
+
     def _setup_auth(self) -> Optional[Any]:
         """Set up authentication if enabled."""
         if not self.auth_config.enabled:
@@ -196,13 +336,34 @@ class MCPServer:
         else:
             logger.debug("MCP-UI tools disabled (install mcp-ui-server to enable)")
 
+        # Register ecosystem tools (GitOps, Cert-Manager, Policy, Backup)
+        # These tools auto-detect installed CRDs and gracefully handle missing components
+        register_gitops_tools(self.server, self.non_destructive)
+        register_certs_tools(self.server, self.non_destructive)
+        register_policy_tools(self.server, self.non_destructive)
+        register_backup_tools(self.server, self.non_destructive)
+        logger.debug("Ecosystem tools registered (GitOps, Certs, Policy, Backup)")
+
+        # Register advanced ecosystem tools (KEDA, Cilium, Rollouts, CAPI, KubeVirt, Istio)
+        register_keda_tools(self.server, self.non_destructive)
+        register_cilium_tools(self.server, self.non_destructive)
+        register_rollouts_tools(self.server, self.non_destructive)
+        register_capi_tools(self.server, self.non_destructive)
+        register_kubevirt_tools(self.server, self.non_destructive)
+        register_istio_tools(self.server, self.non_destructive)
+        logger.debug("Advanced ecosystem tools registered (KEDA, Cilium, Rollouts, CAPI, KubeVirt, Istio)")
+
     def setup_resources(self):
         """Set up MCP resources for Kubernetes data exposure."""
         register_resources(self.server)
 
     def setup_prompts(self):
-        """Set up MCP prompts."""
-        register_prompts(self.server)
+        """Set up MCP prompts from built-in and custom config."""
+        # Get custom prompts path from config if specified
+        prompts_config_path = None
+        if hasattr(self.config, 'prompts') and hasattr(self.config.prompts, 'file'):
+            prompts_config_path = self.config.prompts.file
+        register_prompts(self.server, config_path=prompts_config_path)
 
     def _check_dependencies(self) -> bool:
         """Check if required dependencies are available."""
@@ -331,17 +492,51 @@ class MCPServer:
         try:
             # FastMCP 3 uses create_sse_app() to create a Starlette ASGI app
             from fastmcp.server.http import create_sse_app
+            from starlette.applications import Starlette
+            from starlette.responses import JSONResponse, PlainTextResponse
+            from starlette.routing import Route, Mount
+
+            # Create observability endpoints
+            async def health_check(request):
+                return JSONResponse({"status": "healthy", "server": self.name})
+
+            async def stats_endpoint(request):
+                stats = self._stats.get_stats()
+                return JSONResponse(stats)
+
+            async def metrics_endpoint(request):
+                if is_prometheus_available():
+                    metrics_text = get_metrics()
+                    return PlainTextResponse(metrics_text, media_type="text/plain; version=0.0.4; charset=utf-8")
+                else:
+                    return PlainTextResponse("# Prometheus metrics not available\n", media_type="text/plain")
+
+            async def safety_mode_endpoint(request):
+                mode_info = get_mode_info()
+                return JSONResponse(mode_info)
 
             # Create the SSE Starlette application
             # message_path: POST endpoint for client messages
             # sse_path: GET endpoint for SSE event stream
-            app = create_sse_app(
+            sse_app = create_sse_app(
                 self.server,
                 message_path="/messages/",
                 sse_path="/sse"
             )
 
+            # Create combined app with SSE and observability endpoints
+            app = Starlette(
+                routes=[
+                    Route("/health", health_check, methods=["GET"]),
+                    Route("/stats", stats_endpoint, methods=["GET"]),
+                    Route("/metrics", metrics_endpoint, methods=["GET"]),
+                    Route("/safety", safety_mode_endpoint, methods=["GET"]),
+                    Mount("/", app=sse_app),  # Mount SSE app at root
+                ]
+            )
+
             logger.info(f"SSE endpoints: GET /sse (events), POST /messages/ (messages)")
+            logger.info(f"Observability endpoints: GET /health, /stats, /metrics, /safety")
 
             # Run with uvicorn
             config = uvicorn.Config(app, host=host, port=port, log_level="info")
@@ -471,11 +666,33 @@ class MCPServer:
             """Health check endpoint."""
             return JSONResponse({"status": "healthy", "server": self.name})
 
+        async def stats_endpoint(request):
+            """Return runtime statistics."""
+            stats = self._stats.get_stats()
+            return JSONResponse(stats)
+
+        async def metrics_endpoint(request):
+            """Return Prometheus-format metrics."""
+            from starlette.responses import PlainTextResponse
+            if is_prometheus_available():
+                metrics_text = get_metrics()
+                return PlainTextResponse(metrics_text, media_type="text/plain; version=0.0.4; charset=utf-8")
+            else:
+                return PlainTextResponse("# Prometheus metrics not available\n", media_type="text/plain")
+
+        async def safety_mode_endpoint(request):
+            """Return current safety mode information."""
+            mode_info = get_mode_info()
+            return JSONResponse(mode_info)
+
         app = Starlette(
             routes=[
                 Route("/", handle_mcp_request, methods=["POST"]),
                 Route("/mcp", handle_mcp_request, methods=["POST"]),
                 Route("/health", health_check, methods=["GET"]),
+                Route("/stats", stats_endpoint, methods=["GET"]),
+                Route("/metrics", metrics_endpoint, methods=["GET"]),
+                Route("/safety", safety_mode_endpoint, methods=["GET"]),
             ]
         )
 
@@ -508,10 +725,31 @@ if __name__ == "__main__":
         default="0.0.0.0",
         help="Host to bind to for SSE/HTTP transport. Default: 0.0.0.0.",
     )
+    parser.add_argument(
+        "--config",
+        type=str,
+        default=None,
+        help="Path to TOML configuration file.",
+    )
+    parser.add_argument(
+        "--read-only",
+        action="store_true",
+        help="Enable read-only mode (block all write operations).",
+    )
+    parser.add_argument(
+        "--disable-destructive",
+        action="store_true",
+        help="Disable destructive operations (allow create/update, block delete).",
+    )
     args = parser.parse_args()
 
     server_name = "kubectl_mcp_server"
-    mcp_server = MCPServer(name=server_name)
+    mcp_server = MCPServer(
+        name=server_name,
+        read_only=args.read_only,
+        disable_destructive=args.disable_destructive,
+        config_file=args.config,
+    )
 
     # Handle signals gracefully with immediate exit
     def signal_handler(sig, frame):

kubectl_mcp_tool/observability/__init__.py

@@ -0,0 +1,59 @@
+"""
+Observability module for kubectl-mcp-server.
+
+Provides:
+- StatsCollector: Runtime statistics and metrics collection
+- Prometheus metrics: Standard Prometheus format metrics
+- OpenTelemetry tracing: Distributed tracing with OTLP export
+
+Usage:
+    # Stats collection
+    from kubectl_mcp_tool.observability import get_stats_collector
+    stats = get_stats_collector()
+    stats.record_tool_call("get_pods", success=True, duration=0.5)
+
+    # Prometheus metrics
+    from kubectl_mcp_tool.observability import get_metrics
+    metrics_text = get_metrics()
+
+    # Tracing
+    from kubectl_mcp_tool.observability import init_tracing, traced_tool_call
+    init_tracing()
+    with traced_tool_call("get_pods") as span:
+        # execute tool
+        pass
+"""
+
+from .stats import StatsCollector, get_stats_collector
+from .metrics import (
+    get_metrics,
+    record_tool_call_metric,
+    record_tool_error_metric,
+    record_tool_duration_metric,
+    is_prometheus_available,
+)
+from .tracing import (
+    init_tracing,
+    traced_tool_call,
+    get_tracer,
+    is_tracing_available,
+    shutdown_tracing,
+)
+
+__all__ = [
+    # Stats
+    "StatsCollector",
+    "get_stats_collector",
+    # Metrics
+    "get_metrics",
+    "record_tool_call_metric",
+    "record_tool_error_metric",
+    "record_tool_duration_metric",
+    "is_prometheus_available",
+    # Tracing
+    "init_tracing",
+    "traced_tool_call",
+    "get_tracer",
+    "is_tracing_available",
+    "shutdown_tracing",
+]