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

kubectl_mcp_tool/prompts/custom.py

@@ -0,0 +1,298 @@
+"""
+Custom prompt loading and rendering system for kubectl-mcp-server.
+
+Supports user-defined workflow prompts via TOML configuration file with
+Mustache-style template syntax ({{variable}}) and conditional sections.
+"""
+
+import re
+import logging
+from typing import List, Dict, Any, Optional
+from dataclasses import dataclass, field
+
+logger = logging.getLogger("mcp-server")
+
+
+@dataclass
+class PromptArgument:
+    """Definition of a prompt argument."""
+    name: str
+    description: str = ""
+    required: bool = False
+    default: str = ""
+
+
+@dataclass
+class PromptMessage:
+    """A single message in a prompt conversation."""
+    role: str  # "user" or "assistant"
+    content: str
+
+
+@dataclass
+class CustomPrompt:
+    """A custom prompt definition."""
+    name: str
+    description: str
+    title: str = ""
+    arguments: List[PromptArgument] = field(default_factory=list)
+    messages: List[PromptMessage] = field(default_factory=list)
+
+
+def render_prompt(prompt: CustomPrompt, args: Dict[str, str]) -> List[PromptMessage]:
+    """
+    Render prompt messages with argument substitution using {{arg_name}} syntax.
+
+    Supports:
+    - Simple substitution: {{variable}} -> value
+    - Conditional sections: {{#variable}}content{{/variable}} (shown if variable is truthy)
+    - Inverse sections: {{^variable}}content{{/variable}} (shown if variable is falsy)
+
+    Args:
+        prompt: The CustomPrompt to render
+        args: Dictionary of argument names to values
+
+    Returns:
+        List of PromptMessage with rendered content
+    """
+    rendered = []
+    for msg in prompt.messages:
+        content = msg.content
+
+        # Process conditional sections ({{#var}}...{{/var}})
+        # These are shown only if the variable exists and is truthy
+        def process_conditional(match):
+            var_name = match.group(1)
+            section_content = match.group(2)
+            var_value = args.get(var_name, "")
+            # Only render section if variable exists and is not empty/false
+            if var_value and var_value.lower() not in ("false", "0", "no"):
+                # Recursively process the section content for variable substitution
+                processed = section_content
+                for key, value in args.items():
+                    processed = processed.replace(f"{{{{{key}}}}}", str(value))
+                return processed
+            return ""
+
+        content = re.sub(
+            r'\{\{#(\w+)\}\}(.*?)\{\{/\1\}\}',
+            process_conditional,
+            content,
+            flags=re.DOTALL
+        )
+
+        # Process inverse sections ({{^var}}...{{/var}})
+        # These are shown only if the variable is missing or falsy
+        def process_inverse(match):
+            var_name = match.group(1)
+            section_content = match.group(2)
+            var_value = args.get(var_name, "")
+            # Only render section if variable is missing or falsy
+            if not var_value or var_value.lower() in ("false", "0", "no"):
+                processed = section_content
+                for key, value in args.items():
+                    processed = processed.replace(f"{{{{{key}}}}}", str(value))
+                return processed
+            return ""
+
+        content = re.sub(
+            r'\{\{\^(\w+)\}\}(.*?)\{\{/\1\}\}',
+            process_inverse,
+            content,
+            flags=re.DOTALL
+        )
+
+        # Simple variable substitution
+        for key, value in args.items():
+            content = content.replace(f"{{{{{key}}}}}", str(value))
+
+        # Remove unsubstituted optional placeholders (simple variables only)
+        content = re.sub(r'\{\{[^#^/][^}]*\}\}', '', content)
+
+        # Clean up any remaining empty lines from removed sections
+        content = re.sub(r'\n\s*\n\s*\n', '\n\n', content)
+
+        rendered.append(PromptMessage(role=msg.role, content=content.strip()))
+
+    return rendered
+
+
+def load_prompts_from_config(config: dict) -> List[CustomPrompt]:
+    """
+    Load prompts from config dict (from TOML).
+
+    Expected config structure:
+    {
+        "prompts": [
+            {
+                "name": "debug-pod",
+                "title": "Debug Pod Issues",
+                "description": "Diagnose pod problems",
+                "arguments": [
+                    {"name": "pod_name", "required": True, "description": "Pod to debug"},
+                    {"name": "namespace", "required": False, "default": "default"}
+                ],
+                "messages": [
+                    {"role": "user", "content": "Debug pod {{pod_name}} in namespace {{namespace}}"}
+                ]
+            }
+        ]
+    }
+
+    Args:
+        config: Dictionary loaded from TOML configuration
+
+    Returns:
+        List of CustomPrompt objects
+    """
+    prompts = []
+
+    prompt_configs = config.get("prompts", [])
+    if not prompt_configs:
+        return prompts
+
+    for prompt_config in prompt_configs:
+        try:
+            # Parse arguments
+            arguments = []
+            for arg_config in prompt_config.get("arguments", []):
+                arg = PromptArgument(
+                    name=arg_config.get("name", ""),
+                    description=arg_config.get("description", ""),
+                    required=arg_config.get("required", False),
+                    default=arg_config.get("default", "")
+                )
+                if arg.name:  # Only add valid arguments
+                    arguments.append(arg)
+
+            # Parse messages
+            messages = []
+            for msg_config in prompt_config.get("messages", []):
+                msg = PromptMessage(
+                    role=msg_config.get("role", "user"),
+                    content=msg_config.get("content", "")
+                )
+                if msg.content:  # Only add non-empty messages
+                    messages.append(msg)
+
+            # Create prompt
+            prompt = CustomPrompt(
+                name=prompt_config.get("name", ""),
+                title=prompt_config.get("title", prompt_config.get("name", "")),
+                description=prompt_config.get("description", ""),
+                arguments=arguments,
+                messages=messages
+            )
+
+            if prompt.name:  # Only add valid prompts
+                prompts.append(prompt)
+                logger.debug(f"Loaded custom prompt: {prompt.name}")
+
+        except Exception as e:
+            logger.warning(f"Failed to parse prompt config: {e}")
+            continue
+
+    return prompts
+
+
+def load_prompts_from_toml_file(file_path: str) -> List[CustomPrompt]:
+    """
+    Load prompts from a TOML file.
+
+    Args:
+        file_path: Path to the TOML configuration file
+
+    Returns:
+        List of CustomPrompt objects
+    """
+    try:
+        import tomllib
+    except ImportError:
+        try:
+            import tomli as tomllib
+        except ImportError:
+            logger.warning("TOML parsing not available. Install tomli for Python < 3.11")
+            return []
+
+    try:
+        with open(file_path, "rb") as f:
+            config = tomllib.load(f)
+        return load_prompts_from_config(config)
+    except FileNotFoundError:
+        logger.debug(f"Custom prompts file not found: {file_path}")
+        return []
+    except Exception as e:
+        logger.warning(f"Failed to load prompts from {file_path}: {e}")
+        return []
+
+
+def validate_prompt_args(prompt: CustomPrompt, args: Dict[str, str]) -> List[str]:
+    """
+    Validate that all required arguments are provided.
+
+    Args:
+        prompt: The CustomPrompt to validate against
+        args: Dictionary of argument names to values
+
+    Returns:
+        List of error messages (empty if valid)
+    """
+    errors = []
+
+    for arg in prompt.arguments:
+        if arg.required and arg.name not in args:
+            errors.append(f"Missing required argument: {arg.name}")
+        elif arg.required and not args.get(arg.name):
+            errors.append(f"Required argument cannot be empty: {arg.name}")
+
+    return errors
+
+
+def apply_defaults(prompt: CustomPrompt, args: Dict[str, str]) -> Dict[str, str]:
+    """
+    Apply default values for missing optional arguments.
+
+    Args:
+        prompt: The CustomPrompt with argument definitions
+        args: Dictionary of argument names to values
+
+    Returns:
+        New dictionary with defaults applied
+    """
+    result = dict(args)
+
+    for arg in prompt.arguments:
+        if arg.name not in result and arg.default:
+            result[arg.name] = arg.default
+
+    return result
+
+
+def get_prompt_schema(prompt: CustomPrompt) -> Dict[str, Any]:
+    """
+    Generate JSON Schema for prompt arguments.
+
+    Args:
+        prompt: The CustomPrompt to generate schema for
+
+    Returns:
+        JSON Schema dictionary
+    """
+    properties = {}
+    required = []
+
+    for arg in prompt.arguments:
+        properties[arg.name] = {
+            "type": "string",
+            "description": arg.description or f"Argument: {arg.name}"
+        }
+        if arg.default:
+            properties[arg.name]["default"] = arg.default
+        if arg.required:
+            required.append(arg.name)
+
+    return {
+        "type": "object",
+        "properties": properties,
+        "required": required
+    }

kubectl_mcp_tool/prompts/prompts.py

@@ -1,14 +1,190 @@
+"""
+MCP prompts registration for kubectl-mcp-server.
+
+This module handles registration of both built-in and custom prompts.
+Custom prompts can be loaded from a TOML configuration file.
+"""
+
 import logging
-from typing import Optional
+import os
+from typing import Optional, Dict, Any
+
+from .custom import (
+    CustomPrompt,
+    PromptMessage,
+    render_prompt,
+    load_prompts_from_toml_file,
+    validate_prompt_args,
+    apply_defaults,
+)
+from .builtin import get_builtin_prompts
 
 logger = logging.getLogger("mcp-server")
 
 
-def register_prompts(server):
-    """Register all MCP prompts for Kubernetes workflows.
+# Default paths for custom prompts configuration
+DEFAULT_CONFIG_PATHS = [
+    os.path.expanduser("~/.kubectl-mcp/prompts.toml"),
+    os.path.expanduser("~/.config/kubectl-mcp/prompts.toml"),
+    "./kubectl-mcp-prompts.toml",
+]
+
+
+def _get_custom_prompts_path() -> Optional[str]:
+    """
+    Get the path to custom prompts configuration file.
+
+    Checks (in order):
+    1. MCP_PROMPTS_FILE environment variable
+    2. Default config paths
+
+    Returns:
+        Path to config file if found, None otherwise
+    """
+    # Check environment variable first
+    env_path = os.environ.get("MCP_PROMPTS_FILE")
+    if env_path and os.path.isfile(env_path):
+        return env_path
+
+    # Check default paths
+    for path in DEFAULT_CONFIG_PATHS:
+        if os.path.isfile(path):
+            return path
+
+    return None
+
+
+def _merge_prompts(builtin: list, custom: list) -> Dict[str, CustomPrompt]:
+    """
+    Merge built-in and custom prompts.
+
+    Custom prompts override built-in prompts with the same name.
+
+    Args:
+        builtin: List of built-in CustomPrompt objects
+        custom: List of custom CustomPrompt objects
+
+    Returns:
+        Dictionary of prompt name -> CustomPrompt
+    """
+    prompts = {}
+
+    # Add built-in prompts first
+    for prompt in builtin:
+        prompts[prompt.name] = prompt
+
+    # Custom prompts override built-in
+    for prompt in custom:
+        if prompt.name in prompts:
+            logger.info(f"Custom prompt '{prompt.name}' overrides built-in prompt")
+        prompts[prompt.name] = prompt
+
+    return prompts
+
+
+def register_prompts(server, config_path: Optional[str] = None):
+    """
+    Register all MCP prompts for Kubernetes workflows.
+
+    Registers:
+    1. Built-in prompts from builtin.py
+    2. Custom prompts from configuration file (if found)
+    3. Original inline prompts for backward compatibility
+
+    Custom prompts can override built-in prompts by using the same name.
+
+    Args:
+        server: FastMCP server instance
+        config_path: Optional path to custom prompts TOML file
+    """
+    # Load built-in prompts
+    builtin_prompts = get_builtin_prompts()
+    logger.debug(f"Loaded {len(builtin_prompts)} built-in prompts")
+
+    # Load custom prompts
+    prompts_file = config_path or _get_custom_prompts_path()
+    custom_prompts = []
+    if prompts_file:
+        custom_prompts = load_prompts_from_toml_file(prompts_file)
+        logger.info(f"Loaded {len(custom_prompts)} custom prompts from {prompts_file}")
+
+    # Merge prompts (custom overrides built-in)
+    all_prompts = _merge_prompts(builtin_prompts, custom_prompts)
+
+    # Register each configurable prompt
+    for prompt in all_prompts.values():
+        _register_custom_prompt(server, prompt)
+
+    logger.debug(f"Registered {len(all_prompts)} configurable prompts")
+
+    # Register original inline prompts for backward compatibility
+    _register_inline_prompts(server)
+
+
+def _register_custom_prompt(server, prompt: CustomPrompt):
+    """
+    Register a single CustomPrompt with the server.
 
     Args:
         server: FastMCP server instance
+        prompt: CustomPrompt to register
+    """
+    # Build the argument schema for FastMCP
+    def create_prompt_handler(p: CustomPrompt):
+        """Create a closure that captures the prompt."""
+        def handler(**kwargs) -> str:
+            # Apply defaults for missing optional arguments
+            args = apply_defaults(p, kwargs)
+
+            # Validate required arguments
+            errors = validate_prompt_args(p, args)
+            if errors:
+                return f"Error: {'; '.join(errors)}"
+
+            # Render the prompt messages
+            rendered = render_prompt(p, args)
+
+            # Return the content (for now, just the first message)
+            # MCP prompts typically return a single string
+            if rendered:
+                return rendered[0].content
+            return f"Prompt '{p.name}' has no messages defined."
+
+        return handler
+
+    # Create the handler
+    handler = create_prompt_handler(prompt)
+
+    # Set function metadata for FastMCP registration
+    handler.__name__ = prompt.name.replace("-", "_")
+    handler.__doc__ = prompt.description or prompt.title
+
+    # Build parameter annotations from arguments
+    params = {}
+    for arg in prompt.arguments:
+        # All prompt arguments are strings with Optional if not required
+        if arg.required:
+            params[arg.name] = str
+        else:
+            params[arg.name] = Optional[str]
+
+    handler.__annotations__ = params
+    handler.__annotations__["return"] = str
+
+    # Register with server
+    try:
+        server.prompt()(handler)
+        logger.debug(f"Registered configurable prompt: {prompt.name}")
+    except Exception as e:
+        logger.warning(f"Failed to register prompt '{prompt.name}': {e}")
+
+
+def _register_inline_prompts(server):
+    """
+    Register original inline prompts for backward compatibility.
+
+    These prompts are kept for users who may be using them directly.
+    They can be overridden by custom prompts with the same name.
     """
 
     @server.prompt()
@@ -605,7 +781,7 @@ Target Replicas: {target_replicas}
 
 ### Step 2: Capacity Planning
 Calculate required resources:
-- Current pod resources × {target_replicas} = Total needed
+- Current pod resources x {target_replicas} = Total needed
 - Check node capacity: `kubectl_top("nodes")`
 - Verify cluster can accommodate new pods
 

kubectl_mcp_tool/safety.py

@@ -0,0 +1,155 @@
+"""
+Safety mode implementation for kubectl-mcp-server.
+
+Provides read-only and disable-destructive modes to prevent accidental cluster mutations.
+"""
+
+from enum import Enum
+from functools import wraps
+from typing import Any, Callable, Dict, Set
+import logging
+
+logger = logging.getLogger("mcp-server")
+
+
+class SafetyMode(Enum):
+    """Safety mode levels for the MCP server."""
+    NORMAL = "normal"
+    READ_ONLY = "read_only"
+    DISABLE_DESTRUCTIVE = "disable_destructive"
+
+
+# Global safety mode state
+_current_mode: SafetyMode = SafetyMode.NORMAL
+
+
+# Operations that modify cluster state (blocked in READ_ONLY mode)
+WRITE_OPERATIONS: Set[str] = {
+    # Pod operations
+    "run_pod", "delete_pod",
+    # Deployment operations
+    "scale_deployment", "restart_deployment", "delete_deployment",
+    "rollback_deployment", "create_deployment", "update_deployment",
+    # StatefulSet operations
+    "scale_statefulset", "restart_statefulset", "delete_statefulset",
+    # DaemonSet operations
+    "restart_daemonset", "delete_daemonset",
+    # Service operations
+    "create_service", "delete_service", "update_service",
+    # ConfigMap/Secret operations
+    "create_configmap", "delete_configmap", "update_configmap",
+    "create_secret", "delete_secret", "update_secret",
+    # Namespace operations
+    "create_namespace", "delete_namespace",
+    # Helm operations
+    "install_helm_chart", "upgrade_helm_chart", "uninstall_helm_chart",
+    "rollback_helm_release",
+    # kubectl operations
+    "apply_manifest", "delete_resource", "patch_resource",
+    "create_resource", "replace_resource",
+    # Context operations
+    "switch_context", "set_namespace_for_context",
+    # Rollout operations
+    "rollout_promote_tool", "rollout_abort_tool", "rollout_retry_tool",
+    "rollout_restart_tool",
+    # KubeVirt operations
+    "kubevirt_vm_start_tool", "kubevirt_vm_stop_tool", "kubevirt_vm_restart_tool",
+    "kubevirt_vm_pause_tool", "kubevirt_vm_unpause_tool", "kubevirt_vm_migrate_tool",
+    # CAPI operations
+    "capi_machinedeployment_scale_tool",
+}
+
+# Operations that are destructive (blocked in DISABLE_DESTRUCTIVE mode)
+DESTRUCTIVE_OPERATIONS: Set[str] = {
+    # Delete operations
+    "delete_pod", "delete_deployment", "delete_statefulset", "delete_daemonset",
+    "delete_service", "delete_configmap", "delete_secret", "delete_namespace",
+    "delete_resource",
+    # Helm uninstall
+    "uninstall_helm_chart",
+    # Rollout abort
+    "rollout_abort_tool",
+    # VM stop
+    "kubevirt_vm_stop_tool",
+}
+
+
+def get_safety_mode() -> SafetyMode:
+    """Get the current safety mode."""
+    return _current_mode
+
+
+def set_safety_mode(mode: SafetyMode) -> None:
+    """Set the safety mode globally."""
+    global _current_mode
+    _current_mode = mode
+    logger.info(f"Safety mode set to: {mode.value}")
+
+
+def is_operation_allowed(operation_name: str) -> tuple[bool, str]:
+    """
+    Check if an operation is allowed under the current safety mode.
+
+    Returns:
+        Tuple of (allowed: bool, reason: str)
+    """
+    mode = get_safety_mode()
+
+    if mode == SafetyMode.NORMAL:
+        return True, ""
+
+    if mode == SafetyMode.READ_ONLY:
+        if operation_name in WRITE_OPERATIONS or operation_name in DESTRUCTIVE_OPERATIONS:
+            return False, f"Operation '{operation_name}' blocked: read-only mode is enabled"
+
+    if mode == SafetyMode.DISABLE_DESTRUCTIVE:
+        if operation_name in DESTRUCTIVE_OPERATIONS:
+            return False, f"Operation '{operation_name}' blocked: destructive operations are disabled"
+
+    return True, ""
+
+
+def check_safety_mode(func: Callable) -> Callable:
+    """
+    Decorator to check safety mode before executing a tool function.
+
+    Usage:
+        @check_safety_mode
+        def delete_pod(...):
+            ...
+    """
+    @wraps(func)
+    def wrapper(*args, **kwargs) -> Dict[str, Any]:
+        operation_name = func.__name__
+        allowed, reason = is_operation_allowed(operation_name)
+
+        if not allowed:
+            logger.warning(f"Blocked operation: {operation_name} (mode: {get_safety_mode().value})")
+            return {
+                "success": False,
+                "error": reason,
+                "blocked_by": get_safety_mode().value,
+                "operation": operation_name
+            }
+
+        return func(*args, **kwargs)
+
+    return wrapper
+
+
+def get_mode_info() -> Dict[str, Any]:
+    """Get information about the current safety mode."""
+    mode = get_safety_mode()
+    return {
+        "mode": mode.value,
+        "description": {
+            SafetyMode.NORMAL: "All operations allowed",
+            SafetyMode.READ_ONLY: "Only read operations allowed (no create/update/delete)",
+            SafetyMode.DISABLE_DESTRUCTIVE: "Create/update allowed, delete operations blocked",
+        }[mode],
+        "blocked_operations": {
+            SafetyMode.NORMAL: [],
+            SafetyMode.READ_ONLY: sorted(WRITE_OPERATIONS | DESTRUCTIVE_OPERATIONS),
+            SafetyMode.DISABLE_DESTRUCTIVE: sorted(DESTRUCTIVE_OPERATIONS),
+        }[mode]
+    }

kubectl_mcp_tool/tools/__init__.py

@@ -11,6 +11,16 @@ from .diagnostics import register_diagnostics_tools
 from .cost import register_cost_tools
 from .browser import register_browser_tools, is_browser_available
 from .ui import register_ui_tools, is_ui_available
+from .gitops import register_gitops_tools
+from .certs import register_certs_tools
+from .policy import register_policy_tools
+from .backup import register_backup_tools
+from .keda import register_keda_tools
+from .cilium import register_cilium_tools
+from .rollouts import register_rollouts_tools
+from .capi import register_capi_tools
+from .kubevirt import register_kubevirt_tools
+from .kiali import register_istio_tools
 
 __all__ = [
     "register_helm_tools",
@@ -28,4 +38,14 @@ __all__ = [
     "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",
 ]