kubectl-mcp-server 1.6.0 → 1.9.0

package/README.md

@@ -5,133 +5,121 @@ A Model Context Protocol (MCP) server for Kubernetes that enables AI assistants
 [![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)
+[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)
+[![PyPI](https://img.shields.io/pypi/v/kubectl-mcp-tool?color=blue&label=PyPI)](https://pypi.org/project/kubectl-mcp-tool/)
+[![npm](https://img.shields.io/npm/v/kubectl-mcp-server?color=green&label=npm)](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)
+[![Tests](https://img.shields.io/badge/tests-135%20passed-success)](https://github.com/rohitg00/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)
-
+## MCP Client Compatibility
 
-## Features
+Works with all MCP-compatible AI assistants:
 
-### 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
+| Client | Status | Client | Status |
+|--------|--------|--------|--------|
+| Claude Desktop | ✅ Native | Claude Code | ✅ Native |
+| Cursor | ✅ Native | Windsurf | ✅ Native |
+| GitHub Copilot | ✅ Native | OpenAI Codex | ✅ Native |
+| Gemini CLI | ✅ Native | Goose | ✅ Native |
+| Roo Code | ✅ Native | Kilo Code | ✅ Native |
+| Amp | ✅ Native | Trae | ✅ Native |
+| OpenCode | ✅ Native | Kiro CLI | ✅ Native |
+| Antigravity | ✅ Native | Clawdbot | ✅ Native |
+| Droid (Factory) | ✅ Native | Any MCP Client | ✅ Compatible |
 
-## Architecture
+## Live Demos
 
-### 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
+### Claude Desktop
+![Claude MCP](./docs/claude/claude-mcp.gif)
 
-### Request Flow
+### Cursor AI
+![Cursor MCP](./docs/cursor/cursor-mcp.gif)
 
-![Request Flow](./image.png)
+### Windsurf
+![Windsurf MCP](./docs/windsurf/windsurf-mcp.gif)
 
-### Dual Mode Operation
+## Features
 
-The tool operates in two modes:
+### 121 MCP Tools for Complete Kubernetes Management
 
-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
+| Category | Tools |
+|----------|-------|
+| **Pods** | `get_pods`, `get_logs`, `get_pod_events`, `check_pod_health`, `exec_in_pod`, `cleanup_pods`, `get_pod_conditions`, `get_previous_logs` |
+| **Deployments** | `get_deployments`, `create_deployment`, `scale_deployment`, `kubectl_rollout`, `restart_deployment` |
+| **Workloads** | `get_statefulsets`, `get_daemonsets`, `get_jobs`, `get_replicasets` |
+| **Services & Networking** | `get_services`, `get_ingress`, `get_endpoints`, `diagnose_network_connectivity`, `check_dns_resolution`, `trace_service_chain` |
+| **Storage** | `get_persistent_volumes`, `get_pvcs`, `get_storage_classes` |
+| **Config** | `get_configmaps`, `get_secrets`, `get_resource_quotas`, `get_limit_ranges` |
+| **Cluster** | `get_nodes`, `get_namespaces`, `get_cluster_info`, `get_cluster_version`, `health_check`, `get_node_metrics`, `get_pod_metrics` |
+| **RBAC & Security** | `get_rbac_roles`, `get_cluster_roles`, `get_service_accounts`, `audit_rbac_permissions`, `check_secrets_security`, `get_pod_security_info`, `get_admission_webhooks` |
+| **CRDs** | `get_crds`, `get_priority_classes` |
+| **Helm Releases** | `helm_list`, `helm_status`, `helm_history`, `helm_get_values`, `helm_get_manifest`, `helm_get_notes`, `helm_get_hooks`, `helm_get_all` |
+| **Helm Charts** | `helm_show_chart`, `helm_show_values`, `helm_show_readme`, `helm_show_crds`, `helm_show_all`, `helm_search_repo`, `helm_search_hub` |
+| **Helm Repos** | `helm_repo_list`, `helm_repo_add`, `helm_repo_remove`, `helm_repo_update` |
+| **Helm Operations** | `install_helm_chart`, `upgrade_helm_chart`, `uninstall_helm_chart`, `helm_rollback`, `helm_test`, `helm_template`, `helm_template_apply` |
+| **Helm Development** | `helm_create`, `helm_lint`, `helm_package`, `helm_pull`, `helm_dependency_list`, `helm_dependency_update`, `helm_dependency_build`, `helm_version`, `helm_env` |
+| **Context** | `get_current_context`, `switch_context`, `list_contexts`, `list_kubeconfig_contexts` |
+| **Diagnostics** | `diagnose_pod_crash`, `detect_pending_pods`, `get_evicted_pods`, `compare_namespaces` |
+| **Operations** | `kubectl_apply`, `kubectl_create`, `kubectl_describe`, `kubectl_patch`, `delete_resource`, `kubectl_cp`, `backup_resource`, `label_resource`, `annotate_resource`, `taint_node`, `wait_for_condition` |
+| **Autoscaling** | `get_hpa`, `get_pdb` |
+| **Cost Optimization** | `get_resource_recommendations`, `get_idle_resources`, `get_resource_quotas_usage`, `get_cost_analysis`, `get_overprovisioned_resources`, `get_resource_trends`, `get_namespace_cost_allocation`, `optimize_resource_requests` |
+| **Advanced** | `kubectl_generic`, `kubectl_explain`, `get_api_resources`, `port_forward`, `get_resource_usage`, `node_management` |
+
+### MCP Resources (FastMCP 3)
+
+Access Kubernetes data as browsable resources:
+
+| Resource URI | Description |
+|--------------|-------------|
+| `kubeconfig://contexts` | List all available kubectl contexts |
+| `kubeconfig://current-context` | Get current active context |
+| `namespace://current` | Get current namespace |
+| `namespace://list` | List all namespaces |
+| `cluster://info` | Get cluster information |
+| `cluster://nodes` | Get detailed node information |
+| `cluster://version` | Get Kubernetes version |
+| `cluster://api-resources` | List available API resources |
+| `manifest://deployments/{ns}/{name}` | Get deployment YAML |
+| `manifest://services/{ns}/{name}` | Get service YAML |
+| `manifest://pods/{ns}/{name}` | Get pod YAML |
+| `manifest://configmaps/{ns}/{name}` | Get ConfigMap YAML |
+| `manifest://secrets/{ns}/{name}` | Get secret YAML (data masked) |
+| `manifest://ingresses/{ns}/{name}` | Get ingress YAML |
+
+### MCP Prompts (FastMCP 3)
+
+Pre-built workflow prompts for common Kubernetes operations:
+
+| Prompt | Description |
+|--------|-------------|
+| `troubleshoot_workload` | Comprehensive troubleshooting guide for pods/deployments |
+| `deploy_application` | Step-by-step deployment workflow |
+| `security_audit` | Security scanning and RBAC analysis workflow |
+| `cost_optimization` | Resource optimization and cost analysis workflow |
+| `disaster_recovery` | Backup and recovery planning workflow |
+| `debug_networking` | Network debugging for services and connectivity |
+| `scale_application` | Scaling guide with HPA/VPA best practices |
+| `upgrade_cluster` | Kubernetes cluster upgrade planning |
+
+### Key Capabilities
+
+- **Multi-Transport Support**: stdio, SSE, HTTP/streamable-http
+- **AI Assistant Integration**: Claude Desktop, Claude Code, Cursor, Windsurf
+- **Multi-Cluster**: Context switching between clusters
+- **Security**: Non-destructive mode, secrets masking, RBAC validation
+- **Diagnostics**: Pod crash analysis, network connectivity testing, DNS resolution checks
+- **Helm v3**: Full Helm chart lifecycle management
+- **Cost Optimization**: Resource recommendations, idle resource detection, usage analysis
+- **FastMCP 3**: MCP Resources and Prompts for enhanced AI workflows
 
 ## Installation
 
-For detailed installation instructions, please see the [Installation Guide](./docs/INSTALLATION.md).
-
-### npm / npx (Recommended for Node.js users)
+### Prerequisites
+- Python 3.9+
+- kubectl CLI installed and configured
+- Access to a Kubernetes cluster
 
-The easiest way to run kubectl-mcp-server is via npx:
+### npm / npx (Recommended)
 
 ```bash
 # Run directly without installation
@@ -139,289 +127,33 @@ 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:
+### Docker
 
 ```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:
+# Run with stdio transport
+docker run -i -v $HOME/.kube:/root/.kube:ro rohitghumare64/kubectl-mcp-server:latest
 
-```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
+# Run with SSE transport
+docker run -p 8000:8000 -v $HOME/.kube:/root/.kube:ro rohitghumare64/kubectl-mcp-server:latest --transport sse
 ```
 
-### 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
-   ```
+## Quick Start
 
 ### Claude Desktop
 
-Add the following to your Claude Desktop configuration at `~/Library/Application\ Support/Claude/claude_desktop_config.json` (Windows: `%APPDATA%\Claude\mcp.json`):
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
-**Using npx (Recommended):**
 ```json
 {
   "mcpServers": {
@@ -433,26 +165,25 @@ Add the following to your Claude Desktop configuration at `~/Library/Application
 }
 ```
 
-**Using Python directly:**
+### Claude Code
+
+Add to `~/.config/claude-code/mcp.json`:
+
 ```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
-      }
+      "command": "npx",
+      "args": ["-y", "kubectl-mcp-server"]
     }
   }
 }
 ```
 
-### Claude Code
+### Cursor AI
 
-Claude Code is Anthropic's CLI tool for coding with Claude. Add the following to `~/.config/claude-code/mcp.json`:
+Add to `~/.cursor/mcp.json`:
 
-**Using npx (Recommended):**
 ```json
 {
   "mcpServers": {
@@ -464,64 +195,70 @@ Claude Code is Anthropic's CLI tool for coding with Claude. Add the following to
 }
 ```
 
-**Using Python directly:**
+### Windsurf
+
+Add to `~/.config/windsurf/mcp.json`:
+
 ```json
 {
   "mcpServers": {
     "kubernetes": {
-      "command": "python",
-      "args": ["-m", "kubectl_mcp_tool.mcp_server"],
-      "env": {
-        "KUBECONFIG": "/path/to/your/.kube/config"
-      }
+      "command": "npx",
+      "args": ["-y", "kubectl-mcp-server"]
     }
   }
 }
 ```
 
-For detailed Claude Code integration instructions, see [Claude Code Integration Guide](./docs/claude/claude_code_integration.md).
-
-### Cursor AI
+### GitHub Copilot (VS Code)
 
-Add the following to your Cursor AI settings under MCP by adding a new global MCP server:
+Add to VS Code `settings.json`:
 
-**Using npx (Recommended):**
 ```json
 {
-  "mcpServers": {
-    "kubernetes": {
-      "command": "npx",
-      "args": ["-y", "kubectl-mcp-server"]
+  "mcp": {
+    "servers": {
+      "kubernetes": {
+        "command": "npx",
+        "args": ["-y", "kubectl-mcp-server"]
+      }
     }
   }
 }
 ```
 
-**Using Python directly:**
+### Goose
+
+Add to `~/.config/goose/config.yaml`:
+
+```yaml
+extensions:
+  kubernetes:
+    command: npx
+    args:
+      - -y
+      - kubectl-mcp-server
+```
+
+### Gemini CLI
+
+Add to `~/.gemini/settings.json`:
+
 ```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"
-      }
+      "command": "npx",
+      "args": ["-y", "kubectl-mcp-server"]
     }
   }
 }
 ```
 
-Save this configuration to `~/.cursor/mcp.json` for global settings.
+### Roo Code / Kilo Code
 
-> **Note**: Replace `/path/to/your/.kube/config` with the actual path to your kubeconfig file. On most systems, this is `~/.kube/config`.
+Add to `~/.config/roo-code/mcp.json` or `~/.config/kilo-code/mcp.json`:
 
-### Windsurf
-
-Add the following to your Windsurf configuration at `~/.config/windsurf/mcp.json` (Windows: `%APPDATA%\WindSurf\mcp.json`):
-
-**Using npx (Recommended):**
 ```json
 {
   "mcpServers": {
@@ -533,7 +270,10 @@ Add the following to your Windsurf configuration at `~/.config/windsurf/mcp.json
 }
 ```
 
-**Using Python directly:**
+### Using Python Directly
+
+If you prefer Python over npx:
+
 ```json
 {
   "mcpServers": {
@@ -541,17 +281,176 @@ Add the following to your Windsurf configuration at `~/.config/windsurf/mcp.json
       "command": "python",
       "args": ["-m", "kubectl_mcp_tool.mcp_server"],
       "env": {
-        "KUBECONFIG": "/path/to/your/.kube/config"
+        "KUBECONFIG": "/path/to/.kube/config"
       }
     }
   }
 }
 ```
 
-### Automatic Configuration
+## Transport Modes
+
+```bash
+# stdio (default) - for Claude Desktop, Cursor, etc.
+python -m kubectl_mcp_tool.mcp_server
+
+# SSE - Server-Sent Events
+python -m kubectl_mcp_tool.mcp_server --transport sse --port 8000
+
+# HTTP
+python -m kubectl_mcp_tool.mcp_server --transport http --port 8000
+```
+
+### Options
+- `--transport`: `stdio`, `sse`, `http`, `streamable-http` (default: `stdio`)
+- `--host`: Host to bind (default: `0.0.0.0`)
+- `--port`: Port for network transports (default: `8000`)
+- `--non-destructive`: Block destructive operations (delete, apply, create)
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `KUBECONFIG` | Path to kubeconfig file (default: `~/.kube/config`) |
+| `MCP_DEBUG` | Set to `1` for verbose logging |
+| `MCP_LOG_FILE` | Path to log file |
+
+## Docker MCP Toolkit
+
+Compatible with [Docker MCP Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/):
+
+```bash
+# Add server
+docker mcp server add kubectl-mcp-server mcp/kubectl-mcp-server:latest
+
+# Configure kubeconfig
+docker mcp server configure kubectl-mcp-server --volume "$HOME/.kube:/root/.kube:ro"
+
+# Enable and connect
+docker mcp server enable kubectl-mcp-server
+docker mcp client connect claude
+```
+
+## Architecture
+
+```
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│   AI Assistant  │────▶│   MCP Server     │────▶│  Kubernetes API │
+│ (Claude/Cursor) │◀────│ (kubectl-mcp)    │◀────│    (kubectl)    │
+└─────────────────┘     └──────────────────┘     └─────────────────┘
+```
+
+The MCP server implements the [Model Context Protocol](https://github.com/modelcontextprotocol/spec), translating natural language requests into kubectl operations.
+
+### Modular Structure
+
+```
+kubectl_mcp_tool/
+├── mcp_server.py          # Main server (FastMCP, transports)
+├── tools/                  # 121 MCP tools organized by category
+│   ├── pods.py            # Pod management & diagnostics
+│   ├── deployments.py     # Deployments, StatefulSets, DaemonSets
+│   ├── core.py            # Namespaces, ConfigMaps, Secrets
+│   ├── cluster.py         # Context/cluster management
+│   ├── networking.py      # Services, Ingress, NetworkPolicies
+│   ├── storage.py         # PVCs, StorageClasses, PVs
+│   ├── security.py        # RBAC, ServiceAccounts, PodSecurity
+│   ├── helm.py            # Complete Helm v3 operations
+│   ├── operations.py      # kubectl apply/patch/describe/etc
+│   ├── diagnostics.py     # Metrics, namespace comparison
+│   └── cost.py            # Resource optimization & cost analysis
+├── resources/              # 8 MCP Resources for data exposure
+├── prompts/                # 8 MCP Prompts for workflows
+└── cli/                    # CLI interface
+```
+
+## Multi-Cluster Support
+
+```bash
+# List contexts
+list_contexts
+
+# Switch cluster
+switch_context --context_name production
+
+# Get context details
+get_context_details --context_name staging
+```
+
+## Development & Testing
+
+### Setup Development Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/rohitg00/kubectl-mcp-server.git
+cd kubectl-mcp-server
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install development dependencies
+pip install -r requirements-dev.txt
+```
+
+### Running Tests
 
-For automatic configuration of all supported AI assistants, run the provided installation script:
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run specific test file
+pytest tests/test_tools.py -v
+
+# Run with coverage
+pytest tests/ --cov=kubectl_mcp_tool --cov-report=html
+
+# Run only unit tests
+pytest tests/ -v -m unit
+```
+
+### Test Structure
+
+```
+tests/
+├── __init__.py          # Test package
+├── conftest.py          # Shared fixtures and mocks
+├── test_tools.py        # Unit tests for 121 MCP tools
+├── test_resources.py    # Tests for 8 MCP Resources
+├── test_prompts.py      # Tests for 8 MCP Prompts
+└── test_server.py       # Server initialization tests
+```
+
+**135 tests covering**: tool registration, resource exposure, prompt generation, server initialization, non-destructive mode, secret masking, error handling, and transport methods.
+
+### Code Quality
 
 ```bash
-bash install.sh
-```
+# Format code
+black kubectl_mcp_tool tests
+
+# Sort imports
+isort kubectl_mcp_tool tests
+
+# Lint
+flake8 kubectl_mcp_tool tests
+
+# Type checking
+mypy kubectl_mcp_tool
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Links
+
+- [PyPI Package](https://pypi.org/project/kubectl-mcp-tool/)
+- [npm Package](https://www.npmjs.com/package/kubectl-mcp-server)
+- [Docker Hub](https://hub.docker.com/r/rohitghumare64/kubectl-mcp-server)
+- [GitHub Issues](https://github.com/rohitg00/kubectl-mcp-server/issues)

package/bin/cli.js

@@ -1,53 +1,23 @@
 #!/usr/bin/env node
 
-const { spawn } = require('child_process');
-const { existsSync } = require('fs');
-const path = require('path');
-const os = require('os');
+const { spawn, spawnSync } = require('child_process');
 
-// 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}`);
-}
+const colors = { red: '\x1b[31m', green: '\x1b[32m', yellow: '\x1b[33m', reset: '\x1b[0m' };
+const log = (msg, color = 'reset') => console.error(`${colors[color]}${msg}${colors.reset}`);
 
 function getPythonCommand() {
-  // Try different Python commands
-  const commands = process.platform === 'win32'
-    ? ['python', 'python3', 'py']
-    : ['python3', 'python'];
-
+  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
-    }
+      if (spawnSync(cmd, ['--version'], { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).status === 0) return cmd;
+    } catch (e) {}
   }
   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;
+    return spawnSync(pythonCmd, ['-c', 'import kubectl_mcp_tool'], { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).status === 0;
   } catch (e) {
     return false;
   }
@@ -56,7 +26,6 @@ function checkPythonPackage(pythonCmd) {
 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
@@ -64,90 +33,47 @@ 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
+  --transport <mode>   Transport: stdio, sse, http, streamable-http (default: stdio)
+  --host <host>        Host for network transports (default: 0.0.0.0)
+  --port <port>        Port for network transports (default: 8000)
+  --non-destructive    Block destructive operations
+  --help, -h           Show this help message
+  --version, -v        Show version
+
+For more info: 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}`);
+    console.log(`kubectl-mcp-server v${require('../package.json').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');
+    log('Error: Python 3.9+ is required. Install from https://python.org', 'red');
     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');
+    log('Installing kubectl-mcp-tool...', 'yellow');
+    if (spawnSync(pythonCmd, ['-m', 'pip', 'install', 'kubectl-mcp-tool'], { stdio: 'inherit' }).status !== 0) {
+      log('Failed to install. Try: pip install kubectl-mcp-tool', 'red');
       process.exit(1);
     }
-
-    log('kubectl-mcp-tool installed successfully!', 'green');
+    log('Installed successfully!', 'green');
   }
 
-  // Run the Python MCP server
-  const serverArgs = ['-m', 'kubectl_mcp_tool.mcp_server', ...args];
-
-  const server = spawn(pythonCmd, serverArgs, {
+  const server = spawn(pythonCmd, ['-m', 'kubectl_mcp_tool.mcp_server', ...args], {
     stdio: 'inherit',
-    env: {
-      ...process.env,
-      PYTHONUNBUFFERED: '1'
-    }
-  });
-
-  server.on('error', (err) => {
-    log(`Error starting MCP server: ${err.message}`, 'red');
-    process.exit(1);
+    env: { ...process.env, PYTHONUNBUFFERED: '1' }
   });
 
-  server.on('close', (code) => {
-    process.exit(code || 0);
-  });
-
-  // Handle signals
-  process.on('SIGINT', () => {
-    server.kill('SIGINT');
-  });
-
-  process.on('SIGTERM', () => {
-    server.kill('SIGTERM');
-  });
+  server.on('error', (err) => { log(`Error: ${err.message}`, 'red'); process.exit(1); });
+  server.on('close', (code) => process.exit(code || 0));
+  process.on('SIGINT', () => server.kill('SIGINT'));
+  process.on('SIGTERM', () => server.kill('SIGTERM'));
 }
 
 main();

package/bin/postinstall.js

@@ -1,147 +1,47 @@
 #!/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}`);
-}
+const colors = { green: '\x1b[32m', yellow: '\x1b[33m', cyan: '\x1b[36m', reset: '\x1b[0m', bold: '\x1b[1m' };
+const log = (msg, color = 'reset') => console.log(`${colors[color]}${msg}${colors.reset}`);
 
 function getPythonCommand() {
-  const commands = process.platform === 'win32'
-    ? ['python', 'python3', 'py']
-    : ['python3', 'python'];
-
+  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
-    }
+      const result = spawnSync(cmd, ['--version'], { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+      if (result.status === 0) return { cmd, version: (result.stdout || result.stderr).trim() };
+    } catch (e) {}
   }
   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');
+  log('kubectl-mcp-server installed!', 'bold');
   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');
+  if (python) {
+    log(`Python: ${python.version}`, 'green');
   } else {
-    log('kubectl CLI: Not found', 'yellow');
-    log('Please install kubectl: https://kubernetes.io/docs/tasks/tools/', 'yellow');
+    log('Python 3.9+ required: https://python.org', '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');
+  log('Usage:', 'cyan');
+  log('  npx kubectl-mcp-server', 'reset');
+  log('  npx kubectl-mcp-server --transport sse --port 8000', 'reset');
   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"]
-        }
+  log('Claude Desktop config:', 'cyan');
+  console.log(`  {
+    "mcpServers": {
+      "kubernetes": {
+        "command": "npx",
+        "args": ["-y", "kubectl-mcp-server"]
       }
-    }`, 'cyan');
-  console.log('');
-  log('='.repeat(60), 'cyan');
+    }
+  }`);
   console.log('');
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kubectl-mcp-server",
-  "version": "1.6.0",
+  "version": "1.9.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",