kubectl-mcp-server 1.12.0__py3-none-any.whl

kubectl_mcp_server-1.12.0.dist-info/METADATA

@@ -0,0 +1,711 @@
+Metadata-Version: 2.4
+Name: kubectl-mcp-server
+Version: 1.12.0
+Summary: A Model Context Protocol (MCP) server for Kubernetes with 121+ tools, 8 resources, and 8 prompts
+Home-page: https://github.com/rohitg00/kubectl-mcp-server
+Author: Rohit Ghumare
+Author-email: ghumare64@gmail.com
+Project-URL: Bug Tracker, https://github.com/rohitg00/kubectl-mcp-server/issues
+Project-URL: Documentation, https://github.com/rohitg00/kubectl-mcp-server#readme
+Project-URL: Source, https://github.com/rohitg00/kubectl-mcp-server
+Keywords: kubernetes,mcp,model-context-protocol,kubectl,helm,ai-assistant,claude,cursor,windsurf,fastmcp,devops,cloud-native
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp>=3.0.0b1
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn>=0.22.0
+Requires-Dist: starlette>=0.27.0
+Requires-Dist: kubernetes>=28.1.0
+Requires-Dist: PyYAML>=6.0.1
+Requires-Dist: requests>=2.31.0
+Requires-Dist: urllib3>=2.1.0
+Requires-Dist: websocket-client>=1.7.0
+Requires-Dist: jsonschema>=4.20.0
+Requires-Dist: cryptography>=42.0.2
+Requires-Dist: rich>=13.0.0
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: aiohttp-sse>=2.1.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# 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.
+
+[![GitHub Stars](https://img.shields.io/github/stars/rohitg00/kubectl-mcp-server?style=flat&logo=github)](https://github.com/rohitg00/kubectl-mcp-server)
+[![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://modelcontextprotocol.io)
+[![PyPI](https://img.shields.io/pypi/v/kubectl-mcp-server?color=blue&label=PyPI)](https://pypi.org/project/kubectl-mcp-server/)
+[![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-187%20passed-success)](https://github.com/rohitg00/kubectl-mcp-server)
+[![agentregistry](https://img.shields.io/badge/agentregistry-verified-blue?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgZmlsbD0id2hpdGUiIHZpZXdCb3g9IjAgMCAxNiAxNiI+PHBhdGggZD0iTTE1Ljk5MiA2LjAzN2wtMy4wMjEtLjQzOS0xLjM1LTIuNzM2Yy0uMzQ2LS43MDItMS41MDQtLjcwMi0xLjg1IDBMOC40MjEgNS41OTggNS40IDYuMDM3Yy0uNzc2LjExMy0xLjA4OCAxLjA1My0uNTI4IDEuNTkzbDIuMTg2IDIuMTI5LS41MTYgMy4wMWMtLjEzMy43NzUuNjgyIDEuMzY2IDEuMzc4Ljk5OGwyLjcwMi0xLjQyIDIuNzAyIDEuNDJjLjY5Ni4zNjggMS41MTEtLjIyMyAxLjM3OC0uOTk4bC0uNTE2LTMuMDEgMi4xODYtMi4xMjljLjU2LS41NCAwLjI0OC0xLjQ4LS41MjgtMS41OTN6Ii8+PC9zdmc+)](https://aregistry.ai)
+
+## MCP Client Compatibility
+
+Works with all MCP-compatible AI assistants:
+
+| 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 |
+
+## Live Demos
+
+### Claude Desktop
+![Claude MCP](./docs/claude/claude-mcp.gif)
+
+### Cursor AI
+![Cursor MCP](./docs/cursor/cursor-mcp.gif)
+
+### Windsurf
+![Windsurf MCP](./docs/windsurf/windsurf-mcp.gif)
+
+## Features
+
+### 121 MCP Tools for Complete Kubernetes Management
+
+| 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
+
+### Prerequisites
+- Python 3.9+
+- kubectl CLI installed and configured
+- Access to a Kubernetes cluster
+
+### npm / npx (Recommended)
+
+```bash
+# Run directly without installation
+npx kubectl-mcp-server
+
+# Or install globally
+npm install -g kubectl-mcp-server
+```
+
+### pip (Python)
+
+```bash
+pip install kubectl-mcp-server
+
+# Legacy alias (still works for backward compatibility)
+pip install kubectl-mcp-tool
+```
+
+### Docker
+
+```bash
+# Pull the latest image
+docker pull rohitghumare64/kubectl-mcp-server:latest
+
+# Run with stdio transport
+docker run -i -v $HOME/.kube:/root/.kube:ro rohitghumare64/kubectl-mcp-server:latest
+
+# Run with SSE transport
+docker run -p 8000:8000 -v $HOME/.kube:/root/.kube:ro rohitghumare64/kubectl-mcp-server:latest --transport sse
+```
+
+## Quick Start
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "kubernetes": {
+      "command": "npx",
+      "args": ["-y", "kubectl-mcp-server"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to `~/.config/claude-code/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "kubernetes": {
+      "command": "npx",
+      "args": ["-y", "kubectl-mcp-server"]
+    }
+  }
+}
+```
+
+### Cursor AI
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "kubernetes": {
+      "command": "npx",
+      "args": ["-y", "kubectl-mcp-server"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `~/.config/windsurf/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "kubernetes": {
+      "command": "npx",
+      "args": ["-y", "kubectl-mcp-server"]
+    }
+  }
+}
+```
+
+### GitHub Copilot (VS Code)
+
+Add to VS Code `settings.json`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "kubernetes": {
+        "command": "npx",
+        "args": ["-y", "kubectl-mcp-server"]
+      }
+    }
+  }
+}
+```
+
+### 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": "npx",
+      "args": ["-y", "kubectl-mcp-server"]
+    }
+  }
+}
+```
+
+### Roo Code / Kilo Code
+
+Add to `~/.config/roo-code/mcp.json` or `~/.config/kilo-code/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "kubernetes": {
+      "command": "npx",
+      "args": ["-y", "kubectl-mcp-server"]
+    }
+  }
+}
+```
+
+### Using Python Directly
+
+If you prefer Python over npx:
+
+```json
+{
+  "mcpServers": {
+    "kubernetes": {
+      "command": "python",
+      "args": ["-m", "kubectl_mcp_tool.mcp_server"],
+      "env": {
+        "KUBECONFIG": "/path/to/.kube/config"
+      }
+    }
+  }
+}
+```
+
+## 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 |
+
+### Authentication (Enterprise)
+
+| Variable | Description |
+|----------|-------------|
+| `MCP_AUTH_ENABLED` | Enable OAuth 2.1 authentication (default: `false`) |
+| `MCP_AUTH_ISSUER` | OAuth 2.0 Authorization Server URL |
+| `MCP_AUTH_JWKS_URI` | JWKS endpoint (optional, derived from issuer) |
+| `MCP_AUTH_AUDIENCE` | Expected token audience (default: `kubectl-mcp-server`) |
+| `MCP_AUTH_REQUIRED_SCOPES` | Required scopes (default: `mcp:tools`) |
+
+### Browser Automation (Optional)
+
+| Variable | Description |
+|----------|-------------|
+| `MCP_BROWSER_ENABLED` | Enable browser automation tools (default: `false`) |
+
+## Browser Tools (Optional Module)
+
+Enable browser automation for web-based K8s operations using [agent-browser](https://github.com/vercel-labs/agent-browser).
+
+### Setup
+
+```bash
+# Install agent-browser
+npm install -g agent-browser
+agent-browser install  # Download Chromium
+
+# Enable browser tools
+export MCP_BROWSER_ENABLED=true
+kubectl-mcp-server
+```
+
+### 19 Browser Tools
+
+| Tool | Description |
+|------|-------------|
+| `browser_open` | Open URL in browser |
+| `browser_snapshot` | Get page accessibility tree |
+| `browser_click` | Click element by ref |
+| `browser_fill` | Fill form field |
+| `browser_screenshot` | Take screenshot |
+| `browser_get_text` | Get element text |
+| `browser_get_url` | Get current URL |
+| `browser_wait` | Wait for element/text/timeout |
+| `browser_close` | Close browser |
+| `browser_test_ingress` | Test K8s service via Ingress |
+| `browser_screenshot_service` | Screenshot K8s service UI |
+| `browser_screenshot_grafana` | Screenshot Grafana dashboard |
+| `browser_screenshot_argocd` | Screenshot ArgoCD app |
+| `browser_health_check` | Health check web app |
+| `browser_form_submit` | Fill and submit form |
+| `browser_session_save` | Save browser session |
+| `browser_session_load` | Load browser session |
+| `browser_open_cloud_console` | Open EKS/GKE/AKS console |
+| `browser_pdf_export` | Export page as PDF |
+
+### Use Cases
+
+- **Test deployed apps** via Ingress URLs
+- **Screenshot Grafana/ArgoCD** dashboards
+- **Automate cloud console** operations (EKS, GKE, AKS)
+- **Health check** web applications
+- **Export monitoring dashboards** as PDF
+
+## MCP Authorization (RFC 9728)
+
+For enterprise deployments, kubectl-mcp-server supports OAuth 2.1 authentication.
+
+```bash
+export MCP_AUTH_ENABLED=true
+export MCP_AUTH_ISSUER=https://your-idp.example.com
+export MCP_AUTH_AUDIENCE=kubectl-mcp-server
+kubectl-mcp-server --transport http --port 8000
+```
+
+Supported identity providers: **Okta**, **Auth0**, **Keycloak**, **Microsoft Entra ID**, **Google OAuth**, and any OIDC-compliant provider.
+
+## 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
+```
+
+## agentregistry
+
+kubectl-mcp-server is published to [agentregistry](https://github.com/agentregistry-dev/agentregistry), a centralized registry for MCP servers.
+
+### Install with arctl
+
+```bash
+# Install arctl CLI
+curl -fsSL https://raw.githubusercontent.com/agentregistry-dev/agentregistry/main/scripts/install.sh | bash
+
+# Search for kubectl-mcp-server
+arctl mcp search kubectl
+
+# Install the server
+arctl mcp install io.github.rohitg00/kubectl-mcp-server
+```
+
+### Available Packages
+
+| Registry | Identifier |
+|----------|------------|
+| **PyPI** | `kubectl-mcp-server` (uvx) |
+| **npm** | `kubectl-mcp-server` (npx) |
+| **OCI** | `docker.io/rohitghumare64/kubectl-mcp-server` |
+
+### agentgateway Integration
+
+Use with [agentgateway](https://github.com/agentgateway/agentgateway) for unified MCP routing:
+
+```bash
+# Install agentgateway
+cargo install agentgateway
+
+# Configure kubectl-mcp-server as upstream
+agentgateway --config gateway.yaml
+```
+
+## Kubernetes Deployment
+
+Deploy kubectl-mcp-server directly in your Kubernetes cluster for centralized access.
+
+### kMCP Deployment (Recommended)
+
+[kMCP](https://github.com/kagent-dev/kmcp) is a development platform and control plane for MCP servers. See [kMCP quickstart](https://kagent.dev/docs/kmcp/quickstart).
+
+```bash
+# Install kmcp CLI
+curl -fsSL https://raw.githubusercontent.com/kagent-dev/kmcp/refs/heads/main/scripts/get-kmcp.sh | bash
+
+# Install kmcp controller in your cluster
+helm install kmcp-crds oci://ghcr.io/kagent-dev/kmcp/helm/kmcp-crds \
+     --namespace kmcp-system --create-namespace
+kmcp install
+
+# Deploy kubectl-mcp-server using npx (easiest)
+kmcp deploy package --deployment-name kubectl-mcp-server \
+   --manager npx --args kubectl-mcp-server
+
+# Or deploy using our Docker image with the MCPServer manifest
+kmcp deploy --file deploy/kmcp/kmcp.yaml --image rohitghumare64/kubectl-mcp-server:latest
+```
+
+### Standard Kubernetes Deployment
+
+Deploy using kubectl/kustomize without kMCP:
+
+```bash
+# Using kustomize (recommended)
+kubectl apply -k deploy/kubernetes/
+
+# Or apply individual manifests
+kubectl apply -f deploy/kubernetes/namespace.yaml
+kubectl apply -f deploy/kubernetes/rbac.yaml
+kubectl apply -f deploy/kubernetes/deployment.yaml
+kubectl apply -f deploy/kubernetes/service.yaml
+
+# Access via port-forward
+kubectl port-forward -n kubectl-mcp svc/kubectl-mcp-server 8000:8000
+```
+
+### MCPServer Custom Resource
+
+For kMCP deployments, apply this MCPServer resource:
+
+```yaml
+apiVersion: kagent.dev/v1alpha1
+kind: MCPServer
+metadata:
+  name: kubectl-mcp-server
+spec:
+  deployment:
+    image: "rohitghumare64/kubectl-mcp-server:latest"
+    port: 8000
+  transportType: http
+  httpTransport:
+    targetPort: 8000
+    path: /mcp
+```
+
+See [deploy/](deploy/) for full manifests and configuration options.
+
+### kagent Integration (AI Agents)
+
+[kagent](https://github.com/kagent-dev/kagent) is a Kubernetes-native AI agent framework (CNCF project). Register kubectl-mcp-server as a ToolServer to give your agents 121 K8s management tools.
+
+```bash
+# Install kagent
+brew install kagent
+kagent install --profile demo
+
+# Register kubectl-mcp-server as a ToolServer
+kubectl apply -f deploy/kagent/toolserver-stdio.yaml
+
+# Open kagent dashboard and chat with your K8s agent
+kagent dashboard
+```
+
+See [kagent quickstart](https://kagent.dev/docs/kagent/getting-started/quickstart) for full documentation.
+
+## 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
+
+```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
+```
+
+**138 tests covering**: tool registration, resource exposure, prompt generation, server initialization, non-destructive mode, secret masking, error handling, and transport methods.
+
+### Code Quality
+
+```bash
+# 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-server/)
+- [npm Package](https://www.npmjs.com/package/kubectl-mcp-server)
+- [Docker Hub](https://hub.docker.com/r/rohitghumare64/kubectl-mcp-server)
+- [agentregistry](https://aregistry.ai) - MCP Server Registry
+- [GitHub Issues](https://github.com/rohitg00/kubectl-mcp-server/issues)