kubectl-mcp-server 1.16.0__py3-none-any.whl → 1.18.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