Static source inference · medium confidence · evidence: Streamable HTTP
Current-spec patterns detected
Summary
This Kubernetes MCP server exhibits significant gaps in definition quality. While 7 tools are defined with names and basic input schemas, descriptions lack LLM-optimized depth, parameter documentation is sparse, output schemas are not documented, and error handling guidance is absent. The tool set is well-organized around Kubernetes operations (list, get, create, delete, logs, search_logs, export_logs), but the definitions fall short of production-grade standards. Tool names follow the verb_noun pattern (good), but descriptions are terse (avg ~50 chars vs. 194 char baseline). Most parameters lack descriptions, and output structures are entirely undocumented. The server would benefit from richer descriptions, comprehensive parameter documentation, explicit output schema definitions, and recovery-oriented error messages.
Tools (7)
createwrite50/100
Create a new Kubernetes resource
deletedestructive50/100
Delete a Kubernetes resource
export_logsread onlysource verified65/100
Export logs from a Kubernetes pod in specified format
getread only50/100
Get a specific Kubernetes resource by name
listread only50/100
List resources of a specific type
logsread only50/100
Retrieve logs from a Kubernetes pod
search_logsread only50/100
Search logs from a Kubernetes pod using pattern matching
Tool descriptions are terse (20-50 chars) and lack WHEN/HOW/WHY context. LLMs cannot distinguish 'list' from 'get' or understand when to call search_logs vs logs without richer descriptions. Baseline: 194 chars.
Parameters 'resource', 'namespace', 'container', 'pattern', 'level', 'since', 'tail' lack descriptions entirely or have minimal guidance. Parameter descriptions should explain constraints (e.g., 'Optional time duration (e.g., 5m) or RFC3339 timestamp' is a format hint, not a description of the parameter's semantics).
Output schemas are entirely undocumented. Agents cannot plan downstream calls or extract data without knowing what fields are returned. No evidence of pagination, result limits, or per-item structure definitions.
Recommendations
Expand tool descriptions to 80-200 chars, following pattern: WHAT (verb + object), WHEN (vs similar tools), RESULT (what to expect). Example for 'list': 'List all Kubernetes resources of a type in a namespace. Use this to discover available pods, services, deployments. Returns resource names and basic metadata. For details on a single resource, use get.'
Add descriptions to ALL parameters. For 'resource', explain: 'Kubernetes resource kind, lowercase plural (pods, services, deployments, replicasets, statefulsets, daemonsets, jobs, cronjobs, configmaps, secrets, etc.)'. For 'namespace', explain: 'Optional Kubernetes namespace to filter results. Defaults to the configured namespace or all namespaces if not specified.'
Document output schemas for each tool. Example for 'list': 'Returns array of objects with fields: {name (string), kind (string), namespace (string), created_at (ISO8601), status (string)}'. For 'get': 'Returns full resource spec as YAML or JSON with fields: {metadata {...}, spec {...}, status {...}}'.
Add enum constraints where applicable. For 'level' in search_logs/export_logs, define: 'One of: debug, info, warn, error, fatal' as an enum, not free text.
For 'create', document the 'data' parameter: 'Kubernetes resource spec as JSON object. Must include apiVersion, kind, metadata.name, metadata.namespace (or omit for cluster-scoped resources), and spec. Example structure provided in nested schema definition.' Add a nested schema showing required/optional fields.
Implement per-tool error responses with recovery guidance. Examples: 'Pod not found. Available pods: nginx-1, nginx-2, nginx-3. Did you mean one of these?' and 'Create failed: invalid field spec.replicas (must be >= 1). Please correct and retry.'
'data' parameter in create tool accepts a raw JSON object with no documentation of expected schema, required fields, or validation rules. Agents will struggle to compose valid Kubernetes resource specs without explicit guidance.
No error handling guidance. Responses from handler.go do not document error classification, recovery steps, or actionable messages. A failed create/delete returns generic errors instead of telling agents whether to retry, ask for help, or abort.
Destructive operations (create, delete) lack confirmation or dry-run patterns. No mechanism for agents to preview changes before applying them, risking accidental resource modifications.
Log retrieval tools (logs, search_logs, export_logs) lack documented result limits or pagination. 'tail' parameter exists but no guidance on default/max/behavior when absent. Unbounded log streaming could exhaust context or timeout.
No documentation of permission checks, audit logging, or security boundaries. Tools can list/get/delete/create resources but no evidence of RBAC enforcement or activity logging, critical for compliance.
listgetcreatedelete
Add dry-run parameters to create/delete tools: 'dry_run' (boolean, optional) allows agents to preview changes without applying them. Update descriptions: 'If dry_run=true, show what would change without making changes. If false (default), apply changes.'
Document result limits and pagination for logs tools. Add guidance: 'Default tail=100 lines. Max tail=10000. For logs >10K lines, use since to narrow the time range. Returns array of log entries with timestamps; total count available for pagination.'
Add permission/scope documentation to tool descriptions. Example: 'Requires Kubernetes verb=get on resources of the specified kind. If the calling user lacks permission, returns 403 Forbidden with the required scope.'
Add audit trail support in descriptions or via a separate logging section: 'All mutations (create/delete) are logged with caller identity, timestamp, resource, and action for compliance auditing.'
For search_logs, clarify regex syntax: 'Pattern is a Go regular expression (golang/regexp syntax). Special chars: . * + ? [ ] ( ) { } ^ $ |. Escape special chars with backslash.'
For export_logs, enumerate format options and their use cases: 'json (structured, suitable for parsing), csv (spreadsheet import), ndjson (newline-delimited JSON, streaming), plaintext (human-readable, includes timestamps and container context), text (alias for plaintext).'
Add minimum/maximum constraints to numeric parameters. Example: 'tail: number of lines, 1-10000 (default 100)'. For namespace queries, document: 'If namespace is empty/omitted, returns resources across all namespaces or defaults to configured namespace depending on RBAC scope.'
Document how 'since' parameter works: 'Can be a duration (5m, 10h) relative to now, or RFC3339 timestamp (2024-01-15T10:30:00Z). Durations are converted to absolute timestamps server-side. If omitted, defaults to last 1 hour or pod creation time.'
Add composition notes to relate tools: 'Use list to discover resources, then get for details, search_logs to find issues in logs, export_logs to save logs for analysis. For resource creation, prepare spec in JSON and call create with data parameter.'
Validate the 'resource' parameter against known Kubernetes kinds server-side and return clear errors: 'Unknown resource type: pod-s. Did you mean: pods? Known types: pods, services, deployments, replicasets, statefulsets, daemonsets, jobs, cronjobs, pvc, pv, configmaps, secrets, nodes, ns'.