kubeview-mcp 1.0.0

package/src/tools/kubernetes/GetPersistentVolumesTool.ts

@@ -0,0 +1,107 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import {
+  BaseTool,
+  CommonSchemas,
+  formatResourceMetadata,
+  formatResourceStatus,
+} from './BaseTool.js';
+import { KubernetesClient } from '../../kubernetes/KubernetesClient.js';
+
+/**
+ * List and analyze Persistent Volumes in a Kubernetes cluster
+ */
+export class GetPersistentVolumesTool implements BaseTool {
+  tool: Tool = {
+    name: 'get_persistent_volumes',
+    description:
+      'List all Persistent Volume resources in the current Kubernetes cluster and optionally analyze their status (similar to `kubectl get pv`)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        labelSelector: CommonSchemas.labelSelector,
+        fieldSelector: CommonSchemas.fieldSelector,
+        storageClass: {
+          type: 'string',
+          description: 'Filter by storage class name',
+          optional: true,
+        },
+        reclaimPolicy: {
+          type: 'string',
+          description: 'Filter by reclaim policy (Retain, Delete, Recycle)',
+          optional: true,
+        },
+        accessMode: {
+          type: 'string',
+          description: 'Filter by access mode (ReadWriteOnce, ReadOnlyMany, ReadWriteMany)',
+          optional: true,
+        },
+        analyze: {
+          type: 'boolean',
+          description: 'Include detailed analysis with issue detection and statistics',
+          optional: true,
+          default: true,
+        },
+      },
+    },
+  };
+
+  async execute(params: any, client: KubernetesClient): Promise<any> {
+    try {
+      const {
+        labelSelector,
+        fieldSelector,
+        storageClass,
+        reclaimPolicy,
+        accessMode,
+        analyze = true,
+      } = params || {};
+      const pvOperations = client.resources.persistentVolumes;
+
+      let analysis;
+      if (analyze) {
+        analysis = await pvOperations.analyzePVs({
+          labelSelector,
+          fieldSelector,
+          storageClass,
+          reclaimPolicy,
+          accessMode,
+        });
+      }
+
+      const res = await pvOperations.list({
+        labelSelector,
+        fieldSelector,
+        storageClass,
+        reclaimPolicy,
+        accessMode,
+      });
+
+      const persistentVolumes = res.items.map((pv: any) => ({
+        metadata: formatResourceMetadata(pv),
+        spec: {
+          capacity: pv.spec?.capacity,
+          storageClassName: pv.spec?.storageClassName,
+          accessModes: pv.spec?.accessModes,
+          persistentVolumeReclaimPolicy: pv.spec?.persistentVolumeReclaimPolicy,
+          volumeMode: pv.spec?.volumeMode,
+          claimRef: pv.spec?.claimRef,
+        },
+        status: {
+          ...formatResourceStatus(pv),
+          phase: pv.status?.phase,
+          message: pv.status?.message,
+          reason: pv.status?.reason,
+        },
+      }));
+
+      return {
+        total: persistentVolumes.length,
+        analysis,
+        persistentVolumes,
+      };
+    } catch (error: any) {
+      const errorMessage = error.response?.body?.message || error.message || 'Unknown error';
+      throw new Error(`Failed to list persistent volumes: ${errorMessage}`);
+    }
+  }
+}

package/src/tools/kubernetes/GetPodMetricsTool.ts

@@ -0,0 +1,113 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { BaseTool, CommonSchemas } from './BaseTool.js';
+import { KubernetesClient } from '../../kubernetes/KubernetesClient.js';
+import { MetricOperations } from '../../kubernetes/resources/MetricOperations.js';
+
+/**
+ * Get pod metrics from Kubernetes metrics API
+ */
+export class GetPodMetricsTool implements BaseTool {
+  tool: Tool = {
+    name: 'get_pod_metrics',
+    description:
+      'Fetch CPU and memory metrics for pods in the current Kubernetes cluster (similar to `kubectl top pods`)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        namespace: {
+          ...CommonSchemas.namespace,
+          description:
+            'Kubernetes namespace to fetch pod metrics from. If not specified, fetches metrics from all namespaces.',
+        },
+        podName: {
+          type: 'string',
+          description:
+            'Optional specific pod name to fetch metrics for. If provided, namespace is required.',
+        },
+      },
+    },
+  };
+
+  async execute(params: any, client: KubernetesClient): Promise<any> {
+    try {
+      const { namespace, podName } = params || {};
+      const metricOperations = new MetricOperations(client);
+
+      // If a specific pod name is requested, fetch metrics for that pod only
+      if (podName) {
+        if (!namespace) {
+          throw new Error('Namespace is required when fetching metrics for a specific pod');
+        }
+
+        const podMetrics = await metricOperations.getPodMetricsByName(podName, namespace);
+
+        if (!podMetrics) {
+          return {
+            message: `No metrics found for pod '${podName}' in namespace '${namespace}'`,
+            pod: null,
+          };
+        }
+
+        return {
+          pod: {
+            name: podMetrics.metadata.name,
+            namespace: podMetrics.metadata.namespace,
+            timestamp: podMetrics.timestamp,
+            window: podMetrics.window,
+            containers: podMetrics.containers.map((container) => ({
+              name: container.name,
+              cpu: container.usage.cpu,
+              memory: container.usage.memory,
+            })),
+          },
+        };
+      }
+
+      // Otherwise, fetch metrics for all pods in the specified namespace (or all namespaces)
+      const podMetricsList = await metricOperations.getPodMetrics(namespace);
+
+      if (!podMetricsList || !podMetricsList.items || podMetricsList.items.length === 0) {
+        return {
+          total: 0,
+          namespace: namespace || 'all',
+          message: 'No pod metrics found',
+          pods: [],
+        };
+      }
+
+      const pods = podMetricsList.items.map((podMetrics) => ({
+        name: podMetrics.metadata.name,
+        namespace: podMetrics.metadata.namespace,
+        timestamp: podMetrics.timestamp,
+        window: podMetrics.window,
+        containers: podMetrics.containers.map((container) => ({
+          name: container.name,
+          cpu: container.usage.cpu,
+          memory: container.usage.memory,
+        })),
+        // Calculate total pod usage by summing container usage
+        totalUsage: {
+          cpu: podMetrics.containers.reduce((total, container) => {
+            // Parse CPU values and sum them (handling different units like 'm', 'n')
+            const cpuValue = metricOperations.parseCpuValueToNanocores(container.usage.cpu);
+            return total + cpuValue;
+          }, 0),
+          memory: podMetrics.containers.reduce((total, container) => {
+            // Parse memory values and sum them (handling different units like 'Ki', 'Mi', 'Gi')
+            const memoryValue = metricOperations.parseMemoryValueToBytes(container.usage.memory);
+            return total + memoryValue;
+          }, 0),
+        },
+      }));
+
+      return {
+        total: pods.length,
+        namespace: namespace || 'all',
+        pods,
+      };
+    } catch (error: any) {
+      const errorMessage = error.response?.body?.message || error.message || 'Unknown error';
+      throw new Error(`Failed to get pod metrics: ${errorMessage}`);
+    }
+  }
+}

package/src/tools/kubernetes/GetPodsTool.ts

@@ -0,0 +1,39 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { BaseTool, CommonSchemas } from './BaseTool.js';
+import { KubernetesClient } from '../../kubernetes/KubernetesClient.js';
+import { PodOperations } from '../../kubernetes/resources/PodOperations.js';
+
+/**
+ * List pods in a Kubernetes cluster
+ */
+export class GetPodsTool implements BaseTool {
+  tool: Tool = {
+    name: 'get_pods',
+    description:
+      'List Pod resources in the current Kubernetes cluster (similar to `kubectl get pods`)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        namespace: CommonSchemas.namespace,
+        labelSelector: CommonSchemas.labelSelector,
+        fieldSelector: CommonSchemas.fieldSelector,
+      },
+    },
+  };
+
+  async execute(params: any, client: KubernetesClient): Promise<any> {
+    try {
+      const { namespace, labelSelector, fieldSelector } = params || {};
+      const podOperations = new PodOperations(client);
+
+      return await podOperations.listFormatted({
+        namespace,
+        labelSelector,
+        fieldSelector,
+      });
+    } catch (error: any) {
+      const errorMessage = error.response?.body?.message || error.message || 'Unknown error';
+      throw new Error(`Failed to list pods: ${errorMessage}`);
+    }
+  }
+}

package/src/tools/kubernetes/GetResourceTool.ts

@@ -0,0 +1,90 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { BaseTool, CommonSchemas } from './BaseTool.js';
+import { KubernetesClient } from '../../kubernetes/KubernetesClient.js';
+import { ConfigMapOperations } from '../../kubernetes/resources/ConfigMapOperations.js';
+import { PodOperations } from '../../kubernetes/resources/PodOperations.js';
+import { ServiceOperations } from '../../kubernetes/resources/ServiceOperations.js';
+import { DeploymentOperations } from '../../kubernetes/resources/DeploymentOperations.js';
+import { SecretOperations } from '../../kubernetes/resources/SecretOperations.js';
+
+/**
+ * Get details of a specific Kubernetes resource
+ */
+export class GetResourceTool implements BaseTool {
+  tool: Tool = {
+    name: 'get_resource',
+    description: 'Get detailed information about a specific Kubernetes resource',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        resourceType: {
+          type: 'string',
+          description: 'Type of resource (pod, service, deployment, configmap, secret)',
+          enum: ['pod', 'service', 'deployment', 'configmap', 'secret'],
+        },
+        name: CommonSchemas.name,
+        namespace: {
+          ...CommonSchemas.namespace,
+          description: 'Kubernetes namespace (defaults to "default")',
+        },
+        skipSanitize: {
+          type: 'boolean',
+          description:
+            'Skip sanitizing sensitive data in ConfigMap values (only applies to configmap type)',
+          optional: true,
+        },
+      },
+      required: ['resourceType', 'name'],
+    },
+  };
+
+  async execute(params: any, client: KubernetesClient): Promise<any> {
+    try {
+      const { resourceType, name, namespace = 'default', skipSanitize } = params;
+
+      switch (resourceType) {
+        case 'pod':
+          return await new PodOperations(client).getFormatted(name, { namespace });
+        case 'service':
+          return await new ServiceOperations(client).getFormatted(name, { namespace });
+        case 'deployment':
+          return await new DeploymentOperations(client).getFormatted(name, { namespace });
+        case 'configmap':
+          return await this.getConfigMapDetails(client, name, namespace, skipSanitize);
+        case 'secret':
+          return await new SecretOperations(client).getFormatted(name, { namespace });
+        default:
+          throw new Error(`Unsupported resource type: ${resourceType}`);
+      }
+    } catch (error: any) {
+      const errorMessage = error.response?.body?.message || error.message || 'Unknown error';
+      throw new Error(`Failed to get resource details: ${errorMessage}`);
+    }
+  }
+
+  private async getConfigMapDetails(
+    client: KubernetesClient,
+    name: string,
+    namespace: string,
+    skipSanitize?: boolean,
+  ): Promise<any> {
+    const configMapOperations = new ConfigMapOperations(client);
+    const configMap = await configMapOperations.get(name, { namespace, skipSanitize });
+
+    return {
+      resourceType: 'configmap',
+      metadata: {
+        name: configMap.metadata?.name,
+        namespace: configMap.metadata?.namespace,
+        uid: configMap.metadata?.uid,
+        resourceVersion: configMap.metadata?.resourceVersion,
+        generation: configMap.metadata?.generation,
+        creationTimestamp: configMap.metadata?.creationTimestamp,
+        labels: configMap.metadata?.labels || {},
+        annotations: configMap.metadata?.annotations || {},
+      },
+      data: configMap.data || {},
+      binaryData: configMap.binaryData ? Object.keys(configMap.binaryData) : [],
+    };
+  }
+}

package/src/tools/kubernetes/GetSecretsTool.ts

@@ -0,0 +1,55 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { BaseTool, CommonSchemas } from './BaseTool.js';
+import { KubernetesClient } from '../../kubernetes/KubernetesClient.js';
+import { SecretOperations } from '../../kubernetes/resources/SecretOperations.js';
+
+/**
+ * List Secret in a Kubernetes cluster with optional data sanitization
+ */
+export class GetSecretsTool implements BaseTool {
+  tool: Tool = {
+    name: 'get_secrets',
+    description:
+      'List all Secret resources in the current Kubernetes cluster (similar to `kubectl get secrets`)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        namespace: CommonSchemas.namespace,
+        labelSelector: CommonSchemas.labelSelector,
+        fieldSelector: CommonSchemas.fieldSelector,
+        skipSanitize: {
+          type: 'boolean',
+          description:
+            'Skip sanitizing sensitive data in Secret values (default: false, meaning sanitization is enabled by default)',
+          optional: true,
+        },
+      },
+    },
+  };
+
+  async execute(params: any, client: KubernetesClient): Promise<any> {
+    try {
+      const { namespace, labelSelector, fieldSelector, skipSanitize } = params || {};
+
+      const secretOperations = new SecretOperations(client);
+
+      let res;
+      if (namespace) {
+        res = await secretOperations.list({
+          namespace,
+          labelSelector,
+          fieldSelector,
+          skipSanitize,
+        });
+      } else {
+        res = await secretOperations.list({ labelSelector, fieldSelector, skipSanitize });
+      }
+
+      return res;
+    } catch (error: any) {
+      return {
+        error: `Failed to get secrets: ${error.message}`,
+      };
+    }
+  }
+}

package/src/tools/kubernetes/GetServicesTool.ts

@@ -0,0 +1,39 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { BaseTool, CommonSchemas } from './BaseTool.js';
+import { KubernetesClient } from '../../kubernetes/KubernetesClient.js';
+import { ServiceOperations } from '../../kubernetes/resources/ServiceOperations.js';
+
+/**
+ * List services in a Kubernetes cluster
+ */
+export class GetServicesTool implements BaseTool {
+  tool: Tool = {
+    name: 'get_services',
+    description:
+      'List Service resources in the current Kubernetes cluster (similar to `kubectl get svc`)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        namespace: CommonSchemas.namespace,
+        labelSelector: CommonSchemas.labelSelector,
+        fieldSelector: CommonSchemas.fieldSelector,
+      },
+    },
+  };
+
+  async execute(params: any, client: KubernetesClient): Promise<any> {
+    try {
+      const { namespace, labelSelector, fieldSelector } = params || {};
+      const serviceOperations = new ServiceOperations(client);
+
+      return await serviceOperations.listFormatted({
+        namespace,
+        labelSelector,
+        fieldSelector,
+      });
+    } catch (error: any) {
+      const errorMessage = error.response?.body?.message || error.message || 'Unknown error';
+      throw new Error(`Failed to list services: ${errorMessage}`);
+    }
+  }
+}

package/src/tools/kubernetes/index.ts

@@ -0,0 +1,16 @@
+export type { BaseTool } from './BaseTool.js';
+export { CommonSchemas } from './BaseTool.js';
+export { GetPodsTool } from './GetPodsTool.js';
+export { GetPodMetricsTool } from './GetPodMetricsTool.js';
+export { GetServicesTool } from './GetServicesTool.js';
+export { GetIngressTool } from './GetIngressTool.js';
+export { GetDeploymentsTool } from './GetDeploymentsTool.js';
+export { GetResourceTool } from './GetResourceTool.js';
+export { GetContainerLogsTool } from './GetContainerLogsTool.js';
+export { GetEventsTool } from './GetEventsTool.js';
+export { GetNamespacesTool } from './GetNamespacesTool.js';
+export { GetMetricsTool } from './GetMetricsTool.js';
+export { GetConfigMapsTool as GetConfigMapTool } from './GetConfigMapTool.js';
+export { GetSecretsTool } from './GetSecretsTool.js';
+export { GetPersistentVolumesTool } from './GetPersistentVolumesTool.js';
+export { GetPersistentVolumeClaimsTool } from './GetPersistentVolumeClaimsTool.js';

package/src/utils/CliUtils.ts

@@ -0,0 +1,207 @@
+import { spawn, ChildProcessWithoutNullStreams } from 'child_process';
+import { existsSync } from 'fs';
+
+/**
+ * Common CLI utilities for various tools (helm, argo, etc.)
+ */
+
+/**
+ * Gets common installation paths for a CLI tool based on the platform
+ * @param toolName The name of the CLI tool
+ * @returns Array of possible installation paths
+ */
+function getCommonCliPaths(toolName: string): string[] {
+  const paths = [
+    `/usr/local/bin/${toolName}`,
+    `/usr/bin/${toolName}`,
+    `/opt/homebrew/bin/${toolName}`,
+    `/snap/bin/${toolName}`,
+  ];
+
+  if (process.platform === 'win32') {
+    paths.push(
+      `C:\\Program Files\\${toolName}\\${toolName}.exe`,
+      `C:\\ProgramData\\chocolatey\\bin\\${toolName}.exe`,
+    );
+  }
+
+  return paths.filter(Boolean);
+}
+
+/**
+ * Finds a CLI executable path
+ * @param toolName The name of the CLI tool (e.g., 'helm', 'argo')
+ * @param versionArgs Arguments to check version (e.g., ['version', '--short'])
+ * @returns Promise with the executable path or null if not found
+ */
+export async function findCliExecutable(
+  toolName: string,
+  versionArgs: string[] = ['version'],
+): Promise<string | null> {
+  // First try to use the tool directly (relies on PATH)
+  try {
+    await new Promise<void>((resolve, reject) => {
+      const testProcess = spawn(toolName, versionArgs, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: process.env,
+      });
+
+      testProcess.on('close', (code) => {
+        if (code === 0) {
+          resolve();
+        } else {
+          reject(new Error(`${toolName} not found in PATH`));
+        }
+      });
+
+      testProcess.on('error', reject);
+    });
+
+    return toolName; // Found in PATH
+  } catch {
+    // Continue to fallback options
+  }
+
+  // Fallback: Check common installation paths
+  const commonPaths = getCommonCliPaths(toolName);
+  for (const cliPath of commonPaths) {
+    if (existsSync(cliPath)) {
+      return cliPath;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Executes a CLI command for any tool
+ * @param toolName The name of the CLI tool
+ * @param args Array of command arguments
+ * @param executablePath Optional executable path (for fallback scenarios)
+ * @param timeoutEnvVar Environment variable name for timeout (e.g., 'HELM_TIMEOUT', 'ARGO_TIMEOUT')
+ * @returns Promise with the command output
+ */
+export async function executeCliCommand(
+  toolName: string,
+  args: string[],
+  executablePath = toolName,
+  timeoutEnvVar = `${toolName.toUpperCase()}_TIMEOUT`,
+): Promise<any> {
+  const timeout = parseInt(process.env[timeoutEnvVar] || '30000', 10);
+  const useShell = false; // Security-first approach: never use shell
+
+  if (process.env.LOG_LEVEL === 'debug') {
+    console.debug(`Executing: ${toolName} ${args.join(' ')}`);
+    console.debug(`Using shell: ${useShell}`);
+  }
+
+  return new Promise((resolve, reject) => {
+    const spawnOptions: {
+      stdio: ['pipe', 'pipe', 'pipe'];
+      env: typeof process.env;
+    } = {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env },
+    };
+
+    const childProcess: ChildProcessWithoutNullStreams = spawn(executablePath, args, spawnOptions);
+
+    let stdout = '';
+    let stderr = '';
+    let timeoutHandle: NodeJS.Timeout | null = null;
+
+    // Set up timeout
+    if (timeout > 0) {
+      timeoutHandle = setTimeout(() => {
+        childProcess.kill('SIGTERM');
+        reject(
+          new Error(
+            `${toolName} command timed out after ${timeout}ms: ${toolName} ${args.join(' ')}`,
+          ),
+        );
+      }, timeout);
+    }
+
+    const cleanup = () => {
+      if (timeoutHandle) {
+        clearTimeout(timeoutHandle);
+      }
+    };
+
+    childProcess.stdout?.on('data', (data: Buffer) => {
+      stdout += data.toString();
+    });
+
+    childProcess.stderr?.on('data', (data: Buffer) => {
+      stderr += data.toString();
+    });
+
+    childProcess.on('close', (code: number | null) => {
+      cleanup();
+
+      if (code !== 0) {
+        reject(new Error(`${toolName} command failed (exit code ${code}): ${stderr || stdout}`));
+        return;
+      }
+
+      try {
+        // Try to parse as JSON first
+        if (stdout.trim().startsWith('{') || stdout.trim().startsWith('[')) {
+          resolve(JSON.parse(stdout));
+        } else {
+          // Return raw output for non-JSON responses
+          resolve({ output: stdout.trim() });
+        }
+      } catch {
+        // If JSON parsing fails, return raw output
+        resolve({ output: stdout.trim() });
+      }
+    });
+
+    childProcess.on('error', (err: Error) => {
+      cleanup();
+      reject(
+        new Error(
+          `Failed to execute ${toolName} command "${toolName} ${args.join(' ')}": ${err.message}`,
+        ),
+      );
+    });
+  });
+}
+
+/**
+ * Validates that a CLI tool is available with fallback detection
+ * @param toolName The name of the CLI tool
+ * @param versionArgs Arguments to check version (e.g., ['version', '--short'])
+ * @param timeoutEnvVar Environment variable name for timeout
+ */
+export async function validateCli(
+  toolName: string,
+  versionArgs: string[] = ['version'],
+  timeoutEnvVar = `${toolName.toUpperCase()}_TIMEOUT`,
+): Promise<void> {
+  try {
+    // First try standard PATH lookup
+    await executeCliCommand(toolName, versionArgs, toolName, timeoutEnvVar);
+  } catch {
+    // If PATH lookup fails, try fallback detection
+    try {
+      const cliExecutable = await findCliExecutable(toolName, versionArgs);
+      if (!cliExecutable) {
+        throw new Error(
+          `${toolName} CLI not found. Please install ${toolName} CLI to use ${toolName} tools.`,
+        );
+      }
+
+      // Test the found executable
+      await executeCliCommand(toolName, versionArgs, cliExecutable, timeoutEnvVar);
+    } catch (fallbackError) {
+      if (fallbackError instanceof Error && fallbackError.message.includes('timed out')) {
+        throw fallbackError; // Re-throw timeout errors as-is
+      }
+      throw new Error(
+        `${toolName} CLI not found. Please install ${toolName} CLI to use ${toolName} tools.`,
+      );
+    }
+  }
+}