@thotischner/observability-mcp 1.0.0

package/config/sources.yaml

@@ -0,0 +1,45 @@
+sources:
+  - name: prometheus
+    type: prometheus
+    url: http://prometheus:9090
+    enabled: true
+    # metrics:  # Uncomment to override default Prometheus metrics
+    #   - name: custom_metric
+    #     query: 'my_custom_metric{job="{{service}}"}'
+    #     unit: requests
+    #     description: My custom metric
+
+  - name: loki
+    type: loki
+    url: http://loki:3100
+    enabled: true
+
+settings:
+  checkIntervalMs: 30000
+  defaultSensitivity: medium
+
+healthThresholds:
+  weights:
+    errorRate: 0.35
+    latency: 0.25
+    cpu: 0.20
+    logErrors: 0.20
+  cpu:
+    good: 50
+    warn: 80
+    crit: 95
+  errorRate:
+    good: 0.01
+    warn: 0.1
+    crit: 0.5
+  latencyP99:
+    good: 0.5
+    warn: 1.0
+    crit: 3.0
+  logErrors:
+    good: 1
+    warn: 5
+    crit: 20
+  statusBoundaries:
+    healthy: 80
+    degraded: 50

package/dist/analysis/anomaly.d.ts

@@ -0,0 +1,24 @@
+import type { AnomalySeverity } from "../types.js";
+export interface ZScoreResult {
+    mean: number;
+    stdDev: number;
+    zScores: number[];
+}
+export declare function calculateZScore(values: number[]): ZScoreResult;
+export interface AnomalyPoint {
+    index: number;
+    value: number;
+    zScore: number;
+    severity: AnomalySeverity;
+}
+export declare function detectAnomalyPoints(values: number[], threshold?: number): AnomalyPoint[];
+/**
+ * Check if the most recent values deviate significantly from the baseline.
+ * Compares the last `recentWindow` values against the rest.
+ */
+export declare function detectRecentAnomaly(values: number[], recentWindow?: number, threshold?: number): {
+    isAnomaly: boolean;
+    zScore: number;
+    recentAvg: number;
+    baselineAvg: number;
+};

package/dist/analysis/anomaly.js

@@ -0,0 +1,50 @@
+export function calculateZScore(values) {
+    if (values.length === 0)
+        return { mean: 0, stdDev: 0, zScores: [] };
+    const mean = values.reduce((a, b) => a + b, 0) / values.length;
+    const variance = values.reduce((sum, v) => sum + (v - mean) ** 2, 0) / values.length;
+    const stdDev = Math.sqrt(variance);
+    const zScores = stdDev === 0
+        ? values.map(() => 0)
+        : values.map((v) => (v - mean) / stdDev);
+    return { mean, stdDev, zScores };
+}
+export function detectAnomalyPoints(values, threshold = 2.0) {
+    const { mean, stdDev, zScores } = calculateZScore(values);
+    if (stdDev === 0)
+        return [];
+    const anomalies = [];
+    for (let i = 0; i < values.length; i++) {
+        const absZ = Math.abs(zScores[i]);
+        if (absZ >= threshold) {
+            anomalies.push({
+                index: i,
+                value: values[i],
+                zScore: zScores[i],
+                severity: absZ >= 3 ? "high" : absZ >= 2 ? "medium" : "low",
+            });
+        }
+    }
+    return anomalies;
+}
+/**
+ * Check if the most recent values deviate significantly from the baseline.
+ * Compares the last `recentWindow` values against the rest.
+ */
+export function detectRecentAnomaly(values, recentWindow = 5, threshold = 2.0) {
+    if (values.length < recentWindow + 5) {
+        return { isAnomaly: false, zScore: 0, recentAvg: 0, baselineAvg: 0 };
+    }
+    const baseline = values.slice(0, -recentWindow);
+    const recent = values.slice(-recentWindow);
+    const baselineAvg = baseline.reduce((a, b) => a + b, 0) / baseline.length;
+    const baselineStdDev = Math.sqrt(baseline.reduce((sum, v) => sum + (v - baselineAvg) ** 2, 0) / baseline.length);
+    const recentAvg = recent.reduce((a, b) => a + b, 0) / recent.length;
+    const zScore = baselineStdDev === 0 ? 0 : (recentAvg - baselineAvg) / baselineStdDev;
+    return {
+        isAnomaly: Math.abs(zScore) >= threshold,
+        zScore,
+        recentAvg,
+        baselineAvg,
+    };
+}

package/dist/analysis/anomaly.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/analysis/anomaly.test.js

@@ -0,0 +1,87 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { calculateZScore, detectAnomalyPoints, detectRecentAnomaly } from "./anomaly.js";
+describe("calculateZScore", () => {
+    it("returns zeros for empty array", () => {
+        const result = calculateZScore([]);
+        assert.equal(result.mean, 0);
+        assert.equal(result.stdDev, 0);
+        assert.deepEqual(result.zScores, []);
+    });
+    it("calculates correct mean and stdDev", () => {
+        const result = calculateZScore([2, 4, 4, 4, 5, 5, 7, 9]);
+        assert.ok(Math.abs(result.mean - 5) < 0.001);
+        assert.ok(result.stdDev > 0);
+    });
+    it("returns zero z-scores for constant values", () => {
+        const result = calculateZScore([5, 5, 5, 5]);
+        assert.equal(result.mean, 5);
+        assert.equal(result.stdDev, 0);
+        assert.deepEqual(result.zScores, [0, 0, 0, 0]);
+    });
+    it("outlier has high z-score", () => {
+        const values = [10, 10, 10, 10, 10, 10, 10, 10, 10, 100];
+        const result = calculateZScore(values);
+        const lastZ = result.zScores[result.zScores.length - 1];
+        assert.ok(lastZ > 2, `Expected z-score > 2, got ${lastZ}`);
+    });
+});
+describe("detectAnomalyPoints", () => {
+    it("returns empty for constant values", () => {
+        assert.deepEqual(detectAnomalyPoints([5, 5, 5, 5]), []);
+    });
+    it("detects outlier with default threshold", () => {
+        const values = [10, 10, 10, 10, 10, 10, 10, 10, 10, 50];
+        const anomalies = detectAnomalyPoints(values);
+        assert.ok(anomalies.length > 0);
+        assert.equal(anomalies[0].index, 9);
+        assert.ok(anomalies[0].value === 50);
+    });
+    it("respects custom threshold", () => {
+        const values = [10, 10, 10, 10, 10, 10, 10, 10, 10, 15];
+        const lowThreshold = detectAnomalyPoints(values, 1.0);
+        const highThreshold = detectAnomalyPoints(values, 3.0);
+        assert.ok(lowThreshold.length >= highThreshold.length);
+    });
+    it("assigns correct severity", () => {
+        const values = [10, 10, 10, 10, 10, 10, 10, 10, 10, 100];
+        const anomalies = detectAnomalyPoints(values);
+        assert.ok(anomalies.length > 0);
+        assert.ok(["low", "medium", "high"].includes(anomalies[0].severity));
+    });
+});
+describe("detectRecentAnomaly", () => {
+    it("returns no anomaly for insufficient data", () => {
+        const result = detectRecentAnomaly([1, 2, 3]);
+        assert.equal(result.isAnomaly, false);
+    });
+    it("returns no anomaly for stable data", () => {
+        const values = Array(20).fill(10);
+        const result = detectRecentAnomaly(values);
+        assert.equal(result.isAnomaly, false);
+    });
+    it("detects spike in recent values", () => {
+        // Baseline needs some variance so stdDev > 0
+        const baseline = Array.from({ length: 20 }, (_, i) => 10 + (i % 3));
+        const spike = Array(5).fill(50);
+        const result = detectRecentAnomaly([...baseline, ...spike]);
+        assert.equal(result.isAnomaly, true);
+        assert.ok(result.zScore > 0);
+        assert.ok(result.recentAvg > 40);
+    });
+    it("detects drop in recent values", () => {
+        const baseline = Array.from({ length: 20 }, (_, i) => 50 + (i % 3));
+        const drop = Array(5).fill(5);
+        const result = detectRecentAnomaly([...baseline, ...drop]);
+        assert.equal(result.isAnomaly, true);
+        assert.ok(result.zScore < 0);
+    });
+    it("respects custom threshold", () => {
+        const baseline = Array(20).fill(10);
+        const slight = Array(5).fill(13);
+        const lowResult = detectRecentAnomaly([...baseline, ...slight], 5, 1.0);
+        const highResult = detectRecentAnomaly([...baseline, ...slight], 5, 3.0);
+        // Slight increase might trigger low threshold but not high
+        assert.ok(lowResult.isAnomaly || !highResult.isAnomaly);
+    });
+});

package/dist/analysis/correlator.d.ts

@@ -0,0 +1,7 @@
+import type { AnomalyReport, LogResult, MetricResult } from "../types.js";
+/**
+ * Cross-signal correlation: find relationships between metric anomalies and log patterns.
+ * Simple timestamp-based approach: if a metric spike and error log increase happen
+ * in the same time window, they are correlated.
+ */
+export declare function correlateSignals(anomalies: AnomalyReport[], logResults: LogResult[], metricResults: MetricResult[]): string[];

package/dist/analysis/correlator.js

@@ -0,0 +1,31 @@
+/**
+ * Cross-signal correlation: find relationships between metric anomalies and log patterns.
+ * Simple timestamp-based approach: if a metric spike and error log increase happen
+ * in the same time window, they are correlated.
+ */
+export function correlateSignals(anomalies, logResults, metricResults) {
+    const correlations = [];
+    for (const anomaly of anomalies) {
+        // Check if there's a corresponding log signal
+        const serviceLogs = logResults.find((l) => l.service === anomaly.service);
+        if (serviceLogs && serviceLogs.summary.errorCount > 0) {
+            const errorPct = serviceLogs.summary.total > 0
+                ? Math.round((serviceLogs.summary.errorCount / serviceLogs.summary.total) * 100)
+                : 0;
+            correlations.push(`${anomaly.service}: ${anomaly.metric} anomaly (${anomaly.severity}) correlates with ` +
+                `${serviceLogs.summary.errorCount} error logs (${errorPct}% of total). ` +
+                `Top error: ${serviceLogs.summary.topPatterns[0] || "N/A"}`);
+        }
+        // Check for metric cross-correlations (e.g., CPU spike + latency increase)
+        const serviceMetrics = metricResults.filter((m) => m.service === anomaly.service);
+        for (const metric of serviceMetrics) {
+            if (metric.metric === anomaly.metric)
+                continue;
+            if (metric.summary.trend === "rising") {
+                correlations.push(`${anomaly.service}: ${anomaly.metric} anomaly coincides with rising ${metric.metric} ` +
+                    `(current: ${metric.summary.current.toFixed(2)})`);
+            }
+        }
+    }
+    return [...new Set(correlations)]; // Deduplicate
+}

package/dist/analysis/correlator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/analysis/correlator.test.js

@@ -0,0 +1,53 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { correlateSignals } from "./correlator.js";
+describe("correlateSignals", () => {
+    it("returns empty for no anomalies", () => {
+        const result = correlateSignals([], [], []);
+        assert.deepEqual(result, []);
+    });
+    it("correlates metric anomaly with error logs", () => {
+        const anomalies = [{
+                metric: "cpu", severity: "high", description: "cpu spike",
+                currentValue: 95, baselineValue: 20, deviationPercent: 375,
+                source: "prometheus", service: "api-gateway",
+            }];
+        const logs = [{
+                source: "loki", service: "api-gateway",
+                entries: [],
+                summary: { total: 100, errorCount: 30, warnCount: 5, topPatterns: ["NullPointerException (15x)"] },
+            }];
+        const result = correlateSignals(anomalies, logs, []);
+        assert.ok(result.length > 0);
+        assert.ok(result[0].includes("api-gateway"));
+        assert.ok(result[0].includes("cpu"));
+    });
+    it("correlates metric cross-signals", () => {
+        const anomalies = [{
+                metric: "cpu", severity: "high", description: "cpu spike",
+                currentValue: 95, baselineValue: 20, deviationPercent: 375,
+                source: "prometheus", service: "payment",
+            }];
+        const metrics = [{
+                source: "prometheus", service: "payment", metric: "latency_p99",
+                unit: "seconds", values: [], summary: { current: 2.5, average: 0.5, min: 0.3, max: 3.0, trend: "rising" },
+            }];
+        const result = correlateSignals(anomalies, [], metrics);
+        assert.ok(result.some(c => c.includes("latency_p99") && c.includes("rising")));
+    });
+    it("does not duplicate correlations", () => {
+        const anomalies = [{
+                metric: "cpu", severity: "medium", description: "test",
+                currentValue: 80, baselineValue: 20, deviationPercent: 300,
+                source: "prometheus", service: "svc",
+            }];
+        const logs = [{
+                source: "loki", service: "svc",
+                entries: [],
+                summary: { total: 10, errorCount: 5, warnCount: 0, topPatterns: ["err"] },
+            }];
+        const result = correlateSignals(anomalies, logs, []);
+        const unique = new Set(result);
+        assert.equal(result.length, unique.size);
+    });
+});

package/dist/analysis/health.d.ts

@@ -0,0 +1,19 @@
+import type { HealthStatus, HealthThresholds } from "../types.js";
+interface HealthInputs {
+    cpu: number;
+    memory: number;
+    errorRate: number;
+    latencyP99: number;
+    logErrorRate: number;
+}
+interface HealthResult {
+    score: number;
+    status: HealthStatus;
+    details: Record<string, {
+        score: number;
+        value: number;
+        threshold: string;
+    }>;
+}
+export declare function calculateHealthScore(inputs: HealthInputs, thresholds: HealthThresholds): HealthResult;
+export {};

package/dist/analysis/health.js

@@ -0,0 +1,34 @@
+export function calculateHealthScore(inputs, thresholds) {
+    const w = thresholds.weights;
+    const t = thresholds;
+    const cpuScore = scoreFromThreshold(inputs.cpu, t.cpu.good, t.cpu.warn, t.cpu.crit);
+    const errorRateScore = scoreFromThreshold(inputs.errorRate, t.errorRate.good, t.errorRate.warn, t.errorRate.crit);
+    const latencyScore = scoreFromThreshold(inputs.latencyP99, t.latencyP99.good, t.latencyP99.warn, t.latencyP99.crit);
+    const logErrorScore = scoreFromThreshold(inputs.logErrorRate, t.logErrors.good, t.logErrors.warn, t.logErrors.crit);
+    const weightedScore = cpuScore * w.cpu +
+        errorRateScore * w.errorRate +
+        latencyScore * w.latency +
+        logErrorScore * w.logErrors;
+    const score = Math.round(Math.max(0, Math.min(100, weightedScore)));
+    const status = score > t.statusBoundaries.healthy ? "healthy" :
+        score > t.statusBoundaries.degraded ? "degraded" : "critical";
+    return {
+        score,
+        status,
+        details: {
+            cpu: { score: Math.round(cpuScore), value: inputs.cpu, threshold: `warn >${t.cpu.warn}%, crit >${t.cpu.crit}%` },
+            errorRate: { score: Math.round(errorRateScore), value: inputs.errorRate, threshold: `warn >${t.errorRate.warn}/s, crit >${t.errorRate.crit}/s` },
+            latencyP99: { score: Math.round(latencyScore), value: inputs.latencyP99, threshold: `warn >${t.latencyP99.warn}s, crit >${t.latencyP99.crit}s` },
+            logErrors: { score: Math.round(logErrorScore), value: inputs.logErrorRate, threshold: `warn >${t.logErrors.warn}/min, crit >${t.logErrors.crit}/min` },
+        },
+    };
+}
+function scoreFromThreshold(value, good, warn, crit) {
+    if (value <= good)
+        return 100;
+    if (value <= warn)
+        return 100 - ((value - good) / (warn - good)) * 40;
+    if (value <= crit)
+        return 60 - ((value - warn) / (crit - warn)) * 40;
+    return Math.max(0, 20 - ((value - crit) / crit) * 20);
+}

package/dist/analysis/health.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/analysis/health.test.js

@@ -0,0 +1,70 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { calculateHealthScore } from "./health.js";
+const defaults = {
+    weights: { errorRate: 0.35, latency: 0.25, cpu: 0.20, logErrors: 0.20 },
+    cpu: { good: 50, warn: 80, crit: 95 },
+    errorRate: { good: 0.01, warn: 0.1, crit: 0.5 },
+    latencyP99: { good: 0.5, warn: 1.0, crit: 3.0 },
+    logErrors: { good: 1, warn: 5, crit: 20 },
+    statusBoundaries: { healthy: 80, degraded: 50 },
+};
+describe("calculateHealthScore", () => {
+    it("returns healthy for all-zero inputs", () => {
+        const result = calculateHealthScore({
+            cpu: 0, memory: 0, errorRate: 0, latencyP99: 0, logErrorRate: 0,
+        }, defaults);
+        assert.equal(result.status, "healthy");
+        assert.equal(result.score, 100);
+    });
+    it("returns healthy for normal values", () => {
+        const result = calculateHealthScore({
+            cpu: 20, memory: 100_000_000, errorRate: 0.005, latencyP99: 0.3, logErrorRate: 0,
+        }, defaults);
+        assert.equal(result.status, "healthy");
+        assert.ok(result.score > 80);
+    });
+    it("returns degraded for elevated values", () => {
+        const result = calculateHealthScore({
+            cpu: 65, memory: 200_000_000, errorRate: 0.05, latencyP99: 0.8, logErrorRate: 3,
+        }, defaults);
+        assert.equal(result.status, "degraded");
+        assert.ok(result.score > 50 && result.score <= 80, `Expected degraded score 50-80, got ${result.score}`);
+    });
+    it("returns critical for extreme values", () => {
+        const result = calculateHealthScore({
+            cpu: 98, memory: 500_000_000, errorRate: 1.0, latencyP99: 5.0, logErrorRate: 50,
+        }, defaults);
+        assert.equal(result.status, "critical");
+        assert.ok(result.score <= 50);
+    });
+    it("score is between 0 and 100", () => {
+        for (const cpu of [0, 50, 100]) {
+            for (const err of [0, 0.5, 2]) {
+                const result = calculateHealthScore({
+                    cpu, memory: 0, errorRate: err, latencyP99: 0, logErrorRate: 0,
+                }, defaults);
+                assert.ok(result.score >= 0 && result.score <= 100, `Score ${result.score} out of range for cpu=${cpu} err=${err}`);
+            }
+        }
+    });
+    it("respects custom thresholds", () => {
+        const strict = {
+            ...defaults,
+            cpu: { good: 10, warn: 20, crit: 30 },
+        };
+        const result = calculateHealthScore({
+            cpu: 25, memory: 0, errorRate: 0, latencyP99: 0, logErrorRate: 0,
+        }, strict);
+        // CPU 25% with strict thresholds should lower the score
+        assert.ok(result.score < 100);
+    });
+    it("includes detail breakdown", () => {
+        const result = calculateHealthScore({
+            cpu: 60, memory: 0, errorRate: 0, latencyP99: 0, logErrorRate: 0,
+        }, defaults);
+        assert.ok("cpu" in result.details);
+        assert.ok("errorRate" in result.details);
+        assert.ok(result.details.cpu.score < 100);
+    });
+});

package/dist/config/loader.d.ts

@@ -0,0 +1,5 @@
+import type { Config, GeneralSettings, HealthThresholds } from "../types.js";
+export declare const DEFAULT_SETTINGS: GeneralSettings;
+export declare const DEFAULT_HEALTH_THRESHOLDS: HealthThresholds;
+export declare function loadConfig(): Config;
+export declare function saveConfig(config: Config): void;

package/dist/config/loader.js

@@ -0,0 +1,81 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import yaml from "js-yaml";
+function resolveConfigPath() {
+    if (process.env.CONFIG_PATH)
+        return process.env.CONFIG_PATH;
+    const localPath = "./config/sources.yaml";
+    if (existsSync(localPath))
+        return localPath;
+    return join(homedir(), ".observability-mcp", "sources.yaml");
+}
+const CONFIG_PATH = resolveConfigPath();
+export const DEFAULT_SETTINGS = {
+    checkIntervalMs: 30000,
+    defaultSensitivity: "medium",
+};
+export const DEFAULT_HEALTH_THRESHOLDS = {
+    weights: { errorRate: 0.35, latency: 0.25, cpu: 0.20, logErrors: 0.20 },
+    cpu: { good: 50, warn: 80, crit: 95 },
+    errorRate: { good: 0.01, warn: 0.1, crit: 0.5 },
+    latencyP99: { good: 0.5, warn: 1.0, crit: 3.0 },
+    logErrors: { good: 1, warn: 5, crit: 20 },
+    statusBoundaries: { healthy: 80, degraded: 50 },
+};
+export function loadConfig() {
+    try {
+        const raw = readFileSync(CONFIG_PATH, "utf-8");
+        const parsed = yaml.load(raw);
+        return {
+            sources: parsed?.sources || [],
+            settings: { ...DEFAULT_SETTINGS, ...parsed?.settings },
+            healthThresholds: deepMerge(DEFAULT_HEALTH_THRESHOLDS, (parsed?.healthThresholds || {})),
+        };
+    }
+    catch {
+        console.warn(`Config file not found at ${CONFIG_PATH}, using env vars + defaults`);
+        return buildConfigFromEnv();
+    }
+}
+function parseUrlList(envVar, type) {
+    if (!envVar)
+        return [];
+    return envVar.split(",").map((url, i, arr) => ({
+        name: arr.length === 1 ? type : `${type}-${i + 1}`,
+        type,
+        url: url.trim(),
+        enabled: true,
+    }));
+}
+function buildConfigFromEnv() {
+    const sources = [
+        ...parseUrlList(process.env.PROMETHEUS_URL, "prometheus"),
+        ...parseUrlList(process.env.LOKI_URL, "loki"),
+    ];
+    return {
+        sources,
+        settings: { ...DEFAULT_SETTINGS },
+        healthThresholds: DEFAULT_HEALTH_THRESHOLDS,
+    };
+}
+export function saveConfig(config) {
+    const dir = dirname(CONFIG_PATH);
+    mkdirSync(dir, { recursive: true });
+    const yamlStr = yaml.dump(config, { indent: 2, lineWidth: 200 });
+    writeFileSync(CONFIG_PATH, yamlStr, "utf-8");
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function deepMerge(base, override) {
+    const result = { ...base };
+    for (const key of Object.keys(override)) {
+        const val = override[key];
+        if (val && typeof val === "object" && !Array.isArray(val) && typeof base[key] === "object") {
+            result[key] = deepMerge(base[key], val);
+        }
+        else if (val !== undefined) {
+            result[key] = val;
+        }
+    }
+    return result;
+}

package/dist/config/loader.test.d.ts

@@ -0,0 +1 @@
+export {};