kubectl-mcp-server 1.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Rohit Ghumare
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/README.md

@@ -0,0 +1,557 @@
+# Kubectl MCP Server
+
+A Model Context Protocol (MCP) server for Kubernetes that enables AI assistants like Claude, Cursor, and others to interact with Kubernetes clusters through natural language.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
+[![Kubernetes](https://img.shields.io/badge/kubernetes-%23326ce5.svg?style=flat&logo=kubernetes&logoColor=white)](https://kubernetes.io/)
+[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://github.com/modelcontextprotocol/modelcontextprotocol)
+[![PyPI version](https://badge.fury.io/py/kubectl-mcp-tool.svg)](https://pypi.org/project/kubectl-mcp-tool/)
+[![npm version](https://badge.fury.io/js/kubectl-mcp-server.svg)](https://www.npmjs.com/package/kubectl-mcp-server)
+[![Docker](https://img.shields.io/docker/pulls/rohitghumare64/kubectl-mcp-server.svg)](https://hub.docker.com/r/rohitghumare64/kubectl-mcp-server)
+
+## 🎥 Live Demo - Watch `kubectl-mcp-tool` in Action with Claude!
+![Claude MCP](./docs/claude/claude-mcp.gif)
+
+## 🎥 Live Demo - Watch `kubectl-mcp-tool` in Action with Cursor!
+![Cursor MCP](./docs/cursor/cursor-mcp.gif)
+
+## 🎥 Live Demo - Watch `kubectl-mcp-tool` in Action with Windsurf!
+![Windsurf MCP](./docs/windsurf/windsurf-mcp.gif)
+
+
+## Features
+
+### Core Kubernetes Operations
+- [x] Connect to a Kubernetes cluster
+- [x] List and manage pods, services, deployments, and nodes
+- [x] Create, delete, and describe pods and other resources
+- [x] Get pod logs and Kubernetes events
+- [x] Support for Helm v3 operations (installation, upgrades, uninstallation)
+- [x] kubectl explain and api-resources support
+- [x] Choose namespace for next commands (memory persistence)
+- [x] Port forward to pods
+- [x] Scale deployments and statefulsets
+- [x] Execute commands in containers
+- [x] Manage ConfigMaps and Secrets
+- [x] Rollback deployments to previous versions
+- [x] Ingress and NetworkPolicy management
+- [x] Context switching between clusters
+
+### Natural Language Processing
+- [x] Process natural language queries for kubectl operations
+- [x] Context-aware commands with memory of previous operations
+- [x] Human-friendly explanations of Kubernetes concepts
+- [x] Intelligent command construction from intent
+- [x] Fallback to kubectl when specialized tools aren't available
+- [x] Mock data support for offline/testing scenarios
+- [x] Namespace-aware query handling
+
+### Monitoring
+- [x] Cluster health monitoring
+- [x] Resource utilization tracking
+- [x] Pod status and health checks
+- [x] Event monitoring and alerting
+- [x] Node capacity and allocation analysis
+- [x] Historical performance tracking
+- [x] Resource usage statistics via kubectl top
+- [x] Container readiness and liveness tracking
+
+### Security
+- [x] RBAC validation and verification
+- [x] Security context auditing
+- [x] Secure connections to Kubernetes API
+- [x] Credentials management
+- [x] Network policy assessment
+- [x] Container security scanning
+- [x] Security best practices enforcement
+- [x] Role and ClusterRole management
+- [x] ServiceAccount creation and binding
+- [x] PodSecurityPolicy analysis
+- [x] RBAC permissions auditing
+- [x] Security context validation
+
+### Diagnostics
+- [x] Cluster diagnostics and troubleshooting
+- [x] Configuration validation
+- [x] Error analysis and recovery suggestions
+- [x] Connection status monitoring
+- [x] Log analysis and pattern detection
+- [x] Resource constraint identification
+- [x] Pod health check diagnostics
+- [x] Common error pattern identification
+- [x] Resource validation for misconfigurations
+- [x] Detailed liveness and readiness probe validation
+
+### Advanced Features
+- [x] Multiple transport protocols support (stdio, SSE, HTTP/streamable-http)
+- [x] Integration with multiple AI assistants (Claude Desktop, Claude Code, Cursor, Windsurf)
+- [x] Multi-cluster support with context switching
+- [x] Extensible tool framework
+- [x] Custom resource definition support
+- [x] Cross-namespace operations
+- [x] Batch operations on multiple resources
+- [x] Intelligent resource relationship mapping
+- [x] Error explanation with recovery suggestions
+- [x] Volume management and identification
+- [x] Command injection protection with input validation
+- [x] Non-destructive mode (`--non-destructive` flag)
+- [x] Secrets masking in output
+- [x] Helm template rendering and application
+- [x] Node management (cordon, drain, uncordon)
+- [x] Pod cleanup for failed/evicted pods
+- [x] Guided troubleshooting prompts
+
+## Architecture
+
+### Model Context Protocol (MCP) Integration
+
+The Kubectl MCP Tool implements the [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol/spec), enabling AI assistants to interact with Kubernetes clusters through a standardized interface. The architecture consists of:
+
+1. **MCP Server**: A compliant server that handles requests from MCP clients (AI assistants)
+2. **Tools Registry**: Registers Kubernetes operations as MCP tools with schemas
+3. **Transport Layer**: Supports stdio, SSE, and HTTP transport methods
+4. **Core Operations**: Translates tool calls to Kubernetes API operations
+5. **Response Formatter**: Converts Kubernetes responses to MCP-compliant responses
+
+### Request Flow
+
+![Request Flow](./image.png)
+
+### Dual Mode Operation
+
+The tool operates in two modes:
+
+1. **CLI Mode**: Direct command-line interface for executing Kubernetes operations
+2. **Server Mode**: Running as an MCP server to handle requests from AI assistants
+
+## Installation
+
+For detailed installation instructions, please see the [Installation Guide](./docs/INSTALLATION.md).
+
+### npm / npx (Recommended for Node.js users)
+
+The easiest way to run kubectl-mcp-server is via npx:
+
+```bash
+# Run directly without installation
+npx kubectl-mcp-server
+
+# Or install globally
+npm install -g kubectl-mcp-server
+kubectl-mcp-server
+```
+
+The npm package is available at: [https://www.npmjs.com/package/kubectl-mcp-server](https://www.npmjs.com/package/kubectl-mcp-server)
+
+> **Note:** The npm package requires Python 3.9+ to be installed. It will automatically install the Python dependencies on first run.
+
+### pip (Python)
+
+You can install kubectl-mcp-tool directly from PyPI:
+
+```bash
+pip install kubectl-mcp-tool
+```
+
+For a specific version:
+
+```bash
+pip install kubectl-mcp-tool==1.4.0
+```
+
+The package is available on PyPI: [https://pypi.org/project/kubectl-mcp-tool/](https://pypi.org/project/kubectl-mcp-tool/)
+
+### Prerequisites
+
+- Python 3.9+
+- kubectl CLI installed and configured
+- Access to a Kubernetes cluster
+- pip (Python package manager)
+
+### Global Installation
+
+```bash
+# Install latest version from PyPI
+pip install kubectl-mcp-tool
+
+# Or install development version from GitHub
+pip install git+https://github.com/rohitg00/kubectl-mcp-server.git
+```
+
+### Local Development Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/rohitg00/kubectl-mcp-server.git
+cd kubectl-mcp-server
+
+# Install in development mode
+pip install -e .
+```
+
+### Verifying Installation
+
+After installation, verify the tool is working correctly:
+
+```bash
+kubectl-mcp --help
+```
+
+Note: This tool is designed to work as an MCP server that AI assistants connect to, not as a direct kubectl replacement. The primary command available is `kubectl-mcp serve` which starts the MCP server.
+
+## Docker Image
+
+Pre-built images are available on Docker Hub:
+
+```bash
+# Pull the latest image
+docker pull rohitghumare64/kubectl-mcp-server:latest
+
+# Or use the official MCP catalog image
+docker pull mcp/kubectl-mcp-server:latest
+```
+
+### Docker MCP Toolkit Integration
+
+This image is compatible with [Docker MCP Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/). The Toolkit provides a streamlined way to run MCP servers with Claude, Cursor, and other AI assistants.
+
+**Quick Setup with Docker MCP Toolkit:**
+
+1. **Add the server to Docker MCP Toolkit:**
+   ```bash
+   docker mcp server add kubectl-mcp-server mcp/kubectl-mcp-server:latest
+   ```
+
+2. **Configure kubeconfig access:**
+   ```bash
+   docker mcp server configure kubectl-mcp-server --volume "$HOME/.kube:/root/.kube:ro"
+   ```
+
+3. **Enable the server:**
+   ```bash
+   docker mcp server enable kubectl-mcp-server
+   ```
+
+4. **Connect your AI client** (e.g., Claude Desktop):
+   ```bash
+   docker mcp client connect claude
+   ```
+
+The server uses **stdio transport** by default for Docker MCP Toolkit compatibility.
+
+### Running the image (Standalone)
+
+For SSE/HTTP transport (without Docker MCP Toolkit):
+
+```bash
+# SSE transport on port 8000
+docker run -p 8081:8000 \
+           -v $HOME/.kube:/root/.kube:ro \
+           rohitghumare64/kubectl-mcp-server:latest \
+           --transport sse --host 0.0.0.0 --port 8000
+```
+
+For stdio transport (for direct MCP client connections):
+
+```bash
+docker run -i \
+           -v $HOME/.kube:/root/.kube:ro \
+           rohitghumare64/kubectl-mcp-server:latest
+```
+
+* `-i` enables interactive mode for stdio transport
+* `-v $HOME/.kube:/root/.kube:ro` mounts kubeconfig as read-only
+
+### Building a multi-architecture image (AMD64 & ARM64)
+
+If you want to build and push a multi-arch image (so it runs on both x86_64 and Apple Silicon), use Docker Buildx:
+
+```bash
+# Ensure Buildx and QEMU are installed once per machine
+# docker buildx create --name multiarch --use
+# docker buildx inspect --bootstrap
+
+# Build and push for linux/amd64 and linux/arm64
+# (replace <your_username> if you're publishing to your own registry)
+
+docker buildx build \
+  --platform linux/amd64,linux/arm64 \
+  -t rohitghumare64/kubectl-mcp-server:latest \
+  --push .
+```
+
+The published image will contain a manifest list with both architectures, and Docker will automatically pull the correct variant on each machine.
+
+### Configuration
+
+The MCP server is allowed to access these paths to read your Kubernetes configuration:
+
+```yaml
+run:
+  volumes:
+    - '{{kubectl-mcp-server.kubeconfig}}:/root/.kube'
+config:
+  description: The MCP server is allowed to access this path
+  parameters:
+    type: object
+    properties:
+      kubeconfig:
+        type: string
+        default:
+          $HOME/.kube
+    required:
+      - kubeconfig
+```
+
+This configuration allows users to add their kubeconfig directory to the container, enabling the MCP server to authenticate with their Kubernetes cluster.
+
+## Transport Modes
+
+The MCP server supports multiple transport protocols:
+
+### stdio (default)
+Standard input/output transport, used by most MCP clients like Claude Desktop and Cursor:
+```bash
+python -m kubectl_mcp_tool.mcp_server --transport stdio
+```
+
+### SSE (Server-Sent Events)
+HTTP-based transport using Server-Sent Events:
+```bash
+python -m kubectl_mcp_tool.mcp_server --transport sse --host 0.0.0.0 --port 8000
+```
+
+### HTTP / Streamable HTTP
+Standard HTTP transport for clients that prefer JSON-RPC over HTTP:
+```bash
+python -m kubectl_mcp_tool.mcp_server --transport http --host 0.0.0.0 --port 8000
+# or
+python -m kubectl_mcp_tool.mcp_server --transport streamable-http --host 0.0.0.0 --port 8000
+```
+
+### Command-Line Options
+- `--transport`: Transport mode (`stdio`, `sse`, `http`, `streamable-http`). Default: `stdio`
+- `--host`: Host to bind for network transports. Default: `0.0.0.0`
+- `--port`: Port for network transports. Default: `8000`
+- `--non-destructive`: Block destructive operations (delete, apply, create, etc.)
+
+## Multi-Cluster Support
+
+The MCP server provides full multi-cluster support through context management:
+
+```bash
+# List all available contexts
+list_contexts
+
+# Switch to a different cluster
+switch_context --context_name production
+
+# Get details about a specific context
+get_context_details --context_name staging
+
+# Set default namespace for a context
+set_namespace_for_context --namespace kube-system --context_name production
+```
+
+For detailed monitoring features documentation, see [Monitoring Guide](./docs/monitoring.md).
+
+## Available Tools
+
+The MCP server provides 40+ tools for Kubernetes management:
+
+| Category | Tools |
+|----------|-------|
+| **Pods** | `get_pods`, `get_logs`, `get_pod_events`, `check_pod_health`, `exec_in_pod`, `cleanup_pods` |
+| **Deployments** | `get_deployments`, `create_deployment`, `scale_deployment`, `kubectl_rollout` |
+| **Resources** | `get_services`, `get_nodes`, `get_namespaces`, `get_configmaps`, `get_secrets`, `get_events` |
+| **CRUD** | `kubectl_apply`, `kubectl_create`, `kubectl_describe`, `kubectl_patch`, `delete_resource`, `kubectl_cp` |
+| **Helm** | `install_helm_chart`, `upgrade_helm_chart`, `uninstall_helm_chart`, `helm_template`, `helm_template_apply` |
+| **Cluster** | `get_current_context`, `switch_context`, `list_contexts`, `list_kubeconfig_contexts`, `get_cluster_info`, `health_check` |
+| **Security** | `analyze_pod_security`, `analyze_network_policies`, `audit_rbac_permissions`, `check_secrets_security`, `get_rbac_roles`, `get_cluster_roles` |
+| **Node Ops** | `node_management` (cordon, drain, uncordon) |
+| **Advanced** | `kubectl_generic`, `kubectl_explain`, `get_api_resources`, `port_forward`, `get_resource_usage` |
+
+## Usage with AI Assistants
+
+### Using the MCP Server
+
+The MCP Server (`kubectl_mcp_tool.mcp_server`) is a robust implementation built on the FastMCP SDK that provides enhanced compatibility across different AI assistants:
+
+> **Note**: If you encounter any errors with the MCP Server implementation, you can fall back to using the minimal wrapper by replacing `kubectl_mcp_tool.mcp_server` with `kubectl_mcp_tool.minimal_wrapper` in your configuration. The minimal wrapper provides basic capabilities with simpler implementation.
+
+1. **Direct Configuration**
+   ```json
+   {
+     "mcpServers": {
+       "kubernetes": {
+         "command": "python",
+         "args": ["-m", "kubectl_mcp_tool.mcp_server"],
+         "env": {
+           "KUBECONFIG": "/path/to/your/.kube/config",
+           "PATH": "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
+           "MCP_LOG_FILE": "/path/to/logs/debug.log",
+           "MCP_DEBUG": "1"
+         }
+       }
+     }
+   }
+   ```
+
+2. **Key Environment Variables**
+   - `MCP_LOG_FILE`: Path to log file (recommended to avoid stdout pollution)
+   - `MCP_DEBUG`: Set to "1" for verbose logging
+   - `MCP_TEST_MOCK_MODE`: Set to "1" to use mock data instead of real cluster
+   - `KUBECONFIG`: Path to your Kubernetes config file
+   - `KUBECTL_MCP_LOG_LEVEL`: Set to "DEBUG", "INFO", "WARNING", or "ERROR"
+
+3. **Testing the MCP Server**
+   You can test if the server is working correctly with:
+   ```bash
+   python -m kubectl_mcp_tool.simple_ping
+   ```
+   This will attempt to connect to the server and execute a ping command.
+
+   Alternatively, you can directly run the server with:
+   ```bash
+   python -m kubectl_mcp_tool
+   ```
+
+### Claude Desktop
+
+Add the following to your Claude Desktop configuration at `~/Library/Application\ Support/Claude/claude_desktop_config.json` (Windows: `%APPDATA%\Claude\mcp.json`):
+
+**Using npx (Recommended):**
+```json
+{
+  "mcpServers": {
+    "kubernetes": {
+      "command": "npx",
+      "args": ["-y", "kubectl-mcp-server"]
+    }
+  }
+}
+```
+
+**Using Python directly:**
+```json
+{
+  "mcpServers": {
+    "kubernetes": {
+      "command": "python",
+      "args": ["-m", "kubectl_mcp_tool.mcp_server"],
+      "env": {
+        "KUBECONFIG": "$HOME/.kube/config" // or whatever your path is for the config file
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+Claude Code is Anthropic's CLI tool for coding with Claude. Add the following to `~/.config/claude-code/mcp.json`:
+
+**Using npx (Recommended):**
+```json
+{
+  "mcpServers": {
+    "kubernetes": {
+      "command": "npx",
+      "args": ["-y", "kubectl-mcp-server"]
+    }
+  }
+}
+```
+
+**Using Python directly:**
+```json
+{
+  "mcpServers": {
+    "kubernetes": {
+      "command": "python",
+      "args": ["-m", "kubectl_mcp_tool.mcp_server"],
+      "env": {
+        "KUBECONFIG": "/path/to/your/.kube/config"
+      }
+    }
+  }
+}
+```
+
+For detailed Claude Code integration instructions, see [Claude Code Integration Guide](./docs/claude/claude_code_integration.md).
+
+### Cursor AI
+
+Add the following to your Cursor AI settings under MCP by adding a new global MCP server:
+
+**Using npx (Recommended):**
+```json
+{
+  "mcpServers": {
+    "kubernetes": {
+      "command": "npx",
+      "args": ["-y", "kubectl-mcp-server"]
+    }
+  }
+}
+```
+
+**Using Python directly:**
+```json
+{
+  "mcpServers": {
+    "kubernetes": {
+      "command": "python",
+      "args": ["-m", "kubectl_mcp_tool.mcp_server"],
+      "env": {
+        "KUBECONFIG": "/path/to/your/.kube/config",
+        "PATH": "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin"
+      }
+    }
+  }
+}
+```
+
+Save this configuration to `~/.cursor/mcp.json` for global settings.
+
+> **Note**: Replace `/path/to/your/.kube/config` with the actual path to your kubeconfig file. On most systems, this is `~/.kube/config`.
+
+### Windsurf
+
+Add the following to your Windsurf configuration at `~/.config/windsurf/mcp.json` (Windows: `%APPDATA%\WindSurf\mcp.json`):
+
+**Using npx (Recommended):**
+```json
+{
+  "mcpServers": {
+    "kubernetes": {
+      "command": "npx",
+      "args": ["-y", "kubectl-mcp-server"]
+    }
+  }
+}
+```
+
+**Using Python directly:**
+```json
+{
+  "mcpServers": {
+    "kubernetes": {
+      "command": "python",
+      "args": ["-m", "kubectl_mcp_tool.mcp_server"],
+      "env": {
+        "KUBECONFIG": "/path/to/your/.kube/config"
+      }
+    }
+  }
+}
+```
+
+### Automatic Configuration
+
+For automatic configuration of all supported AI assistants, run the provided installation script:
+
+```bash
+bash install.sh
+```

package/bin/cli.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+
+const { spawn } = require('child_process');
+const { existsSync } = require('fs');
+const path = require('path');
+const os = require('os');
+
+// ANSI color codes
+const colors = {
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  reset: '\x1b[0m'
+};
+
+function log(message, color = 'reset') {
+  console.error(`${colors[color]}${message}${colors.reset}`);
+}
+
+function getPythonCommand() {
+  // Try different Python commands
+  const commands = process.platform === 'win32'
+    ? ['python', 'python3', 'py']
+    : ['python3', 'python'];
+
+  for (const cmd of commands) {
+    try {
+      const result = require('child_process').spawnSync(cmd, ['--version'], {
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe']
+      });
+      if (result.status === 0) {
+        return cmd;
+      }
+    } catch (e) {
+      // Continue to next command
+    }
+  }
+  return null;
+}
+
+function checkPythonPackage(pythonCmd) {
+  try {
+    const result = require('child_process').spawnSync(
+      pythonCmd,
+      ['-c', 'import kubectl_mcp_tool; print(kubectl_mcp_tool.__file__)'],
+      { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+    );
+    return result.status === 0;
+  } catch (e) {
+    return false;
+  }
+}
+
+function main() {
+  const args = process.argv.slice(2);
+
+  // Handle help flag
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+kubectl-mcp-server - MCP Server for Kubernetes
+
+Usage: kubectl-mcp-server [options]
+
+Options:
+  --transport <mode>     Transport mode: stdio, sse, http, streamable-http (default: stdio)
+  --host <host>          Host to bind for network transports (default: 0.0.0.0)
+  --port <port>          Port for network transports (default: 8000)
+  --non-destructive      Block destructive operations (delete, apply, create, etc.)
+  --help, -h             Show this help message
+  --version, -v          Show version
+
+Examples:
+  kubectl-mcp-server                           # Start with stdio transport
+  kubectl-mcp-server --transport sse           # Start with SSE transport
+  kubectl-mcp-server --transport http --port 3000
+
+Environment Variables:
+  KUBECONFIG             Path to kubeconfig file (default: ~/.kube/config)
+  MCP_DEBUG              Set to "1" for verbose logging
+  MCP_LOG_FILE           Path to log file
+
+For more information, visit: https://github.com/rohitg00/kubectl-mcp-server
+`);
+    process.exit(0);
+  }
+
+  // Handle version flag
+  if (args.includes('--version') || args.includes('-v')) {
+    const pkg = require('../package.json');
+    console.log(`kubectl-mcp-server v${pkg.version}`);
+    process.exit(0);
+  }
+
+  // Check for Python
+  const pythonCmd = getPythonCommand();
+  if (!pythonCmd) {
+    log('Error: Python 3.9+ is required but not found.', 'red');
+    log('Please install Python from https://www.python.org/downloads/', 'yellow');
+    process.exit(1);
+  }
+
+  // Check if kubectl-mcp-tool is installed
+  if (!checkPythonPackage(pythonCmd)) {
+    log('kubectl-mcp-tool Python package not found. Installing...', 'yellow');
+
+    const installResult = require('child_process').spawnSync(
+      pythonCmd,
+      ['-m', 'pip', 'install', 'kubectl-mcp-tool'],
+      { stdio: 'inherit' }
+    );
+
+    if (installResult.status !== 0) {
+      log('Error: Failed to install kubectl-mcp-tool package.', 'red');
+      log('Try installing manually: pip install kubectl-mcp-tool', 'yellow');
+      process.exit(1);
+    }
+
+    log('kubectl-mcp-tool installed successfully!', 'green');
+  }
+
+  // Run the Python MCP server
+  const serverArgs = ['-m', 'kubectl_mcp_tool.mcp_server', ...args];
+
+  const server = spawn(pythonCmd, serverArgs, {
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      PYTHONUNBUFFERED: '1'
+    }
+  });
+
+  server.on('error', (err) => {
+    log(`Error starting MCP server: ${err.message}`, 'red');
+    process.exit(1);
+  });
+
+  server.on('close', (code) => {
+    process.exit(code || 0);
+  });
+
+  // Handle signals
+  process.on('SIGINT', () => {
+    server.kill('SIGINT');
+  });
+
+  process.on('SIGTERM', () => {
+    server.kill('SIGTERM');
+  });
+}
+
+main();

package/bin/postinstall.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+
+/**
+ * Post-install script for kubectl-mcp-server npm package
+ * Checks for Python and optionally installs the Python package
+ */
+
+const { spawnSync } = require('child_process');
+
+// ANSI color codes
+const colors = {
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  reset: '\x1b[0m',
+  bold: '\x1b[1m'
+};
+
+function log(message, color = 'reset') {
+  console.log(`${colors[color]}${message}${colors.reset}`);
+}
+
+function getPythonCommand() {
+  const commands = process.platform === 'win32'
+    ? ['python', 'python3', 'py']
+    : ['python3', 'python'];
+
+  for (const cmd of commands) {
+    try {
+      const result = spawnSync(cmd, ['--version'], {
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe']
+      });
+      if (result.status === 0) {
+        const version = result.stdout.trim() || result.stderr.trim();
+        return { cmd, version };
+      }
+    } catch (e) {
+      // Continue
+    }
+  }
+  return null;
+}
+
+function checkPythonPackage(pythonCmd) {
+  try {
+    const result = spawnSync(
+      pythonCmd,
+      ['-c', 'import kubectl_mcp_tool; print(kubectl_mcp_tool.__version__ if hasattr(kubectl_mcp_tool, "__version__") else "installed")'],
+      { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+    );
+    if (result.status === 0) {
+      return result.stdout.trim();
+    }
+    return null;
+  } catch (e) {
+    return null;
+  }
+}
+
+function checkKubectl() {
+  try {
+    const result = spawnSync('kubectl', ['version', '--client', '--short'], {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+    return result.status === 0;
+  } catch (e) {
+    return false;
+  }
+}
+
+function main() {
+  console.log('');
+  log('='.repeat(60), 'cyan');
+  log('  kubectl-mcp-server - Post-Installation Check', 'bold');
+  log('='.repeat(60), 'cyan');
+  console.log('');
+
+  // Check Python
+  const python = getPythonCommand();
+  if (!python) {
+    log('WARNING: Python 3.9+ is required but not found.', 'yellow');
+    log('Please install Python from https://www.python.org/downloads/', 'yellow');
+    log('The MCP server will attempt to install dependencies on first run.', 'yellow');
+    console.log('');
+  } else {
+    log(`Found ${python.version}`, 'green');
+
+    // Check if kubectl-mcp-tool is installed
+    const pkgVersion = checkPythonPackage(python.cmd);
+    if (pkgVersion) {
+      log(`kubectl-mcp-tool Python package: v${pkgVersion}`, 'green');
+    } else {
+      log('kubectl-mcp-tool Python package: Not installed', 'yellow');
+      log('It will be installed automatically on first run.', 'yellow');
+
+      // Optionally install now
+      if (process.env.KUBECTL_MCP_INSTALL_NOW === '1') {
+        log('Installing kubectl-mcp-tool...', 'cyan');
+        const result = spawnSync(python.cmd, ['-m', 'pip', 'install', 'kubectl-mcp-tool'], {
+          stdio: 'inherit'
+        });
+        if (result.status === 0) {
+          log('kubectl-mcp-tool installed successfully!', 'green');
+        } else {
+          log('Failed to install kubectl-mcp-tool. It will retry on first run.', 'yellow');
+        }
+      }
+    }
+  }
+
+  // Check kubectl
+  if (checkKubectl()) {
+    log('kubectl CLI: Found', 'green');
+  } else {
+    log('kubectl CLI: Not found', 'yellow');
+    log('Please install kubectl: https://kubernetes.io/docs/tasks/tools/', 'yellow');
+  }
+
+  console.log('');
+  log('-'.repeat(60), 'cyan');
+  log('  Quick Start', 'bold');
+  log('-'.repeat(60), 'cyan');
+  console.log('');
+  log('  Run the MCP server:', 'reset');
+  log('    npx kubectl-mcp-server', 'cyan');
+  console.log('');
+  log('  Or with options:', 'reset');
+  log('    npx kubectl-mcp-server --transport sse --port 8000', 'cyan');
+  console.log('');
+  log('  Add to Claude Desktop config (claude_desktop_config.json):', 'reset');
+  log(`    {
+      "mcpServers": {
+        "kubernetes": {
+          "command": "npx",
+          "args": ["-y", "kubectl-mcp-server"]
+        }
+      }
+    }`, 'cyan');
+  console.log('');
+  log('='.repeat(60), 'cyan');
+  console.log('');
+}
+
+main();

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "kubectl-mcp-server",
+  "version": "1.4.0",
+  "description": "A Model Context Protocol (MCP) server for Kubernetes that enables AI assistants like Claude, Cursor, and others to interact with Kubernetes clusters through natural language",
+  "keywords": [
+    "kubernetes",
+    "kubectl",
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "cursor",
+    "ai",
+    "devops",
+    "k8s"
+  ],
+  "author": "Rohit Ghumare",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rohitg00/kubectl-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rohitg00/kubectl-mcp-server/issues"
+  },
+  "homepage": "https://github.com/rohitg00/kubectl-mcp-server#readme",
+  "bin": {
+    "kubectl-mcp-server": "./bin/cli.js"
+  },
+  "files": [
+    "bin/"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "scripts": {
+    "postinstall": "node bin/postinstall.js"
+  }
+}