regen-koi-mcp 1.0.6 → 1.1.0

package/dist/logger.js

@@ -0,0 +1,133 @@
+/**
+ * Logger Module - Structured Logging for KOI MCP Server
+ *
+ * Uses pino for fast, structured JSON logging.
+ * Logs to stderr to avoid interfering with MCP stdio transport.
+ */
+import pino from 'pino';
+// Configuration
+const LOG_LEVEL = process.env.LOG_LEVEL || 'info';
+const SERVER_NAME = process.env.MCP_SERVER_NAME || 'regen-koi';
+// Create the logger instance
+// MCP uses stdio, so we log to stderr to avoid protocol interference
+export const logger = pino({
+    name: SERVER_NAME,
+    level: LOG_LEVEL,
+    // Output to stderr (fd: 2) to avoid MCP stdio conflicts
+    transport: {
+        target: 'pino/file',
+        options: { destination: 2 } // stderr
+    },
+    formatters: {
+        level: (label) => ({ level: label }),
+        bindings: () => ({}) // Remove pid and hostname for cleaner logs
+    },
+    timestamp: pino.stdTimeFunctions.isoTime,
+    // Custom serializers for common objects
+    serializers: {
+        err: pino.stdSerializers.err,
+        error: pino.stdSerializers.err,
+        // Custom serializer for query parameters
+        params: (params) => {
+            if (!params)
+                return undefined;
+            // Redact sensitive fields if any
+            const safe = { ...params };
+            if (safe.password)
+                safe.password = '[REDACTED]';
+            if (safe.api_key)
+                safe.api_key = '[REDACTED]';
+            return safe;
+        }
+    }
+});
+/**
+ * Create a child logger with context (e.g., for a specific tool or request)
+ */
+export function createChildLogger(context) {
+    return logger.child(context);
+}
+/**
+ * Log a query execution with timing
+ */
+export function logQuery(opts) {
+    const { tool, query_type, params, duration_ms, result_count, success = true, error, cached, via } = opts;
+    const logData = {
+        action: 'query',
+        tool,
+        query_type,
+        params,
+        duration_ms,
+        result_count,
+        cached: cached || false,
+        via
+    };
+    if (success) {
+        logger.info(logData, `Query completed: ${tool}${query_type ? `/${query_type}` : ''}`);
+    }
+    else {
+        logger.error({ ...logData, error }, `Query failed: ${tool}${query_type ? `/${query_type}` : ''}`);
+    }
+}
+/**
+ * Log an API call
+ */
+export function logApiCall(opts) {
+    const { endpoint, method, duration_ms, status, success, error } = opts;
+    const logData = {
+        action: 'api_call',
+        endpoint,
+        method,
+        duration_ms,
+        status
+    };
+    if (success) {
+        logger.info(logData, `API call succeeded: ${method} ${endpoint}`);
+    }
+    else {
+        logger.error({ ...logData, error }, `API call failed: ${method} ${endpoint}`);
+    }
+}
+/**
+ * Log cache operations
+ */
+export function logCacheOp(opts) {
+    logger.debug({
+        action: 'cache',
+        ...opts
+    }, `Cache ${opts.operation}: ${opts.key.substring(0, 50)}`);
+}
+/**
+ * Log circuit breaker state changes
+ */
+export function logCircuitBreaker(opts) {
+    const level = opts.state === 'open' ? 'warn' : 'info';
+    logger[level]({
+        action: 'circuit_breaker',
+        ...opts,
+        reset_at: opts.reset_at?.toISOString()
+    }, `Circuit breaker ${opts.state} for ${opts.service}`);
+}
+/**
+ * Log startup information
+ */
+export function logStartup(config) {
+    logger.info({
+        action: 'startup',
+        ...config
+    }, `KOI MCP Server starting v${config.version}`);
+}
+/**
+ * Log health check results
+ */
+export function logHealthCheck(checks) {
+    const allHealthy = Object.values(checks).every(v => v);
+    const level = allHealthy ? 'info' : 'warn';
+    logger[level]({
+        action: 'health_check',
+        checks,
+        healthy: allHealthy
+    }, `Health check: ${allHealthy ? 'HEALTHY' : 'DEGRADED'}`);
+}
+export default logger;
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"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"}

package/dist/metrics.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Metrics Module - Performance Tracking for KOI MCP Server
+ *
+ * Tracks query latency, error rates, cache hit rates, and other metrics.
+ * Provides in-memory metrics collection with percentile calculations.
+ */
+/**
+ * Main Metrics class - singleton pattern
+ */
+declare class Metrics {
+    private static instance;
+    private toolMetrics;
+    private cacheHits;
+    private cacheMisses;
+    private circuitBreaks;
+    private apiLatencies;
+    private apiErrors;
+    private apiCalls;
+    private startTime;
+    private constructor();
+    static getInstance(): Metrics;
+    /**
+     * Get or create metrics for a specific tool
+     */
+    private getToolMetrics;
+    /**
+     * Record a query execution
+     */
+    recordQuery(toolName: string, durationMs: number, success: boolean, errorMessage?: string): void;
+    /**
+     * Record cache hit/miss
+     */
+    recordCacheHit(): void;
+    recordCacheMiss(): void;
+    /**
+     * Record circuit breaker open
+     */
+    recordCircuitBreak(): void;
+    /**
+     * Record API call
+     */
+    recordApiCall(durationMs: number, success: boolean): void;
+    /**
+     * Get metrics for a specific tool
+     */
+    getToolStats(toolName: string): {
+        total_queries: number;
+        success_rate: number;
+        error_count: number;
+        p50_latency_ms: number;
+        p95_latency_ms: number;
+        p99_latency_ms: number;
+        avg_latency_ms: number;
+        last_error?: {
+            message: string;
+            timestamp: string;
+        };
+    };
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        hits: number;
+        misses: number;
+        hit_rate: number;
+    };
+    /**
+     * Get API statistics
+     */
+    getApiStats(): {
+        total_calls: number;
+        error_rate: number;
+        p50_latency_ms: number;
+        p95_latency_ms: number;
+        p99_latency_ms: number;
+    };
+    /**
+     * Get all metrics as a summary object
+     */
+    getSummary(): {
+        uptime_seconds: number;
+        tools: Record<string, ReturnType<Metrics['getToolStats']>>;
+        cache: ReturnType<Metrics['getCacheStats']>;
+        api: ReturnType<Metrics['getApiStats']>;
+        circuit_breaks: number;
+    };
+    /**
+     * Format metrics as markdown for display
+     */
+    formatAsMarkdown(): string;
+    /**
+     * Reset all metrics (useful for testing)
+     */
+    reset(): void;
+}
+export declare const metrics: Metrics;
+export declare function recordQuery(toolName: string, durationMs: number, success: boolean, errorMessage?: string): void;
+export declare function recordCacheHit(): void;
+export declare function recordCacheMiss(): void;
+export declare function recordCircuitBreak(): void;
+export declare function recordApiCall(durationMs: number, success: boolean): void;
+export declare function getMetricsSummary(): {
+    uptime_seconds: number;
+    tools: Record<string, ReturnType<Metrics["getToolStats"]>>;
+    cache: ReturnType<Metrics["getCacheStats"]>;
+    api: ReturnType<Metrics["getApiStats"]>;
+    circuit_breaks: number;
+};
+export declare function getMetricsMarkdown(): string;
+export default metrics;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"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"}

package/dist/metrics.js

@@ -0,0 +1,279 @@
+/**
+ * Metrics Module - Performance Tracking for KOI MCP Server
+ *
+ * Tracks query latency, error rates, cache hit rates, and other metrics.
+ * Provides in-memory metrics collection with percentile calculations.
+ */
+/**
+ * Calculate percentile from sorted array
+ */
+function percentile(sortedArr, p) {
+    if (sortedArr.length === 0)
+        return 0;
+    const index = Math.ceil((p / 100) * sortedArr.length) - 1;
+    return sortedArr[Math.max(0, index)];
+}
+/**
+ * Sliding window for tracking recent values
+ */
+class SlidingWindow {
+    values = [];
+    maxSize;
+    constructor(maxSize = 1000) {
+        this.maxSize = maxSize;
+    }
+    add(value) {
+        this.values.push(value);
+        if (this.values.length > this.maxSize) {
+            this.values.shift();
+        }
+    }
+    getValues() {
+        return [...this.values];
+    }
+    getSorted() {
+        return [...this.values].sort((a, b) => a - b);
+    }
+    clear() {
+        this.values = [];
+    }
+    get length() {
+        return this.values.length;
+    }
+}
+/**
+ * Counter for tracking counts (errors, requests, etc.)
+ */
+class Counter {
+    value = 0;
+    increment(amount = 1) {
+        this.value += amount;
+    }
+    getValue() {
+        return this.value;
+    }
+    reset() {
+        this.value = 0;
+    }
+}
+/**
+ * Main Metrics class - singleton pattern
+ */
+class Metrics {
+    static instance;
+    // Per-tool metrics
+    toolMetrics = new Map();
+    // Cache metrics
+    cacheHits = new Counter();
+    cacheMisses = new Counter();
+    // Circuit breaker metrics
+    circuitBreaks = new Counter();
+    // API call metrics
+    apiLatencies = new SlidingWindow(500);
+    apiErrors = new Counter();
+    apiCalls = new Counter();
+    // Start time for uptime calculation
+    startTime = new Date();
+    constructor() { }
+    static getInstance() {
+        if (!Metrics.instance) {
+            Metrics.instance = new Metrics();
+        }
+        return Metrics.instance;
+    }
+    /**
+     * Get or create metrics for a specific tool
+     */
+    getToolMetrics(toolName) {
+        let metrics = this.toolMetrics.get(toolName);
+        if (!metrics) {
+            metrics = {
+                latencies: new SlidingWindow(200),
+                successCount: new Counter(),
+                errorCount: new Counter()
+            };
+            this.toolMetrics.set(toolName, metrics);
+        }
+        return metrics;
+    }
+    /**
+     * Record a query execution
+     */
+    recordQuery(toolName, durationMs, success, errorMessage) {
+        const metrics = this.getToolMetrics(toolName);
+        metrics.latencies.add(durationMs);
+        if (success) {
+            metrics.successCount.increment();
+        }
+        else {
+            metrics.errorCount.increment();
+            metrics.lastError = {
+                message: errorMessage || 'Unknown error',
+                timestamp: new Date()
+            };
+        }
+    }
+    /**
+     * Record cache hit/miss
+     */
+    recordCacheHit() {
+        this.cacheHits.increment();
+    }
+    recordCacheMiss() {
+        this.cacheMisses.increment();
+    }
+    /**
+     * Record circuit breaker open
+     */
+    recordCircuitBreak() {
+        this.circuitBreaks.increment();
+    }
+    /**
+     * Record API call
+     */
+    recordApiCall(durationMs, success) {
+        this.apiLatencies.add(durationMs);
+        this.apiCalls.increment();
+        if (!success) {
+            this.apiErrors.increment();
+        }
+    }
+    /**
+     * Get metrics for a specific tool
+     */
+    getToolStats(toolName) {
+        const metrics = this.getToolMetrics(toolName);
+        const sorted = metrics.latencies.getSorted();
+        const totalQueries = metrics.successCount.getValue() + metrics.errorCount.getValue();
+        const avgLatency = sorted.length > 0
+            ? sorted.reduce((a, b) => a + b, 0) / sorted.length
+            : 0;
+        return {
+            total_queries: totalQueries,
+            success_rate: totalQueries > 0
+                ? metrics.successCount.getValue() / totalQueries
+                : 1,
+            error_count: metrics.errorCount.getValue(),
+            p50_latency_ms: percentile(sorted, 50),
+            p95_latency_ms: percentile(sorted, 95),
+            p99_latency_ms: percentile(sorted, 99),
+            avg_latency_ms: Math.round(avgLatency * 100) / 100,
+            last_error: metrics.lastError ? {
+                message: metrics.lastError.message,
+                timestamp: metrics.lastError.timestamp.toISOString()
+            } : undefined
+        };
+    }
+    /**
+     * Get cache statistics
+     */
+    getCacheStats() {
+        const hits = this.cacheHits.getValue();
+        const misses = this.cacheMisses.getValue();
+        const total = hits + misses;
+        return {
+            hits,
+            misses,
+            hit_rate: total > 0 ? hits / total : 0
+        };
+    }
+    /**
+     * Get API statistics
+     */
+    getApiStats() {
+        const sorted = this.apiLatencies.getSorted();
+        const totalCalls = this.apiCalls.getValue();
+        return {
+            total_calls: totalCalls,
+            error_rate: totalCalls > 0
+                ? this.apiErrors.getValue() / totalCalls
+                : 0,
+            p50_latency_ms: percentile(sorted, 50),
+            p95_latency_ms: percentile(sorted, 95),
+            p99_latency_ms: percentile(sorted, 99)
+        };
+    }
+    /**
+     * Get all metrics as a summary object
+     */
+    getSummary() {
+        const tools = {};
+        for (const [toolName] of this.toolMetrics) {
+            tools[toolName] = this.getToolStats(toolName);
+        }
+        return {
+            uptime_seconds: Math.round((Date.now() - this.startTime.getTime()) / 1000),
+            tools,
+            cache: this.getCacheStats(),
+            api: this.getApiStats(),
+            circuit_breaks: this.circuitBreaks.getValue()
+        };
+    }
+    /**
+     * Format metrics as markdown for display
+     */
+    formatAsMarkdown() {
+        const summary = this.getSummary();
+        let md = `# KOI MCP Server Metrics\n\n`;
+        md += `**Uptime:** ${summary.uptime_seconds}s\n\n`;
+        md += `## Cache\n`;
+        md += `- Hit Rate: ${(summary.cache.hit_rate * 100).toFixed(1)}%\n`;
+        md += `- Hits: ${summary.cache.hits} | Misses: ${summary.cache.misses}\n\n`;
+        md += `## API Calls\n`;
+        md += `- Total: ${summary.api.total_calls}\n`;
+        md += `- Error Rate: ${(summary.api.error_rate * 100).toFixed(2)}%\n`;
+        md += `- Latency: p50=${summary.api.p50_latency_ms}ms, p95=${summary.api.p95_latency_ms}ms, p99=${summary.api.p99_latency_ms}ms\n\n`;
+        if (Object.keys(summary.tools).length > 0) {
+            md += `## Tools\n\n`;
+            md += `| Tool | Queries | Success Rate | p95 Latency |\n`;
+            md += `|------|---------|--------------|-------------|\n`;
+            for (const [toolName, stats] of Object.entries(summary.tools)) {
+                md += `| ${toolName} | ${stats.total_queries} | ${(stats.success_rate * 100).toFixed(1)}% | ${stats.p95_latency_ms}ms |\n`;
+            }
+        }
+        if (summary.circuit_breaks > 0) {
+            md += `\n## Circuit Breaker\n`;
+            md += `- Circuit Breaks: ${summary.circuit_breaks}\n`;
+        }
+        return md;
+    }
+    /**
+     * Reset all metrics (useful for testing)
+     */
+    reset() {
+        this.toolMetrics.clear();
+        this.cacheHits = new Counter();
+        this.cacheMisses = new Counter();
+        this.circuitBreaks = new Counter();
+        this.apiLatencies = new SlidingWindow(500);
+        this.apiErrors = new Counter();
+        this.apiCalls = new Counter();
+        this.startTime = new Date();
+    }
+}
+// Export singleton instance
+export const metrics = Metrics.getInstance();
+// Export convenience functions
+export function recordQuery(toolName, durationMs, success, errorMessage) {
+    metrics.recordQuery(toolName, durationMs, success, errorMessage);
+}
+export function recordCacheHit() {
+    metrics.recordCacheHit();
+}
+export function recordCacheMiss() {
+    metrics.recordCacheMiss();
+}
+export function recordCircuitBreak() {
+    metrics.recordCircuitBreak();
+}
+export function recordApiCall(durationMs, success) {
+    metrics.recordApiCall(durationMs, success);
+}
+export function getMetricsSummary() {
+    return metrics.getSummary();
+}
+export function getMetricsMarkdown() {
+    return metrics.formatAsMarkdown();
+}
+export default metrics;
+//# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"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"}

package/dist/resilience.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Resilience Module - Retry Logic, Circuit Breaker, Timeouts
+ *
+ * Provides utilities for making the MCP server fault-tolerant:
+ * - Exponential backoff retry for transient failures
+ * - Circuit breaker to prevent cascading failures
+ * - Timeout wrapper for long-running operations
+ */
+/**
+ * Check if an error is retriable (transient failure)
+ */
+export declare function isRetriableError(error: any): boolean;
+/**
+ * Options for retry logic
+ */
+export interface RetryOptions {
+    maxRetries?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    backoffMultiplier?: number;
+    shouldRetry?: (error: any) => boolean;
+    onRetry?: (error: any, attempt: number, delayMs: number) => void;
+}
+/**
+ * Execute a function with exponential backoff retry
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Circuit Breaker State
+ */
+type CircuitState = 'closed' | 'open' | 'half-open';
+/**
+ * Circuit Breaker options
+ */
+export interface CircuitBreakerOptions {
+    failureThreshold?: number;
+    resetTimeoutMs?: number;
+    halfOpenMaxCalls?: number;
+    onStateChange?: (from: CircuitState, to: CircuitState) => void;
+}
+/**
+ * Circuit Breaker class for preventing cascading failures
+ */
+export declare class CircuitBreaker {
+    private state;
+    private failureCount;
+    private successCount;
+    private lastFailureTime?;
+    private halfOpenCalls;
+    private options;
+    private serviceName;
+    constructor(serviceName: string, options?: CircuitBreakerOptions);
+    /**
+     * Get current circuit state
+     */
+    getState(): CircuitState;
+    /**
+     * Transition to a new state
+     */
+    private transitionTo;
+    /**
+     * Execute a function through the circuit breaker
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Record a successful call
+     */
+    private recordSuccess;
+    /**
+     * Record a failed call
+     */
+    private recordFailure;
+    /**
+     * Manually reset the circuit breaker
+     */
+    reset(): void;
+    /**
+     * Get circuit breaker stats
+     */
+    getStats(): {
+        state: CircuitState;
+        failureCount: number;
+        successCount: number;
+        lastFailure?: string;
+    };
+}
+/**
+ * Custom error for circuit breaker open state
+ */
+export declare class CircuitBreakerError extends Error {
+    serviceName: string;
+    retryAfter?: Date | undefined;
+    constructor(message: string, serviceName: string, retryAfter?: Date | undefined);
+}
+/**
+ * Custom error for timeouts
+ */
+export declare class TimeoutError extends Error {
+    timeoutMs: number;
+    constructor(message: string, timeoutMs: number);
+}
+/**
+ * Execute a function with a timeout
+ */
+export declare function withTimeout<T>(fn: () => Promise<T>, timeoutMs: number, operationName?: string): Promise<T>;
+/**
+ * Combine retry and timeout
+ */
+export declare function withRetryAndTimeout<T>(fn: () => Promise<T>, timeoutMs: number, retryOptions?: RetryOptions, operationName?: string): Promise<T>;
+export declare const circuitBreakers: {
+    graphApi: CircuitBreaker;
+    koiApi: CircuitBreaker;
+    database: CircuitBreaker;
+};
+declare const _default: {
+    withRetry: typeof withRetry;
+    withTimeout: typeof withTimeout;
+    withRetryAndTimeout: typeof withRetryAndTimeout;
+    CircuitBreaker: typeof CircuitBreaker;
+    circuitBreakers: {
+        graphApi: CircuitBreaker;
+        koiApi: CircuitBreaker;
+        database: CircuitBreaker;
+    };
+    isRetriableError: typeof isRetriableError;
+};
+export default _default;
+//# sourceMappingURL=resilience.d.ts.map

package/dist/resilience.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resilience.d.ts","sourceRoot":"","sources":["../src/resilience.ts"],"names":[],"mappings":"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"}