kubeview-mcp 1.5.1 → 1.7.0

package/CHANGELOG.md

@@ -7,6 +7,28 @@ 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
+- **MCP SDK compatibility hardening**: Pin `@modelcontextprotocol/sdk` to `^1.25.3`.
+- **Type import policy**: Disallow removed loose type exports (`Tools`, `Prompts`, `Resources`, `Roots`, `Sampling`) from `@modelcontextprotocol/sdk/types.js`.
+
+### Added
+- Introduced the plan_step tool for structured planning and tracking during investigations.
+- Added detailed skills documentation for debugging Kubernetes clusters in SKILL.md.
+- Improved error handling for malformed JSON-RPC payloads in MCPServer.
+- Added tests for the new plan_step tool and ensured compatibility with the updated SDK.
+
 ## [1.5.1] - 2026-01-14
 
 ### Changed

package/README.md

@@ -14,18 +14,26 @@ 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.
 
 ---
 
+## MCP SDK Compatibility
+
+- This project is pinned to `@modelcontextprotocol/sdk@^1.25.3`.
+- Legacy loose type imports (`Tools`, `Prompts`, `Resources`, `Roots`, `Sampling`) are disallowed.
+- This compatibility pass intentionally excludes Streamable HTTP transport migration and icon metadata rollout.
+
+---
+
 ## 🚀 Quick Start
 
 ### Prerequisites
 
 - 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
 
@@ -56,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.
@@ -77,15 +86,36 @@ 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.
+
+### Why `plan_step` really helps:
+
+1. **Stable multi-step planning without bloating chat context.**
+   Instead of dumping a massive plan into the conversation, the agent can store step-by-step progress in `plan_step` and keep user-facing responses clean.
+2. **A consistent state machine for long tasks.**
+   Complex workflows usually need: plan -> execute step 1 -> verify -> step 2 -> backtrack -> branch -> finalize. `plan_step` gives the agent a structured way to follow that lifecycle without losing track.
+3. **Better tool routing.**
+   Good agents alternate between thinking and acting. `plan_step` encourages that rhythm: log intent, call real tools, capture outcome, decide next step.
 
 ---
 
@@ -108,9 +138,9 @@ For complex tasks requiring logic, loops, or data processing, use **Code Mode**:
 "env": { "MCP_MODE": "code" }
 ```
 
-### 💡 Pro Tip: Code Mode Prompt
+### 💡 Pro Tip: `code-mode` MCP Prompt
 
-The server includes a built-in prompt named **`code-mode`** that injects the full TypeScript API documentation, tool overview, and examples into the context.
+The server includes a built-in MCP server prompt named **`code-mode`** that injects the full TypeScript API documentation, tool overview, and examples into the context.
 
 **In Cursor IDE**:
 Simply type `/kubeview/code-mode` in the prompt (or select it from the `/` prompt menu). This gives the AI the exact context it needs to write correct `run_code` scripts immediately.
@@ -120,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
@@ -127,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

@@ -0,0 +1,272 @@
+---
+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
+
+Reusable investigation playbooks for debugging Kubernetes clusters using KubeView MCP.
+
+## Core Principles
+
+- **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 Fixes**: Provide YAML snippets rather than imperative `kubectl` commands.
+
+## Tool Quick Reference
+
+- **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, tools become `tools.kubernetes.*` (e.g., `tools.kubernetes.list`).
+
+## Debugging Decision Tree
+
+```
+Issue reported
+    │
+    ├─ Pod not running? ──────────► Skill: Debug Pod Failures
+    │
+    ├─ Service unreachable? ──────► Skill: Debug Service Connectivity
+    │
+    ├─ Deployment stuck? ─────────► Skill: Debug Deployment Rollout
+    │
+    ├─ Node issues? ──────────────► Skill: Node Debugging
+    │
+    └─ Performance/Resources? ────► Skill: Resource Debugging
+```
+
+---
+
+## Skill: Cluster Triage
+
+**When**: Get high-level cluster health overview, identify problem areas.
+
+**Trigger**: "cluster health", "triage the cluster", "what's wrong"
+
+**Steps**:
+
+1. **Cluster diagnostics**
+   ```json
+   { "tool": "kube_list", "args": {} }
+   ```
+
+2. **Metrics + top consumers**
+   ```json
+   { "tool": "kube_metrics", "args": { "diagnostics": true, "includeSummary": true, "topN": 5 } }
+   ```
+
+3. **Drill into problem namespaces**
+   - Identify namespaces with high `CrashLoopBackOff` or `Pending` counts
+   ```json
+   { "tool": "kube_list", "args": { "namespace": "<ns>" } }
+   ```
+
+---
+
+## Skill: Debug Pod Failures
+
+**When**: Pod is Pending, CrashLoopBackOff, ImagePullBackOff, or OOMKilled.
+
+**Trigger**: "pod won't start", "CrashLoopBackOff", "ImagePullBackOff", "OOMKilled"
+
+**Steps**:
+
+1. **Describe pod with events**
+   ```json
+   {
+     "tool": "kube_get",
+     "args": {
+       "resourceType": "pod",
+       "name": "<pod>",
+       "namespace": "<ns>",
+       "includeEvents": true,
+       "includeDiagnostics": true
+     }
+   }
+   ```
+
+2. **Check logs (current & previous)**
+   ```json
+   {
+     "tool": "kube_logs",
+     "args": { "podName": "<pod>", "namespace": "<ns>", "tailLines": 100, "previous": true }
+   }
+   ```
+
+3. **Common causes**:
+   - **CrashLoopBackOff**:
+     - 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 Deployment Rollout
+
+**When**: Deployment has 0 ready replicas or rollout not progressing.
+
+**Trigger**: "deployment stuck", "rollout not progressing", "0/1 ready"
+
+**Steps**:
+
+1. **Check deployment status**
+   ```json
+   {
+     "tool": "kube_get",
+     "args": {
+       "resourceType": "deployment",
+       "name": "<deploy>",
+       "namespace": "<ns>",
+       "includeEvents": true
+     }
+   }
+   ```
+
+2. **Inspect ReplicaSets** (Is new RS failing to create pods?)
+   ```json
+   {
+     "tool": "kube_list",
+     "args": { "resourceType": "replicaset", "namespace": "<ns>", "labelSelector": "<k=v>" }
+   }
+   ```
+
+3. **Aggregate logs** (Are new pods failing immediately?)
+   ```json
+   {
+     "tool": "kube_log",
+     "args": {
+       "namespace": "<ns>",
+       "ownerKind": "Deployment",
+       "ownerName": "<deploy>",
+       "since": "30m",
+       "includeEvents": true
+     }
+   }
+   ```
+
+**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 Service Connectivity
+
+**When**: Service has no traffic, endpoints missing, or unreachable.
+
+**Trigger**: "service unreachable", "no endpoints", "can't reach service"
+
+**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?
+
+2. **Test connectivity from cluster**
+   ```json
+   {
+     "tool": "kube_net",
+     "args": {
+       "sourcePod": "<debug-pod>",
+       "namespace": "<ns>",
+       "targetService": "<svc>",
+       "runServiceConnectivityTest": true,
+       "runDnsTest": true
+     }
+   }
+   ```
+
+---
+
+## Skill: Node Debugging
+
+**When**: Node-level issues causing pod failures.
+
+**Trigger**: "node not ready", "node pressure", "taints blocking pods"
+
+**Steps**:
+
+1. **List nodes**
+   ```json
+   { "tool": "kube_list", "args": { "resourceType": "node" } }
+   ```
+
+2. **Describe specific node**
+   ```json
+   { "tool": "kube_get", "args": { "resourceType": "node", "name": "<node>", "includeEvents": true } }
+   ```
+
+**Key conditions**:
+- **Ready**: Must be `True`
+- **MemoryPressure/DiskPressure/PIDPressure**: If `True`, node is evicting pods
+- **NetworkUnavailable**: CNI plugin failure
+
+---
+
+## Skill: Resource Debugging
+
+**When**: Detecting resource bottlenecks (CPU throttling, OOM).
+
+**Trigger**: "CPU throttling", "memory pressure", "high CPU/memory"
+
+**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
+
+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
+
+**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) };
+```
+
+---
+
+## Multi-Step Investigation Hygiene
+
+For complex investigations spanning multiple steps, use `plan_step` to maintain clear progress tracking:
+
+```json
+{
+  "tool": "plan_step",
+  "args": {
+    "step": "Triage cluster health, then drill into failing namespace workloads",
+    "stepNumber": 1,
+    "totalSteps": 4,
+    "nextStepNeeded": true
+  }
+}
+```

package/TODO.md

@@ -1,2 +1,13 @@
+- Generate SKILL.md with all the tools and their descriptions for ease of use by the agent.
+	Make your MCP server “skill-friendly” with a few small technical tweaks
+	•	Ensure tool names and schemas are stable and descriptive, because Skills rely on predictable interfaces.
+	•	Provide a single “diagnostics snapshot” tool (even if it internally calls others) so Skills can start with one cheap probe.
+	•	Include golden examples in your docs/prompts that Skills can copy, and keep them updated as your toolset evolves. This aligns with how Skills are described across Claude/Cursor/Codex: instructions + resources that steer behavior reliably.  
+
+- A major trend in 2026 is giving agents tools to "think" before they act.
+Sequential Thinking: Add a tool called `plan_step` that allows the agent to output its reasoning process into a structured format before calling a "real" tool. This improves reliability for complex DevOps tasks.
+https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking
+​
+
 - kube_logs (multiple log streams + events, selectors support)
 - add support for k8s context selector

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"}