Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
The server implements 8 tools across kubectl, helm, istioctl, and argocd CLIs. All tools are registered with names and descriptions visible in src/k8s_mcp_server/server.py. However, critical quality gaps emerge: (1) Parameter descriptions are minimal or absent, 'command' parameters lack format guidance, timeout lacks range constraints; (2) Output schemas are not documented, the tools execute shell commands but do not specify what structure they return (JSON, plaintext, error format); (3) Error handling is implicit, no evidence of recovery guidance or actionable error messages; (4) No input validation hints despite dangerous shell injection risk; (5) Parameter names are generic ('command') rather than specific verb-noun style ('kubectl_command', 'helm_command'); (6) Descriptions do not clarify state-changing implications (execute_* tools are WRITE but descriptions don't highlight irreversibility or dry-run support); (7) No pagination guidance for tools that likely return large outputs (e.g., kubectl get pods across namespaces). The tool naming follows a weak verb_noun pattern (execute_X, describe_X) but lacks distinction clarity. Average across 8 tools: naming 55/100, descriptions 45/100, schema 15/100 (output undocumented), error handling 20/100.
Tools (8)
describe_argocdread onlysource verified48/100
Get documentation and help text for ArgoCD commands.
describe_helmread onlysource verified48/100
Get documentation and help text for Helm commands.
describe_istioctlread onlysource verified48/100
Get documentation and help text for Istio commands.
describe_kubectlread onlysource verified48/100
Get documentation and help text for kubectl commands.
execute_argocdwritesource verified38/100
Execute argocd commands to manage GitOps deployments.
execute_helmwritesource verified38/100
Execute helm commands to manage Kubernetes packages.
execute_istioctlwritesource verified38/100
Execute istioctl commands to manage the Istio service mesh.
Output schemas are not documented. All 8 tools execute CLI commands but do not specify the structure of their responses (JSON vs plaintext, field names, pagination format, error format). LLMs cannot plan downstream tool calls or extract relevant fields without knowing what to expect.
Parameter descriptions are minimal and lack actionable constraints. The 'command' parameter across all tools has a generic description (e.g., 'The kubectl command to execute') but provides no format guidance, forbidden values, or examples of valid vs invalid syntax. The 'timeout' parameter lacks min/max bounds, LLMs could pass 0, negative, or absurdly large values.
Document the output schema for every tool. Specify: (1) For describe_* tools, the format of help text (plaintext block, JSON structure); max length or truncation strategy; whether structured field extraction is possible. (2) For execute_* tools, the format of command output (raw shell stdout/stderr, JSON, YAML if applicable); fields returned (exit_code, stdout, stderr, execution_time); pagination or result limits for commands like 'kubectl get pods' across all namespaces.
Add detailed parameter descriptions with format constraints. For 'command', specify: (1) Allowed subcommands (e.g., 'get', 'create', 'delete' for kubectl; restrict to read-only for describe_* tools). (2) Forbidden patterns or dangerous flags (e.g., '--kubeconfig=/etc/passwd', 'rm -rf'). (3) Example valid vs invalid values. For 'timeout', specify: min=1, max=300 (or appropriate bounds); behavior on timeout (returns partial output or hard error).
Implement and document input validation. At minimum: (1) Reject commands containing shell metacharacters (;, |, &, >, <, $()) unless explicitly escaped. (2) Blacklist dangerous kubectl flags (--context, --kubeconfig with non-standard paths). (3) Return clear validation errors (e.g., 'Invalid command: contains pipe character. Use separate tool calls instead.').
Clarify state-changing implications in execute_* descriptions. Add: (1) 'WARNING: This tool modifies the cluster. Commands like create, delete, apply, patch are irreversible. Use --dry-run flag to preview changes before executing.' (2) Consider adding a 'dry_run' parameter or guidance to always prefix with 'kubectl apply --dry-run=client' for plan tools.
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Score history
Overall score trend
↑ 6 points across a rubric change (v1 → v2)
44/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
F
44
<=2025-11-25
v2
2026-03-09
F
38
-
v1
write
source verified
38/100
Execute kubectl commands against a Kubernetes cluster.
No input validation or sanitization guidance documented. These tools accept arbitrary shell commands as input, a critical injection vector. No documentation of what validation happens server-side (e.g., 'command' filtered against dangerous subcommands like 'rm', dangerous flags like '--kubeconfig=/etc/passwd'), forcing LLMs to assume arbitrary commands are safe.
execute_* tools modify state (create deployments, delete resources, apply manifests) but descriptions do not clearly indicate irreversibility or lack confirmation/dry-run support. An LLM invoking 'execute_kubectl create deployment' cannot distinguish whether this is idempotent, retryable, or destructive without reading implementation code.
No error handling guidance. Tools do not document what happens on failure (e.g., 'pod not found', 'permission denied', 'timeout exceeded') or how to recover. Responses likely return raw shell stderr, which an LLM cannot parse into actionable remediation steps.
Parameter names are generic ('command') rather than type-suffixed. Best practice is 'kubectl_command' or 'kubectl_args' to disambiguate across similar tools and hint at the format. Describe_kubectl and execute_kubectl both take 'command', the LLM cannot infer whether describe expects 'get pods' vs 'pod get'.
Timeout parameter provided but lacks minimum and maximum constraints. LLMs could pass timeout=0 (immediate), timeout=-10 (nonsensical), or timeout=999999999 (freeze). No guidance on default timeout or what happens if exceeded.
Describe tools (describe_kubectl, describe_helm, etc.) may return large help text or documentation. No pagination, truncation, or result limit guidance documented. Output could easily exceed 100KB, bloating the LLM context.
Design structured error responses. Instead of raw shell stderr, return: {"status": "error", "error_type": "not_found" | "permission_denied" | "timeout" | "invalid_command", "message": "<actionable hint>", "recovery": "<next step LLM should take>"}. Example: {"status": "error", "error_type": "not_found", "message": "Pod 'app-xyz' not found in namespace 'default'", "recovery": "Try 'kubectl get pods --all-namespaces' to list available pods and check the correct namespace."}
Add per-tool discovery and guidance. Enhance describe_* descriptions: 'Call this first to understand the syntax of kubectl/helm/istioctl/argocd commands before using execute_* tools. Useful for learning available subcommands and flags.' Consider adding a separate 'get_available_<tool>_commands' tool that returns a structured list of subcommands (get, create, delete, etc.) rather than unstructured help text.
Implement result pagination/truncation for describe_* tools. Document: 'Help output is capped at 50KB. For full documentation, consult the official CLI help (e.g., 'man kubectl') or online docs. If a specific subcommand's help is truncated, call execute_<tool> with '--help' flag for complete details.'
Consider splitting execute_kubectl into read-only variants (execute_kubectl_read, execute_kubectl_dry_run) and write variants (execute_kubectl_write) to help LLMs reason about safety and reversibility.
Add example usage in descriptions to guide LLM invocation. E.g., 'describe_kubectl: Call with command="get pods" to learn how to list pods, or command="create deployment" to see deployment creation syntax.' Include 1 - 2 minimal examples per tool.
Document permission and authentication requirements. Add: 'Requires valid kubeconfig and RBAC permissions for the target cluster. If 'permission denied' errors occur, verify your cluster context and role.'
Implement server-side logging of all tool calls (sanitized, without credentials) and document in error responses how to check logs if a command fails unexpectedly.