# KubeCraft MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that gives AI assistants (Claude, Cursor, etc.) full visibility and control over Kubernetes clusters.

## Features (140 tools)

| Category | Tools | Count |
|----------|-------|-------|
| **Cluster Info** | `get_cluster_info`, `list_namespaces`, `list_nodes` (includes **GPU(alloc)** column), `get_node_health` | 4 |
| **Resources** | `list_pods`, `list_deployments`, `list_services`, `list_ingresses`, `list_gateway_api`, `list_hpas`, `list_resource_quotas`, `list_pod_disruption_budgets`, `list_resources`, `describe_resource`, `get_resource_usage` | 11 |
| **Diagnostics** | `diagnose_pod`, `get_pod_logs`, `get_events` | 3 |
| **Management** | `scale_deployment`, `restart_deployment`, `rollout_history`, `rollback_deployment`, `cordon_node`, `uncordon_node`, `delete_resource`, `apply_manifest`, `validate_manifest` | 9 |
| **Platform / Posture** | `inspect_rbac`, `list_storage_overview`, `cert_manager_health`, `summarize_network_policies`, `diagnose_service_endpoints`, `summarize_policy_engines` | 6 |
| **Security Posture** | `summarize_pod_security_standards`, `audit_service_accounts`, `summarize_image_vulnerabilities`, `audit_secret_hygiene` | 4 |
| **Workloads** | `list_daemonsets`, `restart_daemonset`, `list_statefulsets`, `scale_statefulset`, `restart_statefulset`, `list_cronjobs`, `list_jobs`, `trigger_cronjob`, `analyze_pod_disruption` | 9 |
| **Cluster Intelligence** | `cluster_health_score`, `scan_deprecations`, `unused_resource_report` | 3 |
| **Advanced Storage** | `list_csi_drivers` (capabilities + node registration), `list_volume_snapshots` (snapshot.storage.k8s.io), `analyze_storage_capacity` (PV/PVC utilization + CSIStorageCapacity) | 3 |
| **Advanced Networking** | `list_ingress_classes`, `detect_service_mesh` (Istio/Linkerd/Cilium + sidecar status), `detect_cni` (Calico/Cilium/Flannel/AWS VPC/etc.), `diagnose_coredns`, `analyze_network_reachability` (NetworkPolicy posture), `visualize_network_policies` (Mermaid graph), `simulate_pod_reachability` (pure-logic NetworkPolicy walker), `visualize_egress_allowances` (NS → external CIDR Mermaid), `find_unprotected_workloads` (zero-trust gap detector), `audit_loadbalancers` (LB services + pending allocations), `port_conflict_check` (NodePort + hostNetwork conflicts), `dns_lookup` (cluster-DNS view of any hostname) | 12 |
| **Ingress Audit** | `audit_ingress_endpoints` (backends + TLS), `audit_ingress_tls` (cert expiry, sorted by urgency), `visualize_ingress_topology` (Mermaid Ingress → Service → Pod chains), `test_ingress_connectivity` (synthetic curl probe with timing breakdown) | 4 |
| **Access Control (RBAC YAML)** | `grant_namespace_access` (viewer/editor/admin), `grant_resource_access` (least-privilege Role generator + lint warnings), `revoke_access` (find + remove all bindings) | 3 |
| **Compliance Reporting** | `generate_compliance_report` — aggregates evidence from 11 audit-relevant tools and exports to **Markdown + PDF + DOCX**. Supports CIS Kubernetes Benchmark, SOC 2, ISO 27001, NIST 800-53, PCI-DSS, HIPAA, or comprehensive (all). Multi-cluster optional. | 1 |
| **CRDs & Operators** | `list_crds`, `describe_crd`, `count_custom_resources` (find bloat), `detect_operators` (combines OLM + known-group + Deployment-pattern signals), `audit_finalizers` (stuck-Terminating resources + unstuck recipes), `audit_operator_rbac` (flag operators running with cluster-admin), `find_orphan_crs` (CRs after operator uninstall), `audit_crd_versions` (multi-version + conversion strategy + preserveUnknownFields), `list_olm_subscriptions`, `visualize_operators` (Mermaid: operators → CRDs → CR counts) | 10 |
| **Visualization** | `visualize_cluster_topology`, `visualize_namespace`, `visualize_network`, `visualize_app_architecture`, `analyze_connections` | 5 |
| **Rendered Diagrams** | `render_cluster_topology`, `render_namespace`, `render_network`, `render_app_architecture`, `render_app_architecture_premium`, `render_gpu_dashboard`, `render_gpu_metrics`, `render_gpu_sparkline` | 8 |
| **3D Visualization** | `render_3d_topology` — interactive Three.js 3D cluster topology returned as MCP `EmbeddedResource` (HTML) + auto-opens in browser | 1 |
| **Multi-Cluster** | `list_contexts`, `switch_context`, `multi_cluster_overview` | 3 |
| **Pod Exec** | `exec_command` | 1 |
| **Helm** | `helm_list`, `helm_get_values`, `helm_install`, `helm_uninstall` | 4 |
| **Cost Analysis** | `analyze_cost`, `rightsizing_report` | 2 |
| **OpenShift** | `openshift_detect`, `openshift_list_routes`, `openshift_list_projects`, `openshift_list_builds` | 4 |
| **ArgoCD** | `argocd_detect`, `argocd_list_apps`, `argocd_get_app`, `argocd_list_projects`, `argocd_app_history`, `argocd_sync_app`, `argocd_rollback_app`, `visualize_argocd` | 8 |
| **Flux CD** | `flux_detect`, `flux_list_sources`, `flux_list_kustomizations`, `flux_list_helmreleases`, `visualize_flux` | 5 |
| **Tekton** | `tekton_detect`, `tekton_list_pipelines`, `tekton_list_runs`, `tekton_list_tasks`, `visualize_tekton` | 5 |
| **GitOps Overview** | `visualize_gitops` — unified Mermaid diagram of all detected CD tools | 1 |
| **GPU / Accelerators** | `list_gpu_workloads`, `gpu_cluster_readiness`, `visualize_gpu_allocation`, `visualize_gpu_metrics`, `gpu_nvidia_smi`, `get_gpu_promql_reference` | 6 |
| **Observability** | `get_server_stats` (OpenTelemetry), `prometheus_query`, `loki_query` | 3 |
| **License** | `get_license_info`, `register_license` | 2 |

Further roadmap items (HTTP MCP transport, deeper GitOps) are in [docs/ROADMAP.md](docs/ROADMAP.md).

## Diagram & Visual Rendering

KubeCraft returns visual content using multiple MCP content types, with automatic browser fallback for clients that don't render visuals inline.

| Content | MCP response type | Inline rendering | Fallback |
|---|---|---|---|
| **PNG diagrams** (`render_*`) | `ImageContent` (base64 PNG) | Cursor renders inline | Auto-opens saved PNG in default viewer; also saved to `KUBECRAFT_OUTPUT_DIR` |
| **3D topology** (`render_3d_topology`) | `EmbeddedResource` (base64 HTML, `text/html`) | Future clients that support `EmbeddedResource` | Auto-opens HTML in default browser; also saved to `KUBECRAFT_OUTPUT_DIR` or temp dir |
| **Mermaid text** (`visualize_*`) | `TextContent` (markdown) | Cursor + Claude Desktop render natively | Copy Mermaid block to any Mermaid renderer |

**Auto-open behavior:** When `KUBECRAFT_OUTPUT_DIR` is configured and writable, rendered PNGs and 3D HTML files are saved to disk and automatically opened in the user's default browser or image viewer. Inside Docker containers, auto-open works only when the container can reach the host display (e.g. via X11 forwarding or host networking); otherwise, open the saved files from the host-mounted output directory.

## Kubernetes Distribution Compatibility

KubeCraft uses the standard Kubernetes Python client and communicates directly with the K8s API server — no kubectl or other CLI wrappers required.

| Distribution | Status | Notes |
|---|---|---|
| **Vanilla K8s / KinD** | Fully supported | Primary dev/test target |
| **Amazon EKS** | Fully supported | kubeconfig via `aws eks update-kubeconfig` |
| **Azure AKS** | Fully supported | kubeconfig via `az aks get-credentials` |
| **Google GKE** | Fully supported | kubeconfig via `gcloud container clusters get-credentials` |
| **Canonical K8s / MicroK8s** | Fully supported | CNCF certified, standard APIs |
| **k3s / Rancher** | Fully supported | Lightweight but fully conformant |
| **Red Hat OpenShift** | Fully supported | Standard K8s tools + OCP-specific tools for Routes, Projects, BuildConfigs |

## Quick Start

### Build the Docker image

```bash
docker build -t kubecraft-mcp:latest .
```

### Configure in Cursor

Create or edit `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "kubecraft": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--network=host",
        "-v", "/home/<user>/.kube:/home/mcp/.kube:ro",
        "-e", "KUBECONFIG=/home/mcp/.kube/config",
        "kubecraft-mcp:latest"
      ]
    }
  }
}
```

**Windows (WSL kubeconfig):**

```json
{
  "mcpServers": {
    "kubecraft": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "C:\\Users\\<user>\\.kube:/home/mcp/.kube:ro",
        "-e", "KUBECONFIG=/home/mcp/.kube/config",
        "kubecraft-mcp:latest"
      ]
    }
  }
}
```

**3D topology viewer (HTTP link):** The **Viewer URL** works only while the Kubecraft process is running. If you run a one-off `python -c` locally, the server exits immediately and the link will show **connection refused**. On **Docker Desktop** (Windows/macOS), `--network=host` does not publish the container's loopback to your host browser like it does on Linux; prefer opening the saved **HTML file** from `KUBECRAFT_OUTPUT_DIR`, or publish a fixed port, for example add to `args`: `"run", "--rm", "-i", "-p", "8765:8765",` plus `-e`, `KUBECRAFT_VIEWER_BIND=0.0.0.0:8765`, `-e`, `KUBECRAFT_VIEWER_EXPOSE=1`, then use `http://127.0.0.1:8765` plus the path from the tool output (copy it exactly; the token is case-sensitive).

### Configure in Claude Desktop

Claude Desktop doesn't render MCP `ImageContent` or `EmbeddedResource` inline, so diagrams are saved to a shared folder on your machine and **automatically opened in your default browser/viewer**. Open (or create)
`%APPDATA%\Claude\claude_desktop_config.json` (Windows) or
`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

**Windows:**

```json
{
  "mcpServers": {
    "kubecraft": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--network=host",
        "-v", "C:\\Users\\<user>\\.kube:/home/mcp/.kube:ro",
        "-v", "C:\\Users\\<user>\\kubecraft-diagrams:/output",
        "-e", "KUBECONFIG=/home/mcp/.kube/config",
        "-e", "KUBECRAFT_OUTPUT_DIR=/output",
        "kubecraft-mcp:latest"
      ]
    }
  }
}
```

Rendered PNG diagrams and 3D topology HTML files will appear in `C:\Users\<user>\kubecraft-diagrams\` and auto-open in your browser.

**macOS / Linux:**

```json
{
  "mcpServers": {
    "kubecraft": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--network=host",
        "-v", "/home/<user>/.kube:/home/mcp/.kube:ro",
        "-v", "/home/<user>/kubecraft-diagrams:/output",
        "-e", "KUBECONFIG=/home/mcp/.kube/config",
        "-e", "KUBECRAFT_OUTPUT_DIR=/output",
        "kubecraft-mcp:latest"
      ]
    }
  }
}
```

### Configure in Claude Code

```bash
claude mcp add kubecraft \
  -- docker run --rm -i --network=host \
  -v ~/.kube:/home/mcp/.kube:ro \
  -e KUBECONFIG=/home/mcp/.kube/config \
  kubecraft-mcp:latest
```

## Built-in Chat UI (Web mode)

KubeCraft ships with a full React/TypeScript chat UI bundled in the same Docker image. It exposes the entire 115-tool surface as a conversational interface backed by your choice of LLM (Claude, OpenAI, or Azure OpenAI) — the LLM decides when to call MCP tools and the UI streams the results back with markdown, embedded PNG diagrams, and an interactive 3D topology viewer.

### Pages

- **Chat** — streaming conversation with expandable tool-invocation cards, image/HTML embedding, kubeconfig context switcher in the header. Per-message **Copy** and **Edit** actions (hover any message); **Suggestions** picker right next to the input opens a searchable popover of the full template library.
- **Templates** — curated catalog of **159 prompt templates** spanning all 27 tool categories. Sidebar filter by category, full-text search across title / prompt / tool name / tags. Click **Use** to drop a template into the chat input.
- **Saved** — bookmark your own reusable questions; one click sends them to chat.
- **History** — every past conversation, resumable.
- **Audit** — every MCP tool call ever executed (compliance trail).
- **Settings** — provider config, license registration, full tool inventory.

### Compliance reporting

KubeCraft's `generate_compliance_report` tool produces audit-ready PDF and Word documents mapped to the major compliance frameworks. Run it from chat with one prompt like *"Generate a SOC 2 compliance audit report and export PDF + Word"*.

**Frameworks supported:**

| Framework | Mapping |
|---|---|
| **CIS Kubernetes Benchmark v1.9** | Direct control-ID mapping (5.1.x RBAC, 5.2.x PSS, 5.3.x networking, 5.4.x secrets, etc.) |
| **SOC 2 Trust Service Criteria** | CC6.x logical access · CC7.x system operations · CC8.x change management |
| **ISO 27001:2022** | Annex A (A.5 access control · A.8 operations / cryptography / network security) |
| **NIST 800-53 Rev. 5** | AC, AU, CM, IA, RA, SC, SI control families |
| **PCI-DSS v4.0** | Req 1, 2, 6, 7, 8, 10 |
| **HIPAA Security Rule** | §164.312 Technical Safeguards (a) Access · (b) Audit · (c) Integrity · (e) Transmission |
| **comprehensive** | All of the above in one report — every finding lists its mapping in each framework |

**What the report contains:**

1. **Executive summary** — color-coded status counts + a 0-100 compliance score with interpretation
2. **Findings summary table** — every control with status, control ID, and one-line summary
3. **Detailed findings** — per-control: status, evidence excerpt, cross-framework mappings, remediation guidance
4. **Methodology** — which tools were used to gather evidence, which findings need manual review

**Evidence sources** (run automatically, read-only):

`inspect_rbac` · `summarize_pod_security_standards` · `analyze_network_reachability` · `find_unprotected_workloads` · `audit_secret_hygiene` · `summarize_image_vulnerabilities` · `scan_deprecations` · `audit_ingress_tls` · `audit_loadbalancers` · `get_node_health` · `list_pod_disruption_budgets`

**Multi-cluster:** Set `multi_cluster=true` to loop over every kubeconfig context and produce one combined report — each finding is prefixed with the originating cluster name.

**Output:** Files are saved under `KUBECRAFT_OUTPUT_DIR/compliance/` as `kubecraft-compliance-{framework}-{timestamp}.{md,pdf,docx}`. When the web UI is running, the chat response includes a **Download** link served by `/api/v1/files/...` (path-traversal protected, scoped to the output dir).

> **Note:** This is an *evidence-aggregation* tool, not a substitute for a qualified auditor. Findings flagged 🔍 *manual review* require human verification (e.g., kube-apiserver flags, organizational controls outside the cluster).

### Output beautification

Assistant replies and tool outputs are rendered with **GitHub-flavored markdown**, including:

- **Mermaid diagrams** — fenced ` ```mermaid ` blocks (returned by `visualize_*` tools) are rendered as interactive SVG with a toolbar: **Copy source**, **Copy as PNG**, **Download PNG**, **Toggle source**, **Fullscreen**. Mermaid is lazy-loaded so the bundle stays slim for users who never see a diagram.
- **PNG renders** — every `render_*` tool output (cluster topology, namespace, network, app architecture, premium architecture, GPU dashboard / metrics / sparkline) gets the same toolbar: **Copy PNG**, **Download**, **Open in new tab**, **Fullscreen**. Click the image to open it fullscreen; click the backdrop or press Esc to dismiss.
- **3D HTML topology** (`render_3d_topology`) gets a matching panel: **Open viewer** (in-page iframe overlay), **New tab** (standalone Blob URL), **Download** (`.html` file), **Copy** (HTML source). Includes a size readout (e.g. "342 KB · self-contained Three.js HTML").
- Syntax-highlighted fenced code blocks (highlight.js, common-language bundle)
- Per-codeblock **Copy** button on hover
- JSON auto-pretty-print when fenced as ` ```json `
- Wide tables with sticky headers + horizontal scroll wrapper
- Status emojis (`✅ ❌ ⚠️ 🟢 🟡 🔴 ⏳`) automatically rendered as tinted chips for fast scanning

### Run web mode

**Linux / WSL2 (recommended — uses host networking so the container can reach `127.0.0.1` clusters like kind/k3d/minikube):**

```bash
docker run --rm --network=host \
  -v ~/.kube:/home/mcp/.kube:ro \
  -e KUBECONFIG=/home/mcp/.kube/config \
  -e KUBECRAFT_MODE=http \
  -e KUBECRAFT_LLM_PROVIDER=anthropic \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  kubecraft-mcp:latest
```

Open `http://localhost:8080`.

**Docker Desktop (Windows / macOS — `--network=host` is a no-op there; use `host.docker.internal` to reach a localhost cluster):**

```bash
docker run --rm -p 8080:8080 --add-host=host.docker.internal:host-gateway \
  -v ~/.kube:/home/mcp/.kube:ro \
  -e KUBECONFIG=/home/mcp/.kube/config \
  -e KUBECRAFT_MODE=http \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  kubecraft-mcp:latest
```

Then **rewrite your kubeconfig** to use `host.docker.internal` instead of `127.0.0.1` for the cluster URL — see [Troubleshooting](#kubernetes-api-server-unreachable-connection-refused) below.

The same image still runs MCP stdio mode by default — `KUBECRAFT_MODE=http` (or `--http`) opts into the web UI.

### Provider configuration

| Provider | Env vars |
|---|---|
| **Anthropic Claude** (default) | `KUBECRAFT_LLM_PROVIDER=anthropic` · `ANTHROPIC_API_KEY` · optional `KUBECRAFT_LLM_MODEL` (default `claude-sonnet-4-6`; other options: `claude-opus-4-7`, `claude-haiku-4-5-20251001`) |
| **OpenAI** | `KUBECRAFT_LLM_PROVIDER=openai` · `OPENAI_API_KEY` · optional `KUBECRAFT_LLM_MODEL` (default `gpt-4o`) |
| **Azure OpenAI** | `KUBECRAFT_LLM_PROVIDER=azure-openai` · `AZURE_OPENAI_KEY` · `AZURE_OPENAI_ENDPOINT` · `AZURE_OPENAI_DEPLOYMENT` · optional `AZURE_OPENAI_API_VERSION` |

The Settings page shows whether the active provider is configured and lists every supported provider.

### Tool surface limits per provider

KubeCraft exposes 130+ tools, but **OpenAI and Azure OpenAI cap `tools` at 128 entries per request** (Anthropic has no practical limit). KubeCraft handles this transparently with a smart **tool selector** ([kubecraft_mcp/llm/tool_selector.py](kubecraft_mcp/llm/tool_selector.py)):

1. **Anthropic** — receives every tool, every turn. No filtering.
2. **OpenAI / Azure OpenAI** — receives a relevant subset of ≤128 tools per turn, chosen by:
   - **Always-include core** (~15 tools): cluster discovery, diagnostics, `apply_manifest`, etc.
   - **Category routing**: keyword classifier on your most recent prompt + last few user messages → matches against a tool/category map.
   - **Priority padding**: any remaining slots are filled by global priority order (most universally useful tools first).

You'll see the selected count in the server log on every turn (e.g. `Tool subset for openai: 128/130 tools`). If the LLM ever says it can't find a tool you expected, rephrase with stronger keywords ("audit my **RBAC** for risky bindings" rather than "check permissions") to surface the right category.

### Develop the UI locally

The UI lives at [ui/](ui/) inside this repo (not a separate project). For local dev:

```bash
# Terminal 1 — Python backend
KUBECRAFT_MODE=http ANTHROPIC_API_KEY=... python -m kubecraft_mcp

# Terminal 2 — Vite dev server (proxies /api/* to :8080)
cd ui && npm install && npm run dev
# → http://localhost:5173
```

For production builds, the Dockerfile bundles `npm run build` output into `/app/ui/dist`, served by FastAPI under `/`. No separate dev server needed.

### Environment Variables

| Variable | Description |
|---|---|
| `KUBECONFIG` | Path to kubeconfig file |
| `KUBECRAFT_OUTPUT_DIR` | Directory for saving diagrams and 3D HTML files. Saved files are auto-opened in the default browser/viewer. Pre-created as `/output` inside the container image |
| `KUBECRAFT_VIEWER_BIND` | Optional bind for built-in 3D viewer URL. Loopback: `127.0.0.1:0`, `localhost:0`, `::1:0`. With `KUBECRAFT_VIEWER_EXPOSE=1`, also `0.0.0.0:PORT` (for `docker run -p host:port`) |
| `KUBECRAFT_VIEWER_EXPOSE` | Set to `1` to allow binding `0.0.0.0` so Docker port publishing works. The viewer still uses unguessable URLs; avoid on hostile networks without firewall rules |
| `KUBECRAFT_CPU_HOUR_RATE` | Cost analysis CPU rate (default: $0.031/vCPU-hr) |
| `KUBECRAFT_MEM_GIB_HOUR_RATE` | Cost analysis memory rate (default: $0.004/GiB-hr) |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OpenTelemetry OTLP endpoint for trace export |
| `ARGOCD_SERVER` | ArgoCD server URL for sync/rollback actions (e.g. `https://argocd.example.com`) |
| `ARGOCD_TOKEN` | ArgoCD API token for authenticated REST operations |
| `KUBECRAFT_PROMETHEUS_URL` | Prometheus base URL for `prometheus_query`, `visualize_gpu_metrics`, `render_gpu_metrics`, `render_gpu_sparkline` (e.g. `https://prometheus.example.com`) |
| `KUBECRAFT_PROMETHEUS_TOKEN` | Optional Bearer token for Prometheus |
| `KUBECRAFT_PROMETHEUS_USER` / `KUBECRAFT_PROMETHEUS_PASSWORD` | Optional basic auth for Prometheus (used instead of token when both are set) |
| `KUBECRAFT_LOKI_URL` | Loki base URL for `loki_query` (e.g. `https://loki.example.com`) |
| `KUBECRAFT_LOKI_TOKEN` | Optional Bearer token for Loki |
| `KUBECRAFT_LOKI_USER` / `KUBECRAFT_LOKI_PASSWORD` | Optional basic auth for Loki |
| `KUBECRAFT_LOKI_ORG_ID` | Optional `X-Scope-OrgID` header for multi-tenant Loki |
| `KUBECRAFT_LICENSE_KEY` | License key (overrides file-based license) |
| `KUBECRAFT_EMAIL` | Email address for license registration |
| `KUBECRAFT_MODE` | `stdio` (default — MCP) or `http` (web UI on port 8080). Equivalent to passing `--http` |
| `KUBECRAFT_HTTP_HOST` | Bind address for web mode (default `0.0.0.0`) |
| `KUBECRAFT_HTTP_PORT` | Port for web mode (default `8080`) |
| `KUBECRAFT_INSTANCE_NAME` | Optional label shown in the UI header to distinguish multiple deployments |
| `KUBECRAFT_LLM_PROVIDER` | `anthropic` (default), `openai`, or `azure-openai` |
| `KUBECRAFT_LLM_MODEL` | Override the default model for the active provider |
| `ANTHROPIC_API_KEY` | API key for Anthropic Claude provider |
| `ANTHROPIC_BASE_URL` | Optional Anthropic API base URL (proxies, mirrors) |
| `OPENAI_API_KEY` | API key for OpenAI provider |
| `OPENAI_BASE_URL` | Optional OpenAI base URL (compatible endpoints, proxies) |
| `AZURE_OPENAI_KEY` / `AZURE_OPENAI_ENDPOINT` / `AZURE_OPENAI_DEPLOYMENT` / `AZURE_OPENAI_API_VERSION` | Azure OpenAI configuration (deployment-based; `KUBECRAFT_LLM_MODEL` falls back to the deployment name) |
| `KUBECRAFT_CORS_ORIGINS` | Comma-separated CORS allow-list for web mode (default `http://localhost:5173` for Vite dev). Production same-origin deploys can ignore |

## Project Structure

```
kubecraft-mcp-server/
├── Dockerfile
├── pyproject.toml
├── kubecraft_mcp/
│   ├── server.py              # MCP server entry point (140 tools)
│   ├── licensing.py           # 30-day trial + commercial license management
│   ├── observability.py       # OpenTelemetry tracing + server stats
│   ├── k8s/
│   │   ├── client.py          # Kubernetes API client wrapper
│   │   ├── formatters.py      # Resource formatting utilities
│   │   ├── mermaid.py         # Mermaid diagram generation
│   │   ├── metrics_backend.py # Prometheus/Loki query backend
│   │   ├── renderer.py        # Pillow-based PNG dashboard renderer
│   │   ├── topology_3d.py     # Three.js 3D topology viewer + auto-open
│   │   ├── gpu_utils.py       # GPU extended-resource detection helpers
│   │   ├── gpu_renderer.py    # Pillow PNG dashboards for GPU allocation / metrics
│   │   └── logo_gen.py        # Programmatic KubeCraft logo generator
│   └── tools/
│       ├── cluster.py         # Cluster-level tools
│       ├── cleanup.py         # Unused resource cleanup report
│       ├── cost.py            # Cost analysis and rightsizing
│       ├── deprecation.py     # API deprecation scanner
│       ├── diagnostics.py     # Pod diagnostics and logs
│       ├── exec.py            # Pod exec (command execution)
│       ├── gateway_api.py     # Gateway API (HTTPRoute, GRPCRoute)
│       ├── gpu.py             # GPU workloads, readiness, Prometheus, nvidia-smi
│       ├── health.py          # Composite cluster health score
│       ├── helm.py            # Helm integration
│       ├── management.py      # Scale, restart, cordon, apply
│       ├── multicluster.py    # Multi-cluster context management
│       ├── openshift.py       # OpenShift-specific tools
│       ├── platform_posture.py # Storage, cert-manager, NetworkPolicy, endpoints
│       ├── policy_budgets.py  # PodDisruptionBudget listing
│       ├── policy_engines.py  # Kyverno / Gatekeeper policy summaries
│       ├── rbac_inspector.py  # RBAC role/binding inspection
│       ├── access_control.py  # RBAC YAML generators: grant_namespace_access, grant_resource_access, revoke_access
│       ├── compliance.py      # Compliance audit report generator (CIS/SOC2/ISO27001/NIST/PCI/HIPAA → Markdown/PDF/DOCX)
│       ├── operators.py       # CRD & operator essentials (10 tools)
│       ├── ingress_audit.py   # Per-Ingress endpoint health + TLS cert decoding
│       ├── network_advanced.py # IngressClasses, service mesh, CNI, CoreDNS, reachability + Mermaid graph + pod reachability simulator
│       ├── render.py          # Image rendering (PNG + 3D HTML + auto-open)
│       ├── resources.py       # Resource listing and describe
│       ├── security_posture.py # PSS, SA audit, image vulns, secret hygiene
│       ├── storage_advanced.py # CSI drivers, VolumeSnapshots, storage capacity
│       ├── visualization.py   # Mermaid text diagram tools
│       ├── wave3_observability.py # Prometheus and Loki query tools
│       ├── workloads.py       # DaemonSet, StatefulSet, CronJob/Job, disruption
│       ├── argocd.py          # ArgoCD integration (CRD + REST API)
│       ├── flux.py            # Flux CD integration (CRD-based)
│       └── tekton.py          # Tekton CI/CD integration (CRD-based)
├── kubecraft_mcp/llm/         # Multi-provider LLM bridge (web mode)
│   ├── base.py                # Provider ABC + streaming event types
│   ├── tool_bridge.py         # MCP tool → Anthropic/OpenAI tool_use translation
│   ├── anthropic_provider.py  # Claude (default) — drives the tool_use loop
│   ├── openai_provider.py     # OpenAI function calling
│   └── azure_provider.py      # Azure OpenAI (deployment-based)
├── kubecraft_mcp/web/         # FastAPI HTTP/SSE server bundled with the chat UI
│   ├── app.py                 # FastAPI factory + uvicorn entry point
│   ├── storage.py             # SQLite (sessions, messages, audit, saved)
│   ├── tool_runner.py         # Async wrapper that executes any registered MCP tool
│   ├── static.py              # Serves the built UI from /app/ui/dist
│   ├── templates_data.py      # Curated template library (159 prompts × 27 categories)
│   └── routes/
│       ├── chat.py            # POST /api/v1/ask (SSE streaming + tool orchestration)
│       ├── sessions.py        # Session CRUD
│       ├── config.py          # /api/v1/config (provider, instance metadata)
│       ├── audit.py           # /api/v1/audit (tool invocation log)
│       ├── saved.py           # Saved questions + suggested-questions starter prompts
│       ├── templates.py       # /api/v1/templates (curated library)
│       ├── files.py           # /api/v1/files (download exported reports / artifacts)
│       └── kubecraft.py       # /api/v1/contexts, /api/v1/license, /api/v1/tools
├── kubecraft_mcp/__main__.py  # Dispatcher: stdio (default) | http (KUBECRAFT_MODE=http)
├── ui/                        # React/TypeScript chat UI (Vite + Tailwind + Zustand)
│   ├── src/
│   │   ├── App.tsx            # Routes: /chat, /templates, /saved, /history, /audit, /settings
│   │   ├── pages/             # ChatPage, TemplatesPage, SavedPage, HistoryPage, AuditPage, SettingsPage
│   │   ├── components/        # Header, MessageCard, MarkdownView (highlight.js), ToolInvocationCard, SuggestionsPicker, ContextPicker, CopyButton
│   │   ├── store/chat.ts      # Zustand chat store with streaming reducers
│   │   └── lib/{api,stream,format,copy,icons}.ts(x)
│   ├── package.json
│   ├── vite.config.ts         # Proxies /api/* → :8080 in dev
│   └── tailwind.config.js     # KubeCraft brand palette
└── .cursor/
    └── mcp.json               # Cursor MCP configuration
```

## Troubleshooting

### Windows: "Permission denied" on `/output` (diagrams not saved)

If you see warnings like `Permission denied: '/output/index.html'` in the MCP server logs, diagrams still work inline but the optional file-save to your host directory fails. This is a Docker Desktop volume-mount permissions issue.

**Fix:** Ensure the host directory exists *before* starting the container:

```powershell
mkdir C:\Users\<user>\kubecraft-diagrams
```

Then confirm your config maps it correctly:

```json
"-v", "C:\\Users\\<user>\\kubecraft-diagrams:/output"
```

If the error persists, check that Docker Desktop has file-sharing access to the drive (Settings → Resources → File sharing). Alternatively, use a named Docker volume:

```json
"-v", "kubecraft-output:/output"
```

> **Note:** Diagrams are always returned inline via MCP regardless of whether the file-save succeeds. The file-save is a convenience for hosts like Claude Desktop that don't render MCP images natively.

### Diagrams don't auto-open in browser

Auto-open uses `webbrowser.open()` which requires the container to reach the host display. Inside Docker, this only works with X11 forwarding or host networking on Linux. On Windows/macOS Docker Desktop, open the saved files from your host-mounted `KUBECRAFT_OUTPUT_DIR` directory instead, or use the dashboard at `<KUBECRAFT_OUTPUT_DIR>/index.html` (auto-refreshes every 5 seconds).

### Kubernetes API server unreachable (connection refused)

If tools fail with errors like:

```
HTTPSConnectionPool(host='127.0.0.1', port=53842): Max retries exceeded ...
[Errno 111] Connection refused
```

…the cause is that your kubeconfig points to a **localhost** endpoint on the host (typical for **kind**, **k3d**, **minikube**, or `kubectl proxy`), but inside the container `127.0.0.1` is the container's own loopback — which has nothing listening.

**Diagnose first:**

```bash
kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}'
# → e.g. https://127.0.0.1:53842   ← that's the smoking gun
```

**Fix on Linux / WSL2 — use host networking:**

```bash
docker run --rm --network=host -e KUBECRAFT_MODE=http ... kubecraft-mcp:latest
```

`--network=host` shares the container's network namespace with the host so `127.0.0.1:53842` resolves correctly. Note: with `--network=host` you don't need `-p 8080:8080` (and Docker will reject combining the two).

**Fix on Docker Desktop (Windows / macOS) — `--network=host` is a no-op:**

> ⚠️ **TLS gotcha:** kind/k3d/minikube apiserver certificates have SANs only for `127.0.0.1`, `localhost`, and `kubernetes`. After rewriting the URL to `host.docker.internal`, Python rejects the cert with `SSL: CERTIFICATE_VERIFY_FAILED — Hostname mismatch`. You must therefore also disable TLS verification in the **container-only** kubeconfig copy. This is acceptable for local dev because these certs are self-signed anyway — but never do it for production clusters.

1. Add the host-gateway alias when you `docker run`:

   ```bash
   docker run --rm -p 8080:8080 --add-host=host.docker.internal:host-gateway ...
   ```

2. Make a **container-only kubeconfig copy** that rewrites the URL **and** turns off TLS verification:

   ```bash
   # On the host:
   sed -e 's|https://127\.0\.0\.1:|https://host.docker.internal:|' \
       -e '/certificate-authority-data:/d' \
       ~/.kube/config > ~/.kube/config.docker
   sed -i 's|^\(\s*\)server: https://host.docker.internal|\1insecure-skip-tls-verify: true\n\1server: https://host.docker.internal|' \
       ~/.kube/config.docker
   ```

3. Mount the rewritten file:

   ```bash
   docker run --rm -p 8080:8080 --add-host=host.docker.internal:host-gateway \
     -v ~/.kube/config.docker:/home/mcp/.kube/config:ro \
     -e KUBECRAFT_MODE=http -e ANTHROPIC_API_KEY=... \
     kubecraft-mcp:latest
   ```

> 💡 **WSL2 users: skip this section.** WSL2's Docker engine supports `--network=host` natively — use the Linux fix above. You keep proper TLS verification and your kubeconfig stays untouched.

**Fix for remote clusters (EKS / AKS / GKE / OpenShift):**

These already have routable hostnames, so this issue only affects local clusters. If you see it against a remote cluster, check whether your kubeconfig has been overridden by a `kubectl proxy` session.

## Requirements

- Docker
- A kubeconfig with access to your target cluster
- Cursor, Claude Desktop, Claude Code, or any MCP-compatible AI assistant

## License

KubeCraft MCP Server is a commercial product by [CloudCraft Labs](https://www.cloudcraftlabs.io).

- **30-day free trial** — no credit card required
- **$200/year** after trial — one license, unlimited clusters
- Use `get_license_info` and `register_license` tools to manage your license