kubeview-mcp 1.0.0

package/src/tools/kubernetes/BaseTool.ts

@@ -0,0 +1,76 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { KubernetesClient } from '../../kubernetes/KubernetesClient.js';
+
+/**
+ * Base interface for all Kubernetes MCP tool commands
+ */
+export interface BaseTool {
+  /**
+   * The tool definition for MCP registration
+   */
+  tool: Tool;
+
+  /**
+   * Execute the command with given parameters
+   */
+  execute(params: any, client: KubernetesClient): Promise<any>;
+}
+
+/**
+ * Common parameter schemas used across multiple commands
+ */
+export const CommonSchemas = {
+  namespace: {
+    type: 'string',
+    description: 'Kubernetes namespace (defaults to all namespaces if not specified)',
+    optional: true,
+  },
+  labelSelector: {
+    type: 'string',
+    description: 'Label selector to filter resources (e.g., "app=nginx")',
+    optional: true,
+  },
+  fieldSelector: {
+    type: 'string',
+    description: 'Field selector to filter resources (e.g., "status.phase=Running")',
+    optional: true,
+  },
+  name: {
+    type: 'string',
+    description: 'Name of the resource',
+  },
+};
+
+/**
+ * Format resource metadata for consistent output
+ */
+export function formatResourceMetadata(resource: any): any {
+  return {
+    name: resource.metadata?.name,
+    namespace: resource.metadata?.namespace,
+    uid: resource.metadata?.uid,
+    creationTimestamp: resource.metadata?.creationTimestamp,
+    labels: resource.metadata?.labels || {},
+    annotations: resource.metadata?.annotations || {},
+  };
+}
+
+/**
+ * Format resource status with common fields
+ */
+export function formatResourceStatus(resource: any): any {
+  const status: any = {
+    phase: resource.status?.phase,
+    conditions: resource.status?.conditions || [],
+  };
+
+  // Add resource-specific status fields if they exist
+  if (resource.status?.readyReplicas !== undefined) {
+    status.readyReplicas = resource.status.readyReplicas;
+  }
+  if (resource.status?.replicas !== undefined) {
+    status.replicas = resource.status.replicas;
+  }
+
+  return status;
+}

package/src/tools/kubernetes/GetConfigMapTool.ts

@@ -0,0 +1,33 @@
+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';
+
+/**
+ * List ConfigMaps in a Kubernetes cluster with optional data sanitization
+ */
+export class GetConfigMapsTool implements BaseTool {
+  tool: Tool = {
+    name: 'get_configmaps',
+    description:
+      'List all ConfigMap resources in the current Kubernetes cluster (similar to `kubectl get configmap`)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        namespace: CommonSchemas.namespace,
+        labelSelector: CommonSchemas.labelSelector,
+        fieldSelector: CommonSchemas.fieldSelector,
+        skipSanitize: {
+          type: 'boolean',
+          description:
+            'Skip sanitizing sensitive data in ConfigMap values (default: false, meaning sanitization is enabled by default)',
+          optional: true,
+        },
+      },
+    },
+  };
+
+  async execute(params: any, client: KubernetesClient): Promise<any> {
+    return await new ConfigMapOperations(client).list(params);
+  }
+}

package/src/tools/kubernetes/GetContainerLogsTool.ts

@@ -0,0 +1,140 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { BaseTool, CommonSchemas } from './BaseTool.js';
+import { KubernetesClient } from '../../kubernetes/KubernetesClient.js';
+
+/**
+ * Fetch logs from a container in a Kubernetes pod
+ */
+export class GetContainerLogsTool implements BaseTool {
+  tool: Tool = {
+    name: 'pod_logs',
+    description:
+      'Return stdout / stderr logs for a specified container in a pod in the current cluster (similar to `kubectl logs`)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        podName: {
+          type: 'string',
+          description: 'Name of the pod',
+        },
+        namespace: {
+          ...CommonSchemas.namespace,
+          description: 'Kubernetes namespace (defaults to "default")',
+        },
+        container: {
+          type: 'string',
+          description: 'Container name (optional, defaults to first container)',
+          optional: true,
+        },
+        tailLines: {
+          type: 'number',
+          description: 'Number of lines from the end of the logs to show (optional)',
+          optional: true,
+        },
+        since: {
+          type: 'string',
+          description: 'Show logs since this duration (e.g., "5m", "1h") (optional)',
+          optional: true,
+        },
+        previous: {
+          type: 'boolean',
+          description: 'Return logs from previous instance of the container (optional)',
+          optional: true,
+        },
+        timestamps: {
+          type: 'boolean',
+          description: 'Include timestamps in log output (optional)',
+          optional: true,
+        },
+      },
+      required: ['podName'],
+    },
+  };
+
+  async execute(params: any, client: KubernetesClient): Promise<any> {
+    try {
+      const {
+        podName,
+        namespace = 'default',
+        container,
+        tailLines,
+        since,
+        previous = false,
+        timestamps = false,
+      } = params;
+
+      // Convert duration string to seconds if provided
+      let sinceSeconds: number | undefined;
+      if (since) {
+        sinceSeconds = this.parseDuration(since);
+      }
+
+      // Fetch the logs
+      const logs = await client.core.readNamespacedPodLog({
+        name: podName,
+        namespace,
+        container,
+        tailLines,
+        sinceSeconds,
+        previous,
+        timestamps,
+      });
+
+      // logs is returned as a string, split into lines for better formatting
+      const logLines = (logs as unknown as string).split('\n').filter((line) => line.trim());
+
+      return {
+        podName,
+        namespace,
+        container: container || 'default',
+        lineCount: logLines.length,
+        logs: logLines,
+        options: {
+          tailLines,
+          since,
+          previous,
+          timestamps,
+        },
+      };
+    } catch (error: any) {
+      const errorMessage = error.response?.body?.message || error.message || 'Unknown error';
+
+      // Provide more helpful error messages for common cases
+      if (errorMessage.includes('container') && errorMessage.includes('not found')) {
+        throw new Error(`Container '${params.container}' not found in pod '${params.podName}'`);
+      } else if (errorMessage.includes('not found')) {
+        throw new Error(
+          `Pod '${params.podName}' not found in namespace '${params.namespace || 'default'}'`,
+        );
+      }
+
+      throw new Error(`Failed to fetch container logs: ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Parse duration string (e.g., "5m", "1h", "30s") to seconds
+   */
+  private parseDuration(duration: string): number {
+    const match = duration.match(/^(\d+)([smhd])$/);
+    if (!match) {
+      throw new Error(`Invalid duration format: ${duration}. Use format like "5m", "1h", "30s"`);
+    }
+
+    const value = parseInt(match[1], 10);
+    const unit = match[2];
+
+    switch (unit) {
+      case 's':
+        return value;
+      case 'm':
+        return value * 60;
+      case 'h':
+        return value * 3600;
+      case 'd':
+        return value * 86400;
+      default:
+        throw new Error(`Unknown duration unit: ${unit}`);
+    }
+  }
+}

package/src/tools/kubernetes/GetDeploymentsTool.ts

@@ -0,0 +1,33 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { BaseTool, CommonSchemas } from './BaseTool.js';
+import { KubernetesClient } from '../../kubernetes/KubernetesClient.js';
+import { DeploymentOperations } from '../../kubernetes/resources/DeploymentOperations.js';
+
+/**
+ * List deployments in a Kubernetes cluster
+ */
+export class GetDeploymentsTool implements BaseTool {
+  tool: Tool = {
+    name: 'get_deployments',
+    description:
+      'List all Deployment resources in the current Kubernetes cluster (similar to `kubectl get deployments`)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        namespace: CommonSchemas.namespace,
+        labelSelector: CommonSchemas.labelSelector,
+        fieldSelector: CommonSchemas.fieldSelector,
+      },
+    },
+  };
+
+  async execute(params: any, client: KubernetesClient): Promise<any> {
+    const deploymentOperations = new DeploymentOperations(client);
+    try {
+      const deployments = await deploymentOperations.list(params);
+      return deployments;
+    } catch (error: any) {
+      throw new Error(`Failed to get deployments: ${error.message}`);
+    }
+  }
+}

package/src/tools/kubernetes/GetEventsTool.ts

@@ -0,0 +1,133 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { BaseTool, CommonSchemas } from './BaseTool.js';
+import { KubernetesClient } from '../../kubernetes/KubernetesClient.js';
+
+/**
+ * Show events in a Kubernetes cluster
+ */
+export class GetEventsTool implements BaseTool {
+  tool: Tool = {
+    name: 'get_events',
+    description: 'Show events in the Kubernetes cluster (similar to `kubectl get events`)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        namespace: CommonSchemas.namespace,
+        resourceType: {
+          type: 'string',
+          description: 'Filter events by resource type (e.g., pod, service, deployment)',
+          optional: true,
+        },
+        resourceName: {
+          type: 'string',
+          description: 'Filter events by specific resource name',
+          optional: true,
+        },
+        type: {
+          type: 'string',
+          description: 'Filter by event type (Normal or Warning)',
+          enum: ['Normal', 'Warning'],
+          optional: true,
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of events to return',
+          optional: true,
+        },
+      },
+    },
+  };
+
+  async execute(params: any, client: KubernetesClient): Promise<any> {
+    try {
+      const { namespace, resourceType, resourceName, type: eventType, limit = 100 } = params || {};
+
+      // Build field selector for filtering
+      const fieldSelectors: string[] = [];
+
+      if (resourceName) {
+        fieldSelectors.push(`involvedObject.name=${resourceName}`);
+      }
+
+      if (resourceType) {
+        // Capitalize the resource type for Kubernetes API
+        const capitalizedType = resourceType.charAt(0).toUpperCase() + resourceType.slice(1);
+        fieldSelectors.push(`involvedObject.kind=${capitalizedType}`);
+      }
+
+      if (eventType) {
+        fieldSelectors.push(`type=${eventType}`);
+      }
+
+      const fieldSelector = fieldSelectors.length > 0 ? fieldSelectors.join(',') : undefined;
+
+      let result;
+      if (namespace) {
+        // List events in specific namespace
+        result = await client.core.listNamespacedEvent({
+          namespace,
+          fieldSelector,
+          limit,
+        });
+      } else {
+        // List events in all namespaces
+        result = await client.core.listEventForAllNamespaces({
+          fieldSelector,
+          limit,
+        });
+      }
+
+      // Sort events by timestamp (most recent first)
+      const events = result.items
+        .sort((a: any, b: any) => {
+          const timeA = new Date(a.lastTimestamp || a.firstTimestamp || 0).getTime();
+          const timeB = new Date(b.lastTimestamp || b.firstTimestamp || 0).getTime();
+          return timeB - timeA;
+        })
+        .map((event: any) => ({
+          namespace: event.metadata?.namespace,
+          timestamp: event.lastTimestamp || event.firstTimestamp,
+          type: event.type,
+          reason: event.reason,
+          message: event.message,
+          count: event.count,
+          source: {
+            component: event.source?.component,
+            host: event.source?.host,
+          },
+          involvedObject: {
+            kind: event.involvedObject?.kind,
+            name: event.involvedObject?.name,
+            namespace: event.involvedObject?.namespace,
+            uid: event.involvedObject?.uid,
+            apiVersion: event.involvedObject?.apiVersion,
+            resourceVersion: event.involvedObject?.resourceVersion,
+            fieldPath: event.involvedObject?.fieldPath,
+          },
+          firstSeen: event.firstTimestamp,
+          lastSeen: event.lastTimestamp,
+        }));
+
+      // Group events by type for summary
+      const summary = {
+        total: events.length,
+        normal: events.filter((e: any) => e.type === 'Normal').length,
+        warning: events.filter((e: any) => e.type === 'Warning').length,
+      };
+
+      return {
+        summary,
+        filters: {
+          namespace: namespace || 'all',
+          resourceType,
+          resourceName,
+          eventType,
+        },
+        events,
+      };
+    } catch (error: any) {
+      const errorMessage = error.response?.body?.message || error.message || 'Unknown error';
+      throw new Error(`Failed to fetch events: ${errorMessage}`);
+    }
+  }
+}

package/src/tools/kubernetes/GetIngressTool.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 { IngressOperations } from '../../kubernetes/resources/IngressOperations.js';
+
+/**
+ * List ingresses in a Kubernetes cluster
+ */
+export class GetIngressTool implements BaseTool {
+  tool: Tool = {
+    name: 'get_ingresses',
+    description:
+      'List Ingress resources in the current Kubernetes cluster (similar to `kubectl get ingress`)',
+    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 ingressOperations = new IngressOperations(client);
+
+      return await ingressOperations.listFormatted({
+        namespace,
+        labelSelector,
+        fieldSelector,
+      });
+    } catch (error: any) {
+      const errorMessage = error.response?.body?.message || error.message || 'Unknown error';
+      throw new Error(`Failed to list ingresses: ${errorMessage}`);
+    }
+  }
+}

package/src/tools/kubernetes/GetMetricsTool.ts

@@ -0,0 +1,53 @@
+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 various metrics for Kubernetes resources, optionally enriched with Prometheus data.
+ */
+export class GetMetricsTool implements BaseTool {
+  tool: Tool = {
+    name: 'get_metrics',
+    description:
+      'Fetch live CPU / memory metrics for all nodes and pods in the current cluster (similar to `kubectl top`), with optional enrichment from Prometheus data.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        prometheusQueries: {
+          type: 'array',
+          items: { type: 'string' },
+          description:
+            'An array of PromQL queries to execute against discovered Prometheus targets.',
+          default: [],
+        },
+        fetchPodSpecs: {
+          type: 'boolean',
+          description:
+            'If true, fetches all pod specifications to enrich normalized pod metrics (e.g., with nodeName). Defaults to true.',
+          default: true,
+        },
+        namespace: {
+          ...CommonSchemas.namespace,
+          description:
+            'Optional namespace to restrict Prometheus discovery, pod metrics, and pod spec fetching. If not provided, operates cluster-wide where applicable.',
+        },
+      },
+    },
+  };
+
+  async execute(params: any, client: KubernetesClient): Promise<any> {
+    const metricOperations = new MetricOperations(client);
+
+    // Use explicit defaults from the tool schema
+    const namespace = params.namespace;
+    const prometheusQueries = params.prometheusQueries ?? [];
+    const fetchPodSpecs = params.fetchPodSpecs ?? true;
+
+    return await metricOperations.getMetricsWithOptions(
+      prometheusQueries,
+      fetchPodSpecs,
+      namespace,
+    );
+  }
+}

package/src/tools/kubernetes/GetNamespacesTool.ts

@@ -0,0 +1,36 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { BaseTool, formatResourceMetadata, formatResourceStatus } from './BaseTool.js';
+import { KubernetesClient } from '../../kubernetes/KubernetesClient.js';
+
+/**
+ * List namespaces in a Kubernetes cluster
+ */
+export class GetNamespacesTool implements BaseTool {
+  tool: Tool = {
+    name: 'get_namespaces',
+    description:
+      'List all Namespace resources in the current Kubernetes cluster (similar to `kubectl get namespaces`)',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  };
+
+  async execute(_params: any, client: KubernetesClient): Promise<any> {
+    try {
+      const result = await client.resources.namespace.list();
+      const namespaces = result.items.map((ns: any) => ({
+        metadata: formatResourceMetadata(ns),
+        status: formatResourceStatus(ns),
+      }));
+      return {
+        total: namespaces.length,
+        namespaces,
+        cluster: client.getCurrentCluster ? client.getCurrentCluster() : undefined,
+      };
+    } catch (error: any) {
+      const errorMessage = error.response?.body?.message || error.message || 'Unknown error';
+      throw new Error(`Failed to list namespaces: ${errorMessage}`);
+    }
+  }
+}

package/src/tools/kubernetes/GetPersistentVolumeClaimsTool.ts

@@ -0,0 +1,113 @@
+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 Volume Claims in a Kubernetes cluster
+ */
+export class GetPersistentVolumeClaimsTool implements BaseTool {
+  tool: Tool = {
+    name: 'get_persistent_volume_claims',
+    description:
+      'List Persistent Volume Claim resources in the current Kubernetes cluster and optionally analyze their status (similar to `kubectl get pvc`)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        namespace: CommonSchemas.namespace,
+        labelSelector: CommonSchemas.labelSelector,
+        fieldSelector: CommonSchemas.fieldSelector,
+        storageClass: {
+          type: 'string',
+          description: 'Filter by storage class name',
+          optional: true,
+        },
+        accessMode: {
+          type: 'string',
+          description: 'Filter by access mode (ReadWriteOnce, ReadOnlyMany, ReadWriteMany)',
+          optional: true,
+        },
+        volumeMode: {
+          type: 'string',
+          description: 'Filter by volume mode (Filesystem, Block)',
+          optional: true,
+        },
+        analyze: {
+          type: 'boolean',
+          description: 'Include detailed analysis with issue detection and binding status',
+          optional: true,
+          default: true,
+        },
+      },
+    },
+  };
+
+  async execute(params: any, client: KubernetesClient): Promise<any> {
+    try {
+      const {
+        namespace,
+        labelSelector,
+        fieldSelector,
+        storageClass,
+        accessMode,
+        volumeMode,
+        analyze = true,
+      } = params || {};
+      const pvcOperations = client.resources.persistentVolumeClaims;
+
+      let analysis = {};
+      if (analyze) {
+        analysis = await pvcOperations.analyzePVCs({
+          namespace,
+          labelSelector,
+          fieldSelector,
+          storageClass,
+          accessMode,
+          volumeMode,
+        });
+      }
+
+      const bindingStatus = await pvcOperations.checkBindingStatus();
+
+      const res = await pvcOperations.list({
+        namespace,
+        labelSelector,
+        fieldSelector,
+        storageClass,
+        accessMode,
+        volumeMode,
+      });
+
+      const persistentVolumeClaims = res.items.map((pvc: any) => ({
+        metadata: formatResourceMetadata(pvc),
+        spec: {
+          storageClassName: pvc.spec?.storageClassName,
+          accessModes: pvc.spec?.accessModes,
+          resources: pvc.spec?.resources,
+          volumeMode: pvc.spec?.volumeMode,
+          volumeName: pvc.spec?.volumeName,
+        },
+        status: {
+          ...formatResourceStatus(pvc),
+          phase: pvc.status?.phase,
+          capacity: pvc.status?.capacity,
+        },
+      }));
+
+      return {
+        total: persistentVolumeClaims.length,
+        namespace: namespace || 'all',
+        analysis,
+        bindingStatus,
+        persistentVolumeClaims,
+      };
+    } catch (error: any) {
+      const errorMessage = error.response?.body?.message || error.message || 'Unknown error';
+      throw new Error(`Failed to list persistent volume claims: ${errorMessage}`);
+    }
+  }
+}