kubectl-mcp-server 1.13.0__py3-none-any.whl → 1.14.0__py3-none-any.whl

kubectl_mcp_tool/cli/errors.py

@@ -0,0 +1,262 @@
+"""Structured error handling for kubectl-mcp-server CLI."""
+
+from dataclasses import dataclass
+from enum import IntEnum
+from typing import List, Optional
+
+
+class ErrorCode(IntEnum):
+    SUCCESS = 0
+    CLIENT_ERROR = 1
+    SERVER_ERROR = 2
+    K8S_ERROR = 3
+    BROWSER_ERROR = 4
+    NETWORK_ERROR = 5
+
+
+@dataclass
+class CliError:
+    code: ErrorCode
+    type: str
+    message: str
+    details: Optional[str] = None
+    suggestion: Optional[str] = None
+
+    def __str__(self) -> str:
+        return format_cli_error(self)
+
+
+def format_cli_error(error: CliError) -> str:
+    lines = [f"Error [{error.type}]: {error.message}"]
+    if error.details:
+        lines.append(f"  Details: {error.details}")
+    if error.suggestion:
+        lines.append(f"  Suggestion: {error.suggestion}")
+    return "\n".join(lines)
+
+
+def tool_not_found_error(name: str, available: Optional[List[str]] = None) -> CliError:
+    available = available or []
+    available_str = ", ".join(available[:5])
+    if len(available) > 5:
+        available_str += f" (+{len(available) - 5} more)"
+
+    return CliError(
+        code=ErrorCode.CLIENT_ERROR,
+        type="TOOL_NOT_FOUND",
+        message=f'Tool "{name}" not found',
+        details=f"Available: {available_str}" if available else None,
+        suggestion="Run 'kubectl-mcp-server tools' to see all available tools"
+    )
+
+
+def tool_execution_error(name: str, cause: str) -> CliError:
+    suggestion = "Check tool arguments match the expected schema"
+
+    if "validation" in cause.lower() or "invalid" in cause.lower():
+        suggestion = f"Run 'kubectl-mcp-server tools {name}' to see the input schema"
+    elif "required" in cause.lower():
+        suggestion = f"Missing required argument. Run 'kubectl-mcp-server tools {name}' for schema"
+    elif "permission" in cause.lower() or "denied" in cause.lower():
+        suggestion = "Permission denied. Check RBAC permissions in your cluster"
+
+    return CliError(
+        code=ErrorCode.SERVER_ERROR,
+        type="TOOL_EXECUTION_FAILED",
+        message=f'Tool "{name}" execution failed',
+        details=cause,
+        suggestion=suggestion
+    )
+
+
+def k8s_connection_error(context: str, cause: str) -> CliError:
+    suggestion = "Check your kubeconfig and ensure the cluster is accessible"
+
+    if "refused" in cause.lower():
+        suggestion = "Connection refused. Is the cluster running? Check 'kubectl cluster-info'"
+    elif "timeout" in cause.lower():
+        suggestion = "Connection timed out. Check network connectivity to the cluster"
+    elif "unauthorized" in cause.lower() or "401" in cause:
+        suggestion = "Authentication failed. Check your credentials with 'kubectl auth whoami'"
+
+    return CliError(
+        code=ErrorCode.K8S_ERROR,
+        type="K8S_CONNECTION_FAILED",
+        message=f'Failed to connect to Kubernetes context "{context}"',
+        details=cause,
+        suggestion=suggestion
+    )
+
+
+def k8s_context_error(context: str, available: Optional[List[str]] = None) -> CliError:
+    available = available or []
+    available_str = ", ".join(available[:5]) if available else "(none)"
+
+    return CliError(
+        code=ErrorCode.K8S_ERROR,
+        type="K8S_CONTEXT_NOT_FOUND",
+        message=f'Kubernetes context "{context}" not found',
+        details=f"Available contexts: {available_str}",
+        suggestion="Run 'kubectl config get-contexts' to list available contexts"
+    )
+
+
+def k8s_resource_error(resource: str, namespace: str, cause: str) -> CliError:
+    return CliError(
+        code=ErrorCode.K8S_ERROR,
+        type="K8S_RESOURCE_ERROR",
+        message=f'Failed to access {resource} in namespace "{namespace}"',
+        details=cause,
+        suggestion="Check if the resource exists and you have permission to access it"
+    )
+
+
+def browser_not_found_error() -> CliError:
+    return CliError(
+        code=ErrorCode.BROWSER_ERROR,
+        type="BROWSER_NOT_FOUND",
+        message="agent-browser CLI not found",
+        details="Browser automation tools require agent-browser to be installed",
+        suggestion="Install with: npm install -g agent-browser && agent-browser install"
+    )
+
+
+def browser_not_enabled_error() -> CliError:
+    return CliError(
+        code=ErrorCode.BROWSER_ERROR,
+        type="BROWSER_NOT_ENABLED",
+        message="Browser tools are not enabled",
+        details="Set MCP_BROWSER_ENABLED=true to enable browser automation",
+        suggestion="Export MCP_BROWSER_ENABLED=true and ensure agent-browser is installed"
+    )
+
+
+def browser_connection_error(cause: str) -> CliError:
+    suggestion = "Check browser configuration and try again"
+
+    if "ECONNREFUSED" in cause:
+        suggestion = "Connection refused. Is the browser running? Try 'agent-browser install'"
+    elif "timeout" in cause.lower():
+        suggestion = "Connection timed out. Try increasing MCP_BROWSER_TIMEOUT"
+    elif "CDP" in cause or "websocket" in cause.lower():
+        suggestion = "CDP connection failed. Check MCP_BROWSER_CDP_URL is correct"
+
+    return CliError(
+        code=ErrorCode.BROWSER_ERROR,
+        type="BROWSER_CONNECTION_FAILED",
+        message="Failed to connect to browser",
+        details=cause,
+        suggestion=suggestion
+    )
+
+
+def browser_timeout_error(timeout: int) -> CliError:
+    return CliError(
+        code=ErrorCode.BROWSER_ERROR,
+        type="BROWSER_TIMEOUT",
+        message=f"Browser command timed out after {timeout}s",
+        details="The command took too long to complete",
+        suggestion="Increase timeout or check if the page is loading correctly"
+    )
+
+
+def invalid_json_error(input_str: str, parse_error: str) -> CliError:
+    truncated = input_str[:100] + "..." if len(input_str) > 100 else input_str
+
+    return CliError(
+        code=ErrorCode.CLIENT_ERROR,
+        type="INVALID_JSON",
+        message="Invalid JSON in arguments",
+        details=f"Parse error: {parse_error}",
+        suggestion=f"Use valid JSON format: '{{\"key\": \"value\"}}'. Input was: {truncated}"
+    )
+
+
+def missing_argument_error(command: str, argument: str) -> CliError:
+    suggestions = {
+        "call": "Use 'kubectl-mcp-server call <tool> '{\"key\": \"value\"}'",
+        "tools": "Use 'kubectl-mcp-server tools <name>' to inspect a tool",
+        "grep": "Use 'kubectl-mcp-server grep \"*pattern*\"' to search tools",
+        "context": "Use 'kubectl-mcp-server context <name>' to switch context",
+    }
+
+    return CliError(
+        code=ErrorCode.CLIENT_ERROR,
+        type="MISSING_ARGUMENT",
+        message=f"Missing required argument: {argument}",
+        details=f"Command '{command}' requires {argument}",
+        suggestion=suggestions.get(command, "Run 'kubectl-mcp-server --help' for usage")
+    )
+
+
+def unknown_subcommand_error(subcommand: str) -> CliError:
+    valid_commands = "serve, tools, resources, prompts, call, grep, info, context, doctor, version, diagnostics"
+
+    suggestions = {
+        "run": "call",
+        "exec": "call",
+        "execute": "call",
+        "invoke": "call",
+        "list": "tools",
+        "ls": "tools",
+        "get": "tools",
+        "show": "info",
+        "describe": "tools",
+        "search": "grep",
+        "find": "grep",
+        "check": "doctor",
+        "status": "info",
+        "start": "serve",
+    }
+
+    suggested = suggestions.get(subcommand.lower())
+    suggestion_text = (
+        f"Did you mean 'kubectl-mcp-server {suggested}'?"
+        if suggested
+        else "Run 'kubectl-mcp-server --help' for available commands"
+    )
+
+    return CliError(
+        code=ErrorCode.CLIENT_ERROR,
+        type="UNKNOWN_SUBCOMMAND",
+        message=f'Unknown subcommand: "{subcommand}"',
+        details=f"Valid commands: {valid_commands}",
+        suggestion=suggestion_text
+    )
+
+
+def config_error(message: str, suggestion: Optional[str] = None) -> CliError:
+    return CliError(
+        code=ErrorCode.CLIENT_ERROR,
+        type="CONFIG_ERROR",
+        message=message,
+        suggestion=suggestion or "Check your configuration and try again"
+    )
+
+
+def dependency_missing_error(dependency: str, install_cmd: Optional[str] = None) -> CliError:
+    return CliError(
+        code=ErrorCode.CLIENT_ERROR,
+        type="DEPENDENCY_MISSING",
+        message=f"Required dependency not found: {dependency}",
+        suggestion=f"Install with: {install_cmd}" if install_cmd else f"Please install {dependency}"
+    )
+
+
+def network_error(cause: str) -> CliError:
+    suggestion = "Check your network connection and try again"
+
+    if "ECONNREFUSED" in cause:
+        suggestion = "Connection refused. Check if the service is running"
+    elif "ETIMEDOUT" in cause or "timeout" in cause.lower():
+        suggestion = "Connection timed out. Check network connectivity"
+    elif "ENOTFOUND" in cause or "DNS" in cause:
+        suggestion = "DNS resolution failed. Check the hostname"
+
+    return CliError(
+        code=ErrorCode.NETWORK_ERROR,
+        type="NETWORK_ERROR",
+        message="Network error occurred",
+        details=cause,
+        suggestion=suggestion
+    )

kubectl_mcp_tool/cli/output.py

@@ -0,0 +1,377 @@
+"""Output formatting utilities for kubectl-mcp-server CLI."""
+
+import json
+import os
+import sys
+from typing import Any, Dict, List, Optional
+
+
+COLORS = {
+    "reset": "\x1b[0m",
+    "bold": "\x1b[1m",
+    "dim": "\x1b[2m",
+    "italic": "\x1b[3m",
+    "underline": "\x1b[4m",
+    # Foreground colors
+    "black": "\x1b[30m",
+    "red": "\x1b[31m",
+    "green": "\x1b[32m",
+    "yellow": "\x1b[33m",
+    "blue": "\x1b[34m",
+    "magenta": "\x1b[35m",
+    "cyan": "\x1b[36m",
+    "white": "\x1b[37m",
+    # Bright colors
+    "bright_black": "\x1b[90m",
+    "bright_red": "\x1b[91m",
+    "bright_green": "\x1b[92m",
+    "bright_yellow": "\x1b[93m",
+    "bright_blue": "\x1b[94m",
+    "bright_magenta": "\x1b[95m",
+    "bright_cyan": "\x1b[96m",
+    "bright_white": "\x1b[97m",
+}
+
+
+def should_colorize() -> bool:
+    if os.environ.get("NO_COLOR"):
+        return False
+    return sys.stdout.isatty()
+
+
+def color(text: str, *codes: str) -> str:
+    if not should_colorize():
+        return text
+    combined = "".join(codes)
+    return f"{combined}{text}{COLORS['reset']}"
+
+
+def bold(text: str) -> str:
+    return color(text, COLORS["bold"])
+
+
+def dim(text: str) -> str:
+    return color(text, COLORS["dim"])
+
+
+def cyan(text: str) -> str:
+    return color(text, COLORS["cyan"])
+
+
+def green(text: str) -> str:
+    return color(text, COLORS["green"])
+
+
+def yellow(text: str) -> str:
+    return color(text, COLORS["yellow"])
+
+
+def red(text: str) -> str:
+    return color(text, COLORS["red"])
+
+
+def blue(text: str) -> str:
+    return color(text, COLORS["blue"])
+
+
+TOOL_CATEGORIES = {
+    "pods": "Pods",
+    "deployments": "Deployments & Workloads",
+    "core": "Core Resources",
+    "cluster": "Cluster Management",
+    "networking": "Networking",
+    "storage": "Storage",
+    "security": "Security & RBAC",
+    "helm": "Helm",
+    "operations": "Operations",
+    "diagnostics": "Diagnostics",
+    "cost": "Cost Optimization",
+    "browser": "Browser Automation",
+    "ui": "UI Dashboards",
+}
+
+
+def format_tools_list(
+    tools: List[Dict[str, Any]],
+    with_descriptions: bool = False,
+    as_json: bool = False
+) -> str:
+    if as_json:
+        return json.dumps(tools, indent=2)
+
+    # Group tools by category
+    categories: Dict[str, List[Dict]] = {}
+    for tool in tools:
+        cat = tool.get("category", "other")
+        cat_display = TOOL_CATEGORIES.get(cat, cat.title())
+        categories.setdefault(cat_display, []).append(tool)
+
+    lines = []
+    for cat, cat_tools in sorted(categories.items()):
+        # Category header
+        header = f"{cat} ({len(cat_tools)})"
+        lines.append(color(header, COLORS["bold"], COLORS["cyan"]))
+
+        # Tools in category
+        for t in sorted(cat_tools, key=lambda x: x.get("name", "")):
+            name = t.get("name", "unknown")
+            if with_descriptions and t.get("description"):
+                desc = t["description"]
+                # Truncate long descriptions
+                if len(desc) > 60:
+                    desc = desc[:57] + "..."
+                lines.append(f"  {green(name)} - {dim(desc)}")
+            else:
+                lines.append(f"  {name}")
+
+        lines.append("")  # Empty line between categories
+
+    return "\n".join(lines).rstrip()
+
+
+def format_tool_schema(tool: Dict[str, Any], as_json: bool = False) -> str:
+    if as_json:
+        return json.dumps(tool, indent=2)
+
+    lines = []
+    name = tool.get("name", "unknown")
+    description = tool.get("description", "")
+    schema = tool.get("inputSchema", tool.get("input_schema", {}))
+
+    # Header
+    lines.append(f"{bold('Tool:')} {green(name)}")
+    if description:
+        lines.append(f"{bold('Description:')} {description}")
+
+    # Parameters
+    properties = schema.get("properties", {})
+    required = schema.get("required", [])
+
+    if properties:
+        lines.append("")
+        lines.append(bold("Parameters:"))
+        for param_name, param_info in properties.items():
+            param_type = param_info.get("type", "any")
+            param_desc = param_info.get("description", "")
+            is_required = param_name in required
+            req_str = yellow("required") if is_required else dim("optional")
+
+            param_line = f"  {cyan(param_name)} ({param_type}, {req_str})"
+            if param_desc:
+                lines.append(f"{param_line}")
+                lines.append(f"    {dim(param_desc)}")
+            else:
+                lines.append(param_line)
+
+    # Full schema
+    lines.append("")
+    lines.append(bold("Input Schema:"))
+    lines.append(json.dumps(schema, indent=2))
+
+    return "\n".join(lines)
+
+
+def format_tools_search(
+    results: List[Dict[str, Any]],
+    pattern: str,
+    with_descriptions: bool = False
+) -> str:
+    if not results:
+        return dim(f"No tools matching '{pattern}'")
+
+    lines = [f"Found {len(results)} tools matching '{pattern}':", ""]
+
+    for tool in results:
+        name = tool.get("name", "unknown")
+        if with_descriptions and tool.get("description"):
+            lines.append(f"{green(name)} - {dim(tool['description'])}")
+        else:
+            lines.append(green(name))
+
+    return "\n".join(lines)
+
+
+def format_resources_list(
+    resources: List[Dict[str, Any]],
+    as_json: bool = False
+) -> str:
+    if as_json:
+        return json.dumps(resources, indent=2)
+
+    lines = [bold(f"Resources ({len(resources)}):"), ""]
+
+    for res in resources:
+        uri = res.get("uri", res.get("name", "unknown"))
+        name = res.get("name", uri)
+        description = res.get("description", "")
+
+        lines.append(f"  {cyan(uri)}")
+        if name != uri:
+            lines.append(f"    Name: {name}")
+        if description:
+            lines.append(f"    {dim(description)}")
+
+    return "\n".join(lines)
+
+
+def format_prompts_list(
+    prompts: List[Dict[str, Any]],
+    as_json: bool = False
+) -> str:
+    if as_json:
+        return json.dumps(prompts, indent=2)
+
+    lines = [bold(f"Prompts ({len(prompts)}):"), ""]
+
+    for prompt in prompts:
+        name = prompt.get("name", "unknown")
+        description = prompt.get("description", "")
+        args = prompt.get("arguments", [])
+
+        lines.append(f"  {green(name)}")
+        if description:
+            lines.append(f"    {dim(description)}")
+        if args:
+            arg_names = [a.get("name", "?") for a in args]
+            lines.append(f"    Arguments: {', '.join(arg_names)}")
+
+    return "\n".join(lines)
+
+
+def format_call_result(result: Any, as_json: bool = False) -> str:
+    if as_json or not sys.stdout.isatty():
+        return json.dumps(result, indent=2, default=str)
+
+    # Try to extract text content from MCP result format
+    if isinstance(result, dict):
+        content = result.get("content", [])
+        if isinstance(content, list):
+            text_parts = []
+            for item in content:
+                if isinstance(item, dict) and item.get("type") == "text":
+                    text_parts.append(item.get("text", ""))
+            if text_parts:
+                return "\n".join(text_parts)
+
+        if result.get("isError"):
+            error_msg = result.get("error", result.get("message", "Unknown error"))
+            return red(f"Error: {error_msg}")
+
+    return json.dumps(result, indent=2, default=str)
+
+
+def format_server_info(
+    version: str,
+    tool_count: int,
+    resource_count: int,
+    prompt_count: int,
+    context: Optional[str] = None,
+    as_json: bool = False
+) -> str:
+    info = {
+        "version": version,
+        "tools": tool_count,
+        "resources": resource_count,
+        "prompts": prompt_count,
+        "k8s_context": context,
+    }
+
+    if as_json:
+        return json.dumps(info, indent=2)
+
+    lines = [
+        bold("kubectl-mcp-server"),
+        "",
+        f"  {cyan('Version:')}     {version}",
+        f"  {cyan('Tools:')}       {tool_count}",
+        f"  {cyan('Resources:')}   {resource_count}",
+        f"  {cyan('Prompts:')}     {prompt_count}",
+    ]
+
+    if context:
+        lines.append(f"  {cyan('K8s Context:')} {context}")
+
+    return "\n".join(lines)
+
+
+def format_context_info(
+    current: str,
+    available: List[str],
+    as_json: bool = False
+) -> str:
+    if as_json:
+        return json.dumps({
+            "current": current,
+            "available": available
+        }, indent=2)
+
+    lines = [
+        f"{bold('Current context:')} {green(current)}",
+        "",
+        bold("Available contexts:"),
+    ]
+
+    for ctx in available:
+        if ctx == current:
+            lines.append(f"  {green('*')} {green(ctx)} (current)")
+        else:
+            lines.append(f"    {ctx}")
+
+    return "\n".join(lines)
+
+
+def format_doctor_results(
+    checks: List[Dict[str, Any]],
+    as_json: bool = False
+) -> str:
+    if as_json:
+        return json.dumps(checks, indent=2)
+
+    lines = [bold("Checking dependencies..."), ""]
+    all_passed = True
+
+    for check in checks:
+        name = check.get("name", "unknown")
+        status = check.get("status", "unknown")
+        details = check.get("details", "")
+        version = check.get("version", "")
+
+        if status == "ok":
+            icon = green("✓")
+            status_text = green("OK")
+        elif status == "warning":
+            icon = yellow("!")
+            status_text = yellow("WARNING")
+            all_passed = False
+        else:
+            icon = red("✗")
+            status_text = red("FAILED")
+            all_passed = False
+
+        line = f"  {icon} {name}: {status_text}"
+        if version:
+            line += f" ({version})"
+        lines.append(line)
+
+        if details and status != "ok":
+            lines.append(f"      {dim(details)}")
+
+    lines.append("")
+    if all_passed:
+        lines.append(green("All checks passed!"))
+    else:
+        lines.append(yellow("Some checks failed. See details above."))
+
+    return "\n".join(lines)
+
+
+def format_error(message: str) -> str:
+    return red(f"Error: {message}")
+
+
+def format_warning(message: str) -> str:
+    return yellow(f"Warning: {message}")
+
+
+def format_success(message: str) -> str:
+    return green(message)