The mcp-kubernetes-server is a Model Context Protocol (MCP) server that enables AI assistants to interact with Kubernetes clusters. It serves as a bridge between AI tools (like Claude, Cursor, and GitHub Copilot) and Kubernetes, translating natural language requests into Kubernetes operations and returning the results in a format the AI tools can understand.
Add explicit JSON Schema input definitions for all 22 tools currently missing schemas (k8s_expose, k8s_run, k8s_set_resources, k8s_set_image, k8s_set_env, k8s_rollout_undo, k8s_rollout_restart, k8s_rollout_pause, k8s_rollout_resume, k8s_scale, k8s_autoscale, k8s_cordon, k8s_uncordon, k8s_drain, k8s_taint, k8s_untaint, k8s_exec_command, k8s_describe, k8s_patch, k8s_label, k8s_annotate, k8s_delete). Use the pattern from k8s_logs and k8s_port_forward as templates.
Expand descriptions from 20-40 chars to 50-150 chars that include: (1) What the tool does, (2) When to use it vs similar tools, (3) Key parameters required, (4) What structure is returned. Example for k8s_expose: 'Expose a Kubernetes resource (Deployment, Service, etc.) by creating a new Service that routes traffic to it. Specify the resource type and name. Returns the created Service details including cluster IP and port mappings.'
Add enum constraints for all multi-value parameters: sort_by in k8s_top_nodes should declare enum: ['cpu', 'memory']; verb in k8s_auth_can_i should declare enum: ['get', 'list', 'create', 'update', 'delete', 'patch']; field_selector in k8s_events should document common patterns like 'involvedObject.kind=Pod'.
Document output schemas for all 12 read tools (k8s_apis, k8s_crds, k8s_get, k8s_rollout_status, k8s_rollout_history, k8s_top_nodes, k8s_top_pods, k8s_describe, k8s_logs, k8s_events, k8s_auth_can_i, k8s_auth_whoami). Specify: (1) Data type of response (object, array, string), (2) Key fields returned with types, (3) Pagination info if applicable, (4) Example structure. This enables LLMs to plan downstream tool calls.
21 tools have descriptions under 40 characters with minimal actionable context. Examples: 'Expose a Kubernetes resource' (29 chars), 'Run a container in Kubernetes' (30 chars), 'Patch a Kubernetes resource' (27 chars), 'Scale a Kubernetes resource' (26 chars). These do not tell an LLM WHEN to use the tool vs similar tools, WHAT parameters are required, or WHAT the output structure is.
kubectl and helm tools accept a free-form 'command' string with no validation, enum constraints, or input sanitization. Descriptions do not warn about injection risks or operational danger. An LLM could be tricked into running 'kubectl delete nodes --all' or 'helm delete --purge *'. These are dangerously under-specified and lack the error handling to guide recovery.
No tools include enums for constrained parameters (e.g., sort_by in k8s_top_nodes accepts 'cpu' or 'memory' but no enum constraint declared). Per pattern guidance, free-form strings invite hallucinated values, enums are self-documenting and prevent invalid input.
No tool includes output schema documentation. Descriptions state WHAT the tool does but not WHAT fields the agent should expect in the response. This forces LLMs to call tools blind and guess what data structure they'll receive, inviting misinterpretation and wasted follow-up calls.
No error handling guidance or recovery instructions visible in any tool descriptions. Per pattern guidance, error responses must tell LLMs what to do next. The source code does not show try-catch blocks or error messages with actionable remediation. LLMs will hit errors blind with no recovery path.
Write and destructive operations (k8s_create, k8s_delete, k8s_apply, kubectl, helm) lack dry-run or confirmation steps. Agents make mistakes, these operations could cause data loss or service disruption without an explicit confirm-before-execute pattern.
Multiple tools with overlapping functionality but no clear distinctions: k8s_create vs k8s_apply (both apply YAML), k8s_get vs k8s_describe (both read resources), k8s_logs vs k8s_events (both retrieve time-series data). Descriptions do not explain WHEN to choose one over the other, forcing LLM reasoning cycles and potential wrong tool selection.
Parameters use generic names without type suffixes (e.g., 'namespace', 'resource', 'name' without clarifying if they accept names, IDs, or patterns). Per naming rubric, parameters should be suffixed with type (namespace_name, resource_type) to avoid LLM confusion about what format to pass.
Refactor kubectl and helm tools to accept structured command objects instead of free-form strings. For kubectl: require {action: enum, resource_type: string, name?: string, namespace?: string, ...}. For helm: require {action: enum, chart: string, release_name: string, ...}. Add validation logic to reject dangerous operations and sanitize inputs against injection.
Split overlapping tools: merge k8s_create and k8s_apply into a single k8s_apply_yaml tool with a boolean 'create_if_missing' parameter. This eliminates user confusion and simplifies the tool registry.
Add error handling guidance to write/delete tools: 'If namespace does not exist, the tool will return "Namespace not found. Available namespaces: [list]". Call k8s_get resource=namespaces to explore.' This guides LLM recovery without forcing extra calls.
Implement dry-run support for k8s_create, k8s_apply, k8s_delete by adding a 'dry_run: boolean' parameter. Destructive operations should default dry_run=true and require explicit override, preventing accidental data loss.
Add parameter type suffixes: change 'namespace' to 'namespace_name', 'resource' to 'resource_type', 'name' to 'resource_name' to clarify format expectations and reduce LLM hallucination.
Document parameter constraints in descriptions: e.g., 'tail must be a positive integer (1-10000)', 'since must be a duration string (5s, 2m, 3h) or ISO 8601 timestamp', 'selector must be a valid label selector (key=value,key2!=value2)'. These constraints prevent invalid LLM input and self-correct on validation failure.