kubeview-mcp 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.7.0] - 2026-02-17
+
+### Added
+- **feat(helm): add API-first backend support for Helm commands**
+- **feat(helm): add CLI fallback support for Helm v4 commands**
+
+### Changed
+- **Refactor CLI run-command.js to simplify Kubernetes and Helm tool class handling**
+
+
 ## [1.6.0] - 2026-02-04
 
 ### Changed

package/README.md

@@ -14,7 +14,7 @@ Learn more about the benefits of code mode and implementation in [Evicting MCP t
 - **🧠 Code Mode**: Sandboxed TypeScript environment for complex reasoning and multi-step workflows.
 - **🛡️ Read-Only & Safe**: Designed for production safety with zero write access and sensitive data masking.
 - **☸️ Kubernetes Integration**: List/get resources, fetch metrics, stream logs and events, execute commands, and tools to diagnose network issues.
-- **📦 Helm Support**: Inspect releases, values, manifests, and history.
+- **📦 Helm Support (API-first)**: Inspect releases, values, manifests, and history via Kubernetes API first, with the CLI fallback.
 - **🐙 Argo Ecosystem**: Manage Argo Workflows and Argo CD applications using direct Kubernetes API or CLI.
 
 ---
@@ -33,7 +33,7 @@ Learn more about the benefits of code mode and implementation in [Evicting MCP t
 
 - Node.js ≥ 18
 - Access to a Kubernetes cluster
-- Optionally, CLIs installed in current $PATH: `helm`, `argo`, `argocd`
+- Optionally, CLIs installed in current $PATH: `helm` (fallback only), `argo`, `argocd`
 
 ### Installation
 
@@ -64,18 +64,19 @@ Add to your `mcpServers` configuration (e.g., in Cursor or Claude Desktop):
 
 Configure the server using environment variables:
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `KUBECONFIG` | Path to kubeconfig file | `~/.kube/config` |
-| `MCP_MODE` | Server mode: `all`, `code`, or `tools` | `all` |
-| `MCP_LOG_LEVEL` | Log level (`error`, `warn`, `info`, `debug`) | `info` |
-| `MCP_HIDE_SENSITIVE` | Enable global sensitive data masking | `false` |
+| Variable             | Description                                  | Default          |
+| -------------------- | -------------------------------------------- | ---------------- |
+| `KUBECONFIG`         | Path to kubeconfig file                      | `~/.kube/config` |
+| `MCP_MODE`           | Server mode: `all`, `code`, or `tools`       | `all`            |
+| `MCP_LOG_LEVEL`      | Log level (`error`, `warn`, `info`, `debug`) | `info`           |
+| `MCP_HIDE_SENSITIVE` | Enable global sensitive data masking         | `false`          |
 
 ---
 
 ## 🛠️ Tools Overview
 
 ### Kubernetes
+
 - **`kube_list`**: List resources or get cluster diagnostics.
 - **`kube_get`**: Describe specific resources (supports all K8s types).
 - **`kube_metrics`**: Fetch CPU/memory metrics for nodes and pods.
@@ -85,14 +86,25 @@ Configure the server using environment variables:
 - **`kube_net`**: Run in-cluster network diagnostics.
 
 ### Helm
-- **`helm_list`**: List Helm releases.
-- **`helm_get`**: Fetch release values, manifests, and history.
+
+- **`helm_list`**: List Helm releases (Kubernetes API first, CLI fallback).
+- **`helm_get`**: Fetch release values, manifests, notes, hooks, resources, status, and history (Kubernetes API first, CLI fallback).
+
+### Helm Execution Strategy
+
+- Helm tools are **API-first by default** and read Helm release metadata from Kubernetes storage backends (Secrets and ConfigMaps).
+- Helm CLI is retained as a compatibility fallback path.
+- In normal read-only scenarios with Kubernetes API access, Helm operations do not require the `helm` binary.
+- If Helm is configured with a non-Kubernetes storage backend (for example SQL), CLI fallback may be required.
+- For `helm_get`/`helm_list`, JSON/default behavior uses API first; non-JSON formatting may use CLI fallback.
 
 ### Argo
+
 - **`argo_list` / `argo_get`**: Manage Argo Workflows.
 - **`argocd_app`**: Inspect Argo CD applications and resources.
 
 ### Utilities
+
 - **`run_code`**: Execute sandboxed TypeScript code for complex tasks.
 - **`plan_step`**: Record step-by-step planning state for long, complex investigations.
 
@@ -138,6 +150,7 @@ Simply type `/kubeview/code-mode` in the prompt (or select it from the `/` promp
 ## 💻 Local Development
 
 1. **Clone & Install**:
+
    ```bash
    git clone https://github.com/mikhae1/kubeview-mcp.git
    cd kubeview-mcp
@@ -145,6 +158,7 @@ Simply type `/kubeview/code-mode` in the prompt (or select it from the `/` promp
    ```
 
 2. **Build & Run**:
+
    ```bash
    npm run build
    npm start

package/SKILL.md

@@ -1,76 +1,81 @@
-# KubeView MCP Skills: Debugging Kubernetes Clusters
+---
+name: kubeview-debug
+description: Debug and diagnose Kubernetes clusters using KubeView MCP server tools. Use when investigating cluster issues (pod crashes, deployment failures, service connectivity problems, node issues, resource constraints), performing cluster health checks, or troubleshooting any Kubernetes workload. Trigger phrases include "cluster health", "pod won't start", "CrashLoopBackOff", "service unreachable", "deployment stuck", "node pressure", "OOMKilled", "ImagePullBackOff".
+---
+
+# Kubernetes Cluster Debugging
 
-This document contains reusable investigation playbooks ("skills") for debugging Kubernetes clusters using the KubeView MCP server.
+Reusable investigation playbooks for debugging Kubernetes clusters using KubeView MCP.
 
-## Assumptions & Constraints
+## Core Principles
 
-- **Read-Only by Design**: Avoid making state changes (edit, delete, scale) through these tools unless explicitly authorized.
-- **Documentation**: Use `search_tools` to find new capabilities.
-- **Prefer MCP Tools**: Use `kube_*` tools over shelling out to `kubectl`.
+- **Read-Only**: Avoid state changes unless explicitly authorized.
+- **Prefer MCP Tools**: Use `kube_*` tools over `kubectl` commands.
 - **Security First**: Treat output as potentially sensitive.
-- **Declarative over Imperative**: When suggesting fixes, provide YAML snippets rather than `kubectl patch/edit` commands.
+- **Declarative Fixes**: Provide YAML snippets rather than imperative `kubectl` commands.
 
-## Tool Quick Map
+## Tool Quick Reference
 
-- **Cluster + Workloads**: `kube_list`, `kube_get`, `kube_metrics`
+- **Cluster & Workloads**: `kube_list`, `kube_get`, `kube_metrics`
 - **Logs**: `kube_logs` (single pod), `kube_log` (multi-pod with filters + events)
 - **Network**: `kube_net`, `kube_exec`, `kube_port`
 - **Discovery**: `search_tools` (tools-mode), `run_code` (code-mode)
 
-In code-mode (`run_code`), these become `tools.kubernetes.*` (e.g., `tools.kubernetes.list`).
-
----
+In code-mode, tools become `tools.kubernetes.*` (e.g., `tools.kubernetes.list`).
 
 ## Debugging Decision Tree
 
 ```
 Issue reported
     │
-    ├─ Pod not running? ──────────► See: Debug a Pod that Won't Start
+    ├─ Pod not running? ──────────► Skill: Debug Pod Failures
     │
-    ├─ Service unreachable? ──────► See: Debug a Service With No Traffic
+    ├─ Service unreachable? ──────► Skill: Debug Service Connectivity
     │
-    ├─ Deployment stuck? ─────────► See: Debug a Deployment
+    ├─ Deployment stuck? ─────────► Skill: Debug Deployment Rollout
     │
-    ├─ Node issues? ──────────────► See: Node Debugging
+    ├─ Node issues? ──────────────► Skill: Node Debugging
     │
-    └─ Performance/Resources? ────► See: Resource Debugging
+    └─ Performance/Resources? ────► Skill: Resource Debugging
 ```
 
 ---
 
-## Skill: Cluster Triage (fast)
+## Skill: Cluster Triage
 
-**Intent**: Get a high-signal overview and decide where to drill down next.
+**When**: Get high-level cluster health overview, identify problem areas.
 
-**Procedure**:
+**Trigger**: "cluster health", "triage the cluster", "what's wrong"
 
-1. **Cluster overview (diagnostics)**
+**Steps**:
+
+1. **Cluster diagnostics**
    ```json
    { "tool": "kube_list", "args": {} }
    ```
 
-2. **Metrics + diagnostics**
+2. **Metrics + top consumers**
    ```json
    { "tool": "kube_metrics", "args": { "diagnostics": true, "includeSummary": true, "topN": 5 } }
    ```
 
-3. **Identify "Worst" Namespaces** (if not obvious)
-   - Look for high counts of `CrashLoopBackOff` or `Pending`.
-   - List pods in that namespace:
+3. **Drill into problem namespaces**
+   - Identify namespaces with high `CrashLoopBackOff` or `Pending` counts
    ```json
    { "tool": "kube_list", "args": { "namespace": "<ns>" } }
    ```
 
 ---
 
-## Skill: Debug a Pod that Won't Start / CrashLoop
+## Skill: Debug Pod Failures
+
+**When**: Pod is Pending, CrashLoopBackOff, ImagePullBackOff, or OOMKilled.
 
-**Intent**: Identify why a pod is Pending / CrashLoopBackOff / ImagePullBackOff / OOMKilled.
+**Trigger**: "pod won't start", "CrashLoopBackOff", "ImagePullBackOff", "OOMKilled"
 
-**Procedure**:
+**Steps**:
 
-1. **Describe the pod with events + diagnostics**
+1. **Describe pod with events**
    ```json
    {
      "tool": "kube_get",
@@ -84,7 +89,7 @@ Issue reported
    }
    ```
 
-2. **Pull logs (current & previous)**
+2. **Check logs (current & previous)**
    ```json
    {
      "tool": "kube_logs",
@@ -92,28 +97,25 @@ Issue reported
    }
    ```
 
-3. **Common Pod Issues Checklist**:
+3. **Common causes**:
    - **CrashLoopBackOff**:
-     - Exit Code 1: App error (check logs).
-     - Exit Code 137: OOMKilled (check memory limits vs usage).
-     - Exit Code 143: Graceful termination timeout or SIGTERM.
-   - **ImagePullBackOff**:
-     - Check image name/tag spelling.
-     - Check ImagePullSecrets (registry auth).
-   - **Pending**:
-     - Insufficient CPU/Memory (Cluster full?).
-     - Unsatisfiable Node Affinity/Selector.
-     - PVC binding failure.
+     - Exit 1: App error (check logs)
+     - Exit 137: OOMKilled (memory limit too low)
+     - Exit 143: SIGTERM timeout
+   - **ImagePullBackOff**: Check image name/tag, verify ImagePullSecrets
+   - **Pending**: Insufficient resources, node affinity issues, or PVC binding failure
 
 ---
 
-## Skill: Debug a Deployment / Rollout Not Progressing
+## Skill: Debug Deployment Rollout
+
+**When**: Deployment has 0 ready replicas or rollout not progressing.
 
-**Intent**: Explain why a deployment has missing/zero ready replicas.
+**Trigger**: "deployment stuck", "rollout not progressing", "0/1 ready"
 
-**Procedure**:
+**Steps**:
 
-1. **Check Deployment Status & Conditions**
+1. **Check deployment status**
    ```json
    {
      "tool": "kube_get",
@@ -126,7 +128,7 @@ Issue reported
    }
    ```
 
-2. **Inspect ReplicaSets** (Is a new RS failing to spin up?)
+2. **Inspect ReplicaSets** (Is new RS failing to create pods?)
    ```json
    {
      "tool": "kube_list",
@@ -134,7 +136,7 @@ Issue reported
    }
    ```
 
-3. **Aggregate Logs** (See if new pods are failing immediately)
+3. **Aggregate logs** (Are new pods failing immediately?)
    ```json
    {
      "tool": "kube_log",
@@ -148,29 +150,31 @@ Issue reported
    }
    ```
 
-**Common Issues**:
-- **Progressing Stuck**: New ReplicaSet can't create pods (quota? errors?).
-- **Available < Desired**: Pods running but failing Readiness Probe.
-- **Old ReplicaSets not cleaning up**: Deployment strategy issues.
+**Common issues**:
+- New ReplicaSet can't create pods (quota/errors?)
+- Pods running but failing readiness probe
+- Old ReplicaSets not cleaning up (strategy issue)
 
 ---
 
-## Skill: Debug a Service With No Traffic / No Endpoints
+## Skill: Debug Service Connectivity
 
-**Intent**: Determine if the issue is Selector, Pod Readiness, or Network Policy.
+**When**: Service has no traffic, endpoints missing, or unreachable.
 
-**Procedure**:
+**Trigger**: "service unreachable", "no endpoints", "can't reach service"
 
-1. **Verify Endpoints Exist**
+**Steps**:
+
+1. **Verify endpoints exist**
    ```json
    {
      "tool": "kube_get",
      "args": { "resourceType": "endpoints", "name": "<svc>", "namespace": "<ns>" }
    }
    ```
-   - *Empty?* Check Service Selector vs Pod Labels. Are pods Ready?
+   - Empty? Check Service selector vs Pod labels. Are pods Ready?
 
-2. **Test Connectivity from inside cluster**
+2. **Test connectivity from cluster**
    ```json
    {
      "tool": "kube_net",
@@ -188,53 +192,73 @@ Issue reported
 
 ## Skill: Node Debugging
 
-**Intent**: Identify if node-level issues (Pressure, Taints) are causing pod failures.
+**When**: Node-level issues causing pod failures.
+
+**Trigger**: "node not ready", "node pressure", "taints blocking pods"
 
-**Procedure**:
+**Steps**:
 
-1. **List Nodes & Status**
+1. **List nodes**
    ```json
    { "tool": "kube_list", "args": { "resourceType": "node" } }
    ```
 
-2. **Describe Specific Node**
+2. **Describe specific node**
    ```json
    { "tool": "kube_get", "args": { "resourceType": "node", "name": "<node>", "includeEvents": true } }
    ```
 
-**Conditions to Watch**:
-- **Ready**: Must be `True`.
-- **MemoryPressure / DiskPressure / PIDPressure**: If `True`, node is evicting/blocking pods.
-- **NetworkUnavailable**: CNI plugin failure?
+**Key conditions**:
+- **Ready**: Must be `True`
+- **MemoryPressure/DiskPressure/PIDPressure**: If `True`, node is evicting pods
+- **NetworkUnavailable**: CNI plugin failure
 
 ---
 
 ## Skill: Resource Debugging
 
-**Intent**: Detect resource bottlenecks (CPU throttling, OOM).
+**When**: Detecting resource bottlenecks (CPU throttling, OOM).
 
-**Procedure**:
+**Trigger**: "CPU throttling", "memory pressure", "high CPU/memory"
 
-1. **Top Pods/Nodes**
+**Steps**:
+
+1. **Top consumers**
    ```json
    { "tool": "kube_metrics", "args": { "topN": 10, "includeSummary": true } }
    ```
 
-2. **OOMKilled Investigation**
-   - Check `kube_get` pod status for `LastState: OOMKilled`.
-   - Solution: Increase Memory Limit or fix leak.
+2. **OOMKilled investigation**
+   - Check `kube_get` pod status for `LastState: OOMKilled`
+   - Solution: Increase memory limit or fix leak
+
+3. **CPU throttling**
+   - App slow but no errors? Check if usage near CPU limit
+   - Solution: Increase CPU limit or remove limit (keep request)
+
+---
+
+## Advanced: Code Mode Bulk Analysis
 
-3. **CPU Throttling**
-   - If app is slow but no errors: Check if usage is near CPU Limit.
-   - Solution: Increase CPU Limit (or remove limit and keep request).
+**When**: Complex queries requiring logic (e.g., "find all pods without resource limits").
+
+**Trigger**: "bulk analysis", "find pods without limits", "code mode"
+
+**Example**:
+```typescript
+const pods = await tools.kubernetes.list({ resourceType: 'pod' });
+const noLimits = pods.items.filter(p =>
+  p.spec.containers.some(c => !c.resources?.limits)
+);
+return { count: noLimits.length, names: noLimits.map(p => p.metadata.name) };
+```
 
 ---
 
-## Skill: Long Investigation Hygiene (using `plan_step`)
+## Multi-Step Investigation Hygiene
 
-**Intent**: Keep multi-step debugging stable and reviewable.
+For complex investigations spanning multiple steps, use `plan_step` to maintain clear progress tracking:
 
-**Template**:
 ```json
 {
   "tool": "plan_step",
@@ -246,18 +270,3 @@ Issue reported
   }
 }
 ```
-
----
-
-## Skill: One-shot Code Mode Triage (Advanced)
-
-**Intent**: Use `run_code` for complex logic (e.g., "Find all pods without resource limits").
-
-**Example**:
-```typescript
-const pods = await tools.kubernetes.list({ resourceType: 'pod' });
-const noLimits = pods.items.filter(p =>
-  p.spec.containers.some(c => !c.resources?.limits)
-);
-return { count: noLimits.length, names: noLimits.map(p => p.metadata.name) };
-```

package/dist/src/kubernetes/resources/HelmReleaseOperations.d.ts

@@ -0,0 +1,62 @@
+import { KubernetesClient } from '../KubernetesClient.js';
+import { HelmHook, HelmReleaseData } from '../../utils/HelmDataParser.js';
+export interface HelmListReleasesOptions {
+    namespace?: string;
+    selector?: string;
+    statuses?: string[];
+    maxReleases?: number;
+}
+export interface HelmGetReleaseOptions {
+    releaseName: string;
+    namespace?: string;
+    revision?: number;
+}
+export interface HelmReleaseSummary {
+    name: string;
+    namespace: string;
+    revision: number;
+    updated: string;
+    status: string;
+    chart: string;
+    app_version: string;
+}
+export interface HelmReleaseHistoryEntry {
+    revision: number;
+    updated: string;
+    status: string;
+    chart: string;
+    app_version: string;
+    description: string;
+}
+export interface HelmReleaseRecord {
+    storageBackend: HelmStorageKind;
+    storageObjectName: string;
+    labels: Record<string, string>;
+    release: HelmReleaseData;
+    summary: HelmReleaseSummary;
+}
+type HelmStorageKind = 'secret' | 'configmap';
+export declare class HelmReleaseOperations {
+    private readonly secretOps;
+    private readonly configMapOps;
+    constructor(client: KubernetesClient);
+    listReleases(options?: HelmListReleasesOptions): Promise<HelmReleaseSummary[]>;
+    getRelease(options: HelmGetReleaseOptions): Promise<HelmReleaseRecord>;
+    getReleaseHistory(options: HelmGetReleaseOptions & {
+        maxRevisions?: number;
+    }): Promise<HelmReleaseHistoryEntry[]>;
+    getReleaseValues(options: HelmGetReleaseOptions, allValues?: boolean): Promise<any>;
+    getReleaseManifest(options: HelmGetReleaseOptions): Promise<string>;
+    getReleaseNotes(options: HelmGetReleaseOptions): Promise<string>;
+    getReleaseHooks(options: HelmGetReleaseOptions): Promise<HelmHook[]>;
+    private buildLabelSelector;
+    private listStorageRefs;
+    private dedupeRefs;
+    private listSecretRefs;
+    private listConfigMapRefs;
+    private ensureRefHasData;
+    private parseReleaseData;
+    private toSummary;
+}
+export {};
+//# sourceMappingURL=HelmReleaseOperations.d.ts.map

package/dist/src/kubernetes/resources/HelmReleaseOperations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HelmReleaseOperations.d.ts","sourceRoot":"","sources":["../../../../src/kubernetes/resources/HelmReleaseOperations.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG1D,OAAO,EAML,QAAQ,EACR,eAAe,EAEhB,MAAM,+BAA+B,CAAC;AAEvC,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,eAAe,CAAC;IAChC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,OAAO,EAAE,eAAe,CAAC;IACzB,OAAO,EAAE,kBAAkB,CAAC;CAC7B;AAED,KAAK,eAAe,GAAG,QAAQ,GAAG,WAAW,CAAC;AA6G9C,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;IAC7C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsB;gBAEvC,MAAM,EAAE,gBAAgB;IAK9B,YAAY,CAAC,OAAO,GAAE,uBAA4B,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAoClF,UAAU,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAyCtE,iBAAiB,CACrB,OAAO,EAAE,qBAAqB,GAAG;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,GACzD,OAAO,CAAC,uBAAuB,EAAE,CAAC;IAsC/B,gBAAgB,CAAC,OAAO,EAAE,qBAAqB,EAAE,SAAS,UAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;IAKjF,kBAAkB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC;IAKnE,eAAe,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC;IAKhE,eAAe,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAK1E,OAAO,CAAC,kBAAkB;YAiBZ,eAAe;IAmC7B,OAAO,CAAC,UAAU;YAkBJ,cAAc;YAmCd,iBAAiB;YAoCjB,gBAAgB;IAkC9B,OAAO,CAAC,gBAAgB;IAoBxB,OAAO,CAAC,SAAS;CA8BlB"}