mcp-server-kubernetes 2.4.0 → 2.4.2

package/README.md

@@ -17,7 +17,6 @@ https://github.com/user-attachments/assets/f25f8f4e-4d04-479b-9ae0-5dac452dd2ed
 
 <a href="https://glama.ai/mcp/servers/w71ieamqrt"><img width="380" height="200" src="https://glama.ai/mcp/servers/w71ieamqrt/badge" /></a>
 
-
 ## Usage with Claude Desktop
 
 ```json
@@ -90,8 +89,19 @@ npx mcp-chat --config "%APPDATA%\Claude\claude_desktop_config.json"
   - Run Helm operations
     - Install, upgrade, and uninstall charts
     - Support for custom values, repositories, and versions
+- [x] Troubleshooting Prompt (`k8s-troubleshoot`)
+  - Guides through a systematic Kubernetes troubleshooting flow for pods based on a keyword and optional namespace.
 - [x] Non-destructive mode for read and create/update-only access to clusters
 
+## Prompts
+
+The MCP Kubernetes server includes specialized prompts to assist with common operations.
+
+### k8s-troubleshoot Prompt
+
+This prompt provides a systematic troubleshooting flow for Kubernetes pods. It accepts a `keyword` to identify relevant pods and an optional `namespace` to narrow the search.
+The prompt's output will guide you through an autonomous troubleshooting flow, providing instructions for identifying issues, collecting evidence, and suggesting remediation steps.
+
 ## Local Development
 
 Make sure that you have [bun installed](https://bun.sh/docs/installation). Clone the repo & install dependencies:

package/dist/index.js

@@ -22,6 +22,7 @@ import { kubectlLogs, kubectlLogsSchema } from "./tools/kubectl-logs.js";
 import { kubectlGeneric, kubectlGenericSchema, } from "./tools/kubectl-generic.js";
 import { kubectlPatch, kubectlPatchSchema } from "./tools/kubectl-patch.js";
 import { kubectlRollout, kubectlRolloutSchema, } from "./tools/kubectl-rollout.js";
+import { registerPromptHandlers } from "./prompts/index.js";
 // Check if non-destructive tools only mode is enabled
 const nonDestructiveTools = process.env.ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS === "true";
 // Define destructive tools (delete and uninstall operations)
@@ -66,11 +67,19 @@ const k8sManager = new KubernetesManager();
 const server = new Server({
     name: serverConfig.name,
     version: serverConfig.version,
-}, serverConfig);
+}, {
+    ...serverConfig,
+    capabilities: {
+        prompts: {},
+        ...serverConfig.capabilities,
+    },
+});
 // Resources handlers
 const resourceHandlers = getResourceHandlers(k8sManager);
 server.setRequestHandler(ListResourcesRequestSchema, resourceHandlers.listResources);
 server.setRequestHandler(ReadResourceRequestSchema, resourceHandlers.readResource);
+// Register prompt handlers
+registerPromptHandlers(server, k8sManager);
 // Tools handlers
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     // Filter out destructive tools if ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS is set to 'true'

package/dist/prompts/index.d.ts

@@ -0,0 +1,3 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { KubernetesManager } from "../types.js";
+export declare function registerPromptHandlers(server: Server, k8sManager: KubernetesManager): void;

package/dist/prompts/index.js

@@ -0,0 +1,108 @@
+import { ListPromptsRequestSchema, GetPromptRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+export function registerPromptHandlers(server, k8sManager) {
+    // Register prompts list handler
+    server.setRequestHandler(ListPromptsRequestSchema, async () => {
+        return {
+            prompts: [
+                {
+                    name: "k8s-troubleshoot",
+                    description: "Troubleshoot Kubernetes Resources.",
+                    arguments: [
+                        {
+                            name: "keyword",
+                            description: "A keyword to search pod/node names.",
+                            required: true,
+                        },
+                        {
+                            name: "namespace",
+                            description: "Optional: Specify a namespace to narrow down the search.",
+                            required: false,
+                            default: "all"
+                        },
+                    ],
+                },
+            ],
+        };
+    });
+    // Register prompt handler
+    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        if (name === "k8s-troubleshoot") {
+            const keyword = args?.keyword;
+            const namespace = args?.namespace;
+            if (!keyword) {
+                throw new Error("Keyword parameter is required for k8s-troubleshoot prompt");
+            }
+            const actualNamespace = namespace || "all";
+            const message = `Troubleshooting for resources (pods, nodes, etc.) containing keyword "${keyword}" in their names within namespace "${actualNamespace}" (or across all namespaces if specified) for this investigation:
+
+**Autonomous Kubernetes Troubleshooting Flow**
+
+0. **Perform Quick Health Checks / Golden Signals Analysis**
+   - Assess latency, errors, and resource utilization. If a clear issue is identified (e.g., node not ready, network partition), streamline or deprioritize subsequent detailed steps.
+
+1. **Identify Resource Type and Scope**
+   - Determine the specific resource type (e.g., Pod, Node, Deployment, Service, Customresourcedefination) by analyzing labels, controller relationships, and initial observations.
+   - If needed we can use kubectl_explain tool to get list of resource type
+   - Note when you need customresourcedefinitions please use kubectl_explain
+
+2. **Assess Current State**
+   - Check resource status (e.g., ready state, desired vs. current replicas for deployments).
+   - Identify any non-running or unhealthy states (e.g., CrashLoopBackOff, NotReady, Pending, Evicted).
+   - Review placement and distribution patterns across nodes.
+
+3. **Analyze Operational History**
+   - Review recent events and warnings related to the resource.
+   - Check rollout history and update strategies for controllers (e.g., Deployments).
+   - Examine recent configuration changes or applied manifests.
+
+4. **Inspect Runtime Behavior**
+   - Collect logs from current and previous instances for errors or anomalies (e.g., container logs for pods, system logs for nodes).
+   - Test intra-cluster networking and DNS resolution.
+   - Verify storage mounts, secret accessibility, and configuration usage.
+
+5. **Evaluate Dependencies**
+   - Validate references to ConfigMaps, Secrets, and other dependent resources.
+   - Check associated service account permissions and RBAC rules.
+   - Confirm initContainers and sidecar containers have completed successfully or are running as expected.
+
+6. **Audit Resource Constraints**
+   - Analyze CPU, memory, and storage usage trends against defined requests and limits.
+   - Check node allocatable resources and capacity.
+   - Review pod disruption budgets and quotas affecting the resource.
+
+7. **Validate Cluster Context & Environment**
+   - Inspect node readiness, taints, and tolerations.
+   - Verify the current Kubernetes context and namespace.
+   - Confirm API server availability and connectivity.
+   - Check Kubernetes version compatibility (if applicable).
+
+8. **Compare Against Patterns**
+   - Benchmark against workload-specific best practices and known healthy configurations.
+   - Verify liveness, readiness, and startup probe configurations.
+   - Audit security context settings and network policies.
+
+---
+
+**Instructions:**
+- For each finding, clearly state the observation, its severity (e.g., \`CRITICAL\`, \`WARNING\`, \`INFO\`), and the evidence (e.g., \`kubectl output\`, error message in POD_NAME, timestamp). Also, print which object they found symptoms, e.g., error message in POD_NAME.
+- If there are more than 4 relevant resources (e.g., pods, nodes), pick up to 3 resources which are exhibiting the most severe or illustrative symptoms.
+- If there's a typo in user input and a closest matching object name exists, consider an auto-correction or suggest the correct name.
+- Summarize the root cause clearly and concisely at the end of the investigation, along with clear, actionable steps for remediation, including specific \`kubectl\` commands or configuration changes required.
+- If there is a node-level issue, thoroughly analyze it and explicitly post the findings.
+- **Keep the output crisp, to the point, professional, direct, and systematic, avoiding verbose descriptions. Focus on actionable insights for engineers.**`;
+            return {
+                messages: [
+                    {
+                        role: "user",
+                        content: {
+                            type: "text",
+                            text: message,
+                        },
+                    },
+                ],
+            };
+        }
+        throw new Error(`Unknown prompt: ${name}`);
+    });
+}

package/dist/tools/kubectl-logs.js

@@ -293,12 +293,42 @@ function handleCommandError(error, resourceDescription) {
             isError: true,
         };
     }
+    // Check for multi-container pod error
+    if (error.message.includes("a container name must be specified")) {
+        // Extract pod name and available containers from error message
+        const podNameMatch = error.message.match(/for pod ([^,]+)/);
+        const containersMatch = error.message.match(/choose one of: \[([^\]]+)\]/);
+        const initContainersMatch = error.message.match(/or one of the init containers: \[([^\]]+)\]/);
+        const podName = podNameMatch ? podNameMatch[1] : 'unknown';
+        const containers = containersMatch ? containersMatch[1].split(' ').map((c) => c.trim()) : [];
+        const initContainers = initContainersMatch ? initContainersMatch[1].split(' ').map((c) => c.trim()) : [];
+        // Generate structured context for the MCP client to make decisions
+        const context = {
+            error: "Multi-container pod requires container specification",
+            status: "multi_container_error",
+            pod_name: podName,
+            available_containers: containers,
+            init_containers: initContainers,
+            suggestion: `Please specify a container name using the 'container' parameter. Available containers: ${containers.join(', ')}${initContainers.length > 0 ? `. Init containers: ${initContainers.join(', ')}` : ''}`
+        };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(context, null, 2),
+                },
+            ],
+            isError: true,
+        };
+    }
     return {
         content: [
             {
                 type: "text",
                 text: JSON.stringify({
                     error: `Failed to get logs for ${resourceDescription}: ${error.message}`,
+                    status: "general_error",
+                    original_error: error.message
                 }, null, 2),
             },
         ],

package/dist/utils/sse.js

@@ -21,7 +21,15 @@ export function startSSEServer(server) {
                 .send("Not found. Must pass valid sessionId as query param.");
         }
     });
-    const port = process.env.PORT || 3000;
-    app.listen(port);
-    console.log(`mcp-kubernetes-server is listening on port ${port}\nUse the following url to connect to the server:\n\http://localhost:${port}/sse`);
+    let port = 3000;
+    try {
+        port = parseInt(process.env.PORT || "3000", 10);
+    }
+    catch (e) {
+        console.error("Invalid PORT environment variable, using default port 3000.");
+    }
+    const host = process.env.HOST || "localhost";
+    app.listen(port, host, () => {
+        console.log(`mcp-kubernetes-server is listening on port ${port}\nUse the following url to connect to the server:\n\http://${host}:${port}/sse`);
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-server-kubernetes",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "description": "MCP server for interacting with Kubernetes clusters via kubectl",
   "license": "MIT",
   "type": "module",