@zerry_jin/k8s-doctor-mcp 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,337 @@
+/**
+ * K8s Doctor type definitions
+ *
+ * @author zerry
+ */
+/**
+ * Diagnostic severity
+ * Represents urgency of Kubernetes issues
+ */
+export type Severity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+/**
+ * Pod status
+ * Possible pod states in K8s
+ */
+export type PodPhase = 'Pending' | 'Running' | 'Succeeded' | 'Failed' | 'Unknown';
+/**
+ * Diagnostic issue
+ *
+ * Contains each detected problem and solution.
+ * Not just showing status but explaining "why this is a problem"
+ */
+export interface DiagnosticIssue {
+    /** Issue type (e.g., "CrashLoopBackOff", "ImagePullBackOff") */
+    type: string;
+    /** Severity */
+    severity: Severity;
+    /** Human-readable description */
+    message: string;
+    /** Root cause analysis */
+    rootCause: string;
+    /** Suggested solution (includes specific kubectl commands) */
+    solution: string;
+    /** Related resource (pod name, namespace, etc.) */
+    resource?: {
+        kind: string;
+        name: string;
+        namespace: string;
+    };
+    /** Related log lines */
+    relevantLogs?: string[];
+    /** Related events */
+    relatedEvents?: K8sEvent[];
+    /** Discovery timestamp */
+    timestamp: string;
+}
+/**
+ * Pod diagnostics result
+ *
+ * Comprehensive diagnostics combining pod status, resource usage, events, etc.
+ */
+export interface PodDiagnostics {
+    /** Pod basic information */
+    podInfo: {
+        name: string;
+        namespace: string;
+        phase: PodPhase;
+        startTime?: string;
+        nodeName?: string;
+        hostIP?: string;
+        podIP?: string;
+    };
+    /** Container status */
+    containers: ContainerStatus[];
+    /** Detected issues */
+    issues: DiagnosticIssue[];
+    /** Resource usage */
+    resources: ResourceUsage;
+    /** Recent events (problem-related) */
+    events: K8sEvent[];
+    /** Diagnosis summary */
+    summary: string;
+    /** Health score (0-100) */
+    healthScore: number;
+}
+/**
+ * Container status
+ */
+export interface ContainerStatus {
+    /** Container name */
+    name: string;
+    /** Ready status */
+    ready: boolean;
+    /** Restart count */
+    restartCount: number;
+    /** Current state */
+    state: {
+        running?: {
+            startedAt: string;
+        };
+        waiting?: {
+            reason: string;
+            message?: string;
+        };
+        terminated?: {
+            reason: string;
+            exitCode: number;
+            message?: string;
+        };
+    };
+    /** Last state (if restarted) */
+    lastState?: {
+        terminated?: {
+            reason: string;
+            exitCode: number;
+            finishedAt: string;
+        };
+    };
+    /** Image */
+    image: string;
+    /** Image pull status */
+    imageID?: string;
+}
+/**
+ * Resource usage
+ *
+ * CPU and memory usage with threshold comparison results
+ */
+export interface ResourceUsage {
+    /** CPU usage */
+    cpu: {
+        /** Current usage (millicores) */
+        current?: number;
+        /** Requested amount (requests) */
+        requested?: number;
+        /** Limit amount (limits) */
+        limit?: number;
+        /** Usage percentage (%) */
+        usagePercent?: number;
+        /** Threshold exceeded */
+        isThrottled: boolean;
+    };
+    /** Memory usage */
+    memory: {
+        /** Current usage (bytes) */
+        current?: number;
+        /** Requested amount (requests) */
+        requested?: number;
+        /** Limit amount (limits) */
+        limit?: number;
+        /** Usage percentage (%) */
+        usagePercent?: number;
+        /** OOM risk */
+        isOOMRisk: boolean;
+    };
+    /** Disk usage */
+    disk?: {
+        current?: number;
+        limit?: number;
+        usagePercent?: number;
+    };
+}
+/**
+ * K8s event
+ *
+ * Events shown in kubectl describe
+ */
+export interface K8sEvent {
+    /** Event type (Normal/Warning) */
+    type: string;
+    /** Reason (e.g., "Failed", "BackOff") */
+    reason: string;
+    /** Message */
+    message: string;
+    /** Occurrence count */
+    count: number;
+    /** First occurrence timestamp */
+    firstTimestamp: string;
+    /** Last occurrence timestamp */
+    lastTimestamp: string;
+    /** Source component */
+    source?: string;
+}
+/**
+ * Log analysis result
+ *
+ * Not just log output, but analyzed error patterns
+ */
+export interface LogAnalysis {
+    /** Total line count */
+    totalLines: number;
+    /** Error lines */
+    errorLines: LogEntry[];
+    /** Warning lines */
+    warningLines: LogEntry[];
+    /** Detected error patterns */
+    patterns: ErrorPattern[];
+    /** Repeated errors (same error multiple times) */
+    repeatedErrors: RepeatedError[];
+    /** Log analysis summary */
+    summary: string;
+    /** Recommendations */
+    recommendations: string[];
+}
+/**
+ * Log entry
+ */
+export interface LogEntry {
+    /** Line number */
+    lineNumber: number;
+    /** Log content */
+    content: string;
+    /** Timestamp (if parseable) */
+    timestamp?: string;
+    /** Log level */
+    level?: 'ERROR' | 'WARN' | 'INFO' | 'DEBUG';
+}
+/**
+ * Error pattern
+ *
+ * Patterns of commonly occurring errors with solutions
+ */
+export interface ErrorPattern {
+    /** Pattern name */
+    name: string;
+    /** Matched log lines */
+    matchedLines: number[];
+    /** Pattern description */
+    description: string;
+    /** Possible causes */
+    possibleCauses: string[];
+    /** Solutions */
+    solutions: string[];
+    /** Severity */
+    severity: Severity;
+}
+/**
+ * Repeated error
+ */
+export interface RepeatedError {
+    /** Error message (normalized) */
+    message: string;
+    /** Occurrence count */
+    count: number;
+    /** First occurrence line */
+    firstLine: number;
+    /** Last occurrence line */
+    lastLine: number;
+    /** Is pattern */
+    isPattern: boolean;
+}
+/**
+ * Network diagnostics result
+ */
+export interface NetworkDiagnostics {
+    /** Service connectivity */
+    serviceConnectivity: ServiceConnectivity[];
+    /** DNS issues */
+    dnsIssues: DiagnosticIssue[];
+    /** Network policy issues */
+    networkPolicyIssues: DiagnosticIssue[];
+    /** Ingress issues */
+    ingressIssues: DiagnosticIssue[];
+    /** Diagnosis summary */
+    summary: string;
+}
+/**
+ * Service connectivity
+ */
+export interface ServiceConnectivity {
+    /** Service name */
+    serviceName: string;
+    /** Namespace */
+    namespace: string;
+    /** Reachable status */
+    isReachable: boolean;
+    /** Endpoint count */
+    endpointCount: number;
+    /** Issues */
+    issues: string[];
+}
+/**
+ * Storage diagnostics result
+ */
+export interface StorageDiagnostics {
+    /** PVC status */
+    pvcStatus: PVCStatus[];
+    /** Volume mount issues */
+    mountIssues: DiagnosticIssue[];
+    /** Capacity issues */
+    capacityIssues: DiagnosticIssue[];
+    /** Diagnosis summary */
+    summary: string;
+}
+/**
+ * PVC status
+ */
+export interface PVCStatus {
+    /** PVC name */
+    name: string;
+    /** Namespace */
+    namespace: string;
+    /** Phase (Bound/Pending/Lost) */
+    phase: string;
+    /** Requested capacity */
+    requestedCapacity: string;
+    /** Actual capacity */
+    actualCapacity?: string;
+    /** Storage class */
+    storageClass?: string;
+    /** Issues */
+    issues: string[];
+}
+/**
+ * Cluster health diagnosis
+ */
+export interface ClusterHealth {
+    /** Overall health score (0-100) */
+    overallScore: number;
+    /** Node health */
+    nodeHealth: {
+        total: number;
+        ready: number;
+        notReady: number;
+        issues: DiagnosticIssue[];
+    };
+    /** Pod health */
+    podHealth: {
+        total: number;
+        running: number;
+        pending: number;
+        failed: number;
+        crashLooping: number;
+        issues: DiagnosticIssue[];
+    };
+    /** Resource utilization */
+    resourceUtilization: {
+        cpu: number;
+        memory: number;
+        storage: number;
+    };
+    /** Critical issues */
+    criticalIssues: DiagnosticIssue[];
+    /** Recommendations */
+    recommendations: string[];
+    /** Diagnosis summary */
+    summary: string;
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * K8s Doctor type definitions
+ *
+ * @author zerry
+ */
+export {};

package/dist/utils/cache.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Simple in-memory cache with TTL
+ *
+ * @author zerry
+ */
+/**
+ * Simple memory cache with TTL support
+ */
+export declare class MemoryCache<T> {
+    private cache;
+    private defaultTTL;
+    /**
+     * @param defaultTTL Default time-to-live in milliseconds (default: 30 seconds)
+     */
+    constructor(defaultTTL?: number);
+    /**
+     * Get value from cache
+     *
+     * @param key Cache key
+     * @returns Cached value or undefined if not found or expired
+     */
+    get(key: string): T | undefined;
+    /**
+     * Set value in cache
+     *
+     * @param key Cache key
+     * @param value Value to cache
+     * @param ttl Time-to-live in milliseconds (optional, uses default if not provided)
+     */
+    set(key: string, value: T, ttl?: number): void;
+    /**
+     * Delete value from cache
+     *
+     * @param key Cache key
+     */
+    delete(key: string): void;
+    /**
+     * Clear all cache entries
+     */
+    clear(): void;
+    /**
+     * Get cache size
+     */
+    size(): number;
+    /**
+     * Clean up expired entries
+     */
+    cleanup(): void;
+}
+/**
+ * Get or compute cached value
+ *
+ * @param cache Cache instance
+ * @param key Cache key
+ * @param computeFn Function to compute value if not cached
+ * @param ttl Optional TTL override
+ * @returns Cached or computed value
+ */
+export declare function getOrCompute<T>(cache: MemoryCache<T>, key: string, computeFn: () => Promise<T>, ttl?: number): Promise<T>;

package/dist/utils/cache.js

@@ -0,0 +1,99 @@
+/**
+ * Simple in-memory cache with TTL
+ *
+ * @author zerry
+ */
+/**
+ * Simple memory cache with TTL support
+ */
+export class MemoryCache {
+    cache = new Map();
+    defaultTTL;
+    /**
+     * @param defaultTTL Default time-to-live in milliseconds (default: 30 seconds)
+     */
+    constructor(defaultTTL = 30000) {
+        this.defaultTTL = defaultTTL;
+    }
+    /**
+     * Get value from cache
+     *
+     * @param key Cache key
+     * @returns Cached value or undefined if not found or expired
+     */
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return undefined;
+        }
+        // Check if expired
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    /**
+     * Set value in cache
+     *
+     * @param key Cache key
+     * @param value Value to cache
+     * @param ttl Time-to-live in milliseconds (optional, uses default if not provided)
+     */
+    set(key, value, ttl) {
+        const expiresAt = Date.now() + (ttl ?? this.defaultTTL);
+        this.cache.set(key, { value, expiresAt });
+    }
+    /**
+     * Delete value from cache
+     *
+     * @param key Cache key
+     */
+    delete(key) {
+        this.cache.delete(key);
+    }
+    /**
+     * Clear all cache entries
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get cache size
+     */
+    size() {
+        return this.cache.size;
+    }
+    /**
+     * Clean up expired entries
+     */
+    cleanup() {
+        const now = Date.now();
+        for (const [key, entry] of this.cache.entries()) {
+            if (now > entry.expiresAt) {
+                this.cache.delete(key);
+            }
+        }
+    }
+}
+/**
+ * Get or compute cached value
+ *
+ * @param cache Cache instance
+ * @param key Cache key
+ * @param computeFn Function to compute value if not cached
+ * @param ttl Optional TTL override
+ * @returns Cached or computed value
+ */
+export async function getOrCompute(cache, key, computeFn, ttl) {
+    // Try to get from cache first
+    const cached = cache.get(key);
+    if (cached !== undefined) {
+        return cached;
+    }
+    // Compute value
+    const value = await computeFn();
+    // Cache it
+    cache.set(key, value, ttl);
+    return value;
+}

package/dist/utils/formatters.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Result formatting utilities
+ *
+ * @author zerry
+ */
+import type { DiagnosticIssue, Severity } from '../types.js';
+/**
+ * Convert bytes to human-readable format
+ *
+ * 1024 -> "1 KiB"
+ * 1048576 -> "1 MiB"
+ */
+export declare function formatBytes(bytes: number): string;
+/**
+ * Convert millicores to human-readable format
+ *
+ * 1000 -> "1 core"
+ * 500 -> "0.5 cores"
+ */
+export declare function formatCPU(millicores: number): string;
+/**
+ * Return emoji based on severity
+ */
+export declare function getSeverityEmoji(severity: Severity): string;
+/**
+ * Convert health score to emoji
+ */
+export declare function getHealthEmoji(score: number): string;
+/**
+ * Convert timestamp to relative time
+ *
+ * "2 hours ago", "5 minutes ago" 등
+ */
+export declare function timeAgo(timestamp: string): string;
+/**
+ * Format issue list as markdown
+ */
+export declare function formatIssues(issues: DiagnosticIssue[]): string;
+/**
+ * Output diagnosis results as clean table
+ */
+export declare function createTable(headers: string[], rows: string[][]): string;
+/**
+ * Display percent as progress bar
+ *
+ * 85% -> "████████░░ 85%"
+ */
+export declare function progressBar(percent: number, width?: number): string;

package/dist/utils/formatters.js

@@ -0,0 +1,129 @@
+/**
+ * Result formatting utilities
+ *
+ * @author zerry
+ */
+/**
+ * Convert bytes to human-readable format
+ *
+ * 1024 -> "1 KiB"
+ * 1048576 -> "1 MiB"
+ */
+export function formatBytes(bytes) {
+    if (bytes === 0)
+        return '0 B';
+    const k = 1024;
+    const sizes = ['B', 'KiB', 'MiB', 'GiB', 'TiB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return `${(bytes / Math.pow(k, i)).toFixed(2)} ${sizes[i]}`;
+}
+/**
+ * Convert millicores to human-readable format
+ *
+ * 1000 -> "1 core"
+ * 500 -> "0.5 cores"
+ */
+export function formatCPU(millicores) {
+    const cores = millicores / 1000;
+    return `${cores.toFixed(2)} ${cores === 1 ? 'core' : 'cores'}`;
+}
+/**
+ * Return emoji based on severity
+ */
+export function getSeverityEmoji(severity) {
+    const emojis = {
+        critical: '🔴',
+        high: '🟠',
+        medium: '🟡',
+        low: '🔵',
+        info: '⚪',
+    };
+    return emojis[severity] || '⚪';
+}
+/**
+ * Convert health score to emoji
+ */
+export function getHealthEmoji(score) {
+    if (score >= 90)
+        return '💚';
+    if (score >= 70)
+        return '💛';
+    if (score >= 50)
+        return '🧡';
+    return '❤️';
+}
+/**
+ * Convert timestamp to relative time
+ *
+ * "2 hours ago", "5 minutes ago" 등
+ */
+export function timeAgo(timestamp) {
+    const now = new Date();
+    const past = new Date(timestamp);
+    const diffMs = now.getTime() - past.getTime();
+    const diffSec = Math.floor(diffMs / 1000);
+    const diffMin = Math.floor(diffSec / 60);
+    const diffHour = Math.floor(diffMin / 60);
+    const diffDay = Math.floor(diffHour / 24);
+    if (diffDay > 0)
+        return `${diffDay}days ago`;
+    if (diffHour > 0)
+        return `${diffHour}hours ago`;
+    if (diffMin > 0)
+        return `${diffMin}minutes ago`;
+    return `${diffSec}seconds ago`;
+}
+/**
+ * Format issue list as markdown
+ */
+export function formatIssues(issues) {
+    if (issues.length === 0) {
+        return '✅ No issues found!';
+    }
+    let result = `## 🔍 Detected Issues (${issues.length})\n\n`;
+    // Severity별로 정렬
+    const sorted = [...issues].sort((a, b) => {
+        const severityOrder = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+        return severityOrder[a.severity] - severityOrder[b.severity];
+    });
+    for (const issue of sorted) {
+        result += `### ${getSeverityEmoji(issue.severity)} ${issue.type}\n\n`;
+        result += `**Severity**: ${issue.severity.toUpperCase()}\n\n`;
+        result += `**Problem**: ${issue.message}\n\n`;
+        result += `**Root Cause**: ${issue.rootCause}\n\n`;
+        result += `**Solution**:\n${issue.solution}\n\n`;
+        if (issue.relevantLogs && issue.relevantLogs.length > 0) {
+            result += `**Related Logs**:\n\`\`\`\n${issue.relevantLogs.join('\n')}\n\`\`\`\n\n`;
+        }
+        if (issue.resource) {
+            result += `**Resource**: ${issue.resource.kind}/${issue.resource.name} (ns: ${issue.resource.namespace})\n\n`;
+        }
+        result += '---\n\n';
+    }
+    return result;
+}
+/**
+ * Output diagnosis results as clean table
+ */
+export function createTable(headers, rows) {
+    const colWidths = headers.map((h, i) => {
+        const maxRowWidth = Math.max(...rows.map(r => (r[i] || '').length));
+        return Math.max(h.length, maxRowWidth);
+    });
+    let table = '| ' + headers.map((h, i) => h.padEnd(colWidths[i])).join(' | ') + ' |\n';
+    table += '| ' + colWidths.map(w => '-'.repeat(w)).join(' | ') + ' |\n';
+    for (const row of rows) {
+        table += '| ' + row.map((cell, i) => (cell || '').padEnd(colWidths[i])).join(' | ') + ' |\n';
+    }
+    return table;
+}
+/**
+ * Display percent as progress bar
+ *
+ * 85% -> "████████░░ 85%"
+ */
+export function progressBar(percent, width = 10) {
+    const filled = Math.round((percent / 100) * width);
+    const empty = width - filled;
+    return '█'.repeat(filled) + '░'.repeat(empty) + ` ${percent.toFixed(1)}%`;
+}

package/dist/utils/k8s-client.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Kubernetes client initialization
+ *
+ * @author zerry
+ */
+import * as k8s from '@kubernetes/client-node';
+/**
+ * Load K8s configuration
+ *
+ * Automatically finds and loads kubeconfig.
+ * Works in-cluster as well
+ */
+export declare function loadK8sConfig(): k8s.KubeConfig;
+/**
+ * Create K8s API clients
+ *
+ * Creates frequently used API clients at once
+ */
+export declare function createK8sClients(kc: k8s.KubeConfig): {
+    core: k8s.CoreV1Api;
+    apps: k8s.AppsV1Api;
+    batch: k8s.BatchV1Api;
+    networking: k8s.NetworkingV1Api;
+    storage: k8s.StorageV1Api;
+    log: k8s.Log;
+    metrics: k8s.Metrics;
+};
+/**
+ * Validate namespace
+ *
+ * Check if namespace actually exists
+ */
+export declare function validateNamespace(coreApi: k8s.CoreV1Api, namespace: string): Promise<boolean>;
+/**
+ * Check if pod exists
+ */
+export declare function podExists(coreApi: k8s.CoreV1Api, namespace: string, podName: string): Promise<boolean>;