@thotischner/observability-mcp 1.0.0

package/dist/tools/get-service-health.js

@@ -0,0 +1,111 @@
+import { calculateHealthScore } from "../analysis/health.js";
+import { detectRecentAnomaly } from "../analysis/anomaly.js";
+let _thresholds = null;
+export function setHealthThresholds(t) {
+    _thresholds = t;
+}
+export const getServiceHealthDefinition = {
+    name: "get_service_health",
+    description: "Get an aggregated health overview for a service combining metrics AND logs. Returns a health score (0-100), status (healthy/degraded/critical), key metric values, log error summary, detected anomalies, and cross-signal correlations.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            service: {
+                type: "string",
+                description: "Service name to check health for",
+            },
+        },
+        required: ["service"],
+    },
+};
+export async function getServiceHealthHandler(registry, args) {
+    const metricsConnectors = registry.getBySignal("metrics");
+    const logConnectors = registry.getBySignal("logs");
+    // Gather metrics
+    let cpu = 0, memory = 0, errorRate = 0, latencyP99 = 0;
+    const anomalies = [];
+    for (const connector of metricsConnectors) {
+        if (!connector.queryMetrics)
+            continue;
+        try {
+            const cpuResult = await connector.queryMetrics({ service: args.service, metric: "cpu", duration: "5m" });
+            cpu = cpuResult.summary.current;
+            checkAnomaly(cpuResult.values.map(v => v.value), "cpu", args.service, connector.name, anomalies);
+            const memResult = await connector.queryMetrics({ service: args.service, metric: "memory", duration: "5m" });
+            memory = memResult.summary.current / 1_000_000; // Convert to MB for display
+            const errResult = await connector.queryMetrics({ service: args.service, metric: "error_rate", duration: "5m" });
+            errorRate = errResult.summary.current;
+            checkAnomaly(errResult.values.map(v => v.value), "error_rate", args.service, connector.name, anomalies);
+            const latResult = await connector.queryMetrics({ service: args.service, metric: "latency_p99", duration: "5m" });
+            latencyP99 = latResult.summary.current;
+            checkAnomaly(latResult.values.map(v => v.value), "latency_p99", args.service, connector.name, anomalies);
+        }
+        catch (err) {
+            console.error(`Health check metrics failed for ${args.service}:`, err);
+        }
+    }
+    // Gather logs
+    let logErrorRate = 0;
+    let topErrors = [];
+    const correlations = [];
+    for (const connector of logConnectors) {
+        if (!connector.queryLogs)
+            continue;
+        try {
+            const logs = await connector.queryLogs({ service: args.service, duration: "5m", limit: 200 });
+            logErrorRate = logs.summary.errorCount; // errors in 5m window
+            topErrors = logs.summary.topPatterns;
+            // Cross-signal correlation
+            if (logErrorRate > 0 && anomalies.length > 0) {
+                correlations.push(`${anomalies.length} metric anomal${anomalies.length === 1 ? "y" : "ies"} detected alongside ${logErrorRate} error logs in the last 5 minutes`);
+                if (topErrors.length > 0) {
+                    correlations.push(`Top error pattern: ${topErrors[0]}`);
+                }
+            }
+        }
+        catch (err) {
+            console.error(`Health check logs failed for ${args.service}:`, err);
+        }
+    }
+    // Calculate health score
+    const { DEFAULT_HEALTH_THRESHOLDS } = await import("../config/loader.js");
+    const health = calculateHealthScore({
+        cpu,
+        memory,
+        errorRate,
+        latencyP99,
+        logErrorRate,
+    }, _thresholds || DEFAULT_HEALTH_THRESHOLDS);
+    const result = {
+        service: args.service,
+        status: health.status,
+        score: health.score,
+        signals: {
+            metrics: { cpu, memory, errorRate, latencyP99 },
+            logs: { errorRate: logErrorRate, topErrors },
+        },
+        anomalies,
+        correlations,
+    };
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+}
+function checkAnomaly(values, metric, service, source, anomalies) {
+    const result = detectRecentAnomaly(values);
+    if (result.isAnomaly) {
+        const deviationPercent = result.baselineAvg === 0
+            ? 100
+            : Math.round(((result.recentAvg - result.baselineAvg) / result.baselineAvg) * 100);
+        anomalies.push({
+            metric,
+            severity: Math.abs(result.zScore) >= 3 ? "high" : Math.abs(result.zScore) >= 2 ? "medium" : "low",
+            description: `${metric} is ${result.zScore.toFixed(1)}σ ${result.zScore > 0 ? "above" : "below"} baseline (${result.baselineAvg.toFixed(2)} → ${result.recentAvg.toFixed(2)})`,
+            currentValue: result.recentAvg,
+            baselineValue: result.baselineAvg,
+            deviationPercent,
+            source,
+            service,
+        });
+    }
+}

package/dist/tools/handlers.test.d.ts

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

package/dist/tools/handlers.test.js

@@ -0,0 +1,138 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { ConnectorRegistry } from "../connectors/registry.js";
+import { listSourcesHandler } from "./list-sources.js";
+import { listServicesHandler } from "./list-services.js";
+// --- Mock Connector ---
+function createMockConnector(overrides) {
+    return {
+        connect: async () => { },
+        disconnect: async () => { },
+        healthCheck: async () => ({ status: "up", latencyMs: 5 }),
+        getDefaultMetrics: () => [],
+        getMetrics: () => [],
+        listServices: async () => [],
+        ...overrides,
+    };
+}
+// Helper to inject mock connectors into registry
+function createRegistryWithMocks(mocks) {
+    const reg = new ConnectorRegistry();
+    // Inject directly via internal maps
+    for (const mock of mocks) {
+        reg.connectors.set(mock.name, mock);
+        reg.sourceConfigs.set(mock.name, {
+            name: mock.name, type: mock.type, url: "http://mock", enabled: true,
+        });
+    }
+    return reg;
+}
+describe("listSourcesHandler", () => {
+    it("returns empty sources for empty registry", async () => {
+        const reg = new ConnectorRegistry();
+        const result = await listSourcesHandler(reg);
+        const data = JSON.parse(result.content[0].text);
+        assert.deepEqual(data.sources, []);
+    });
+    it("returns sources with health status", async () => {
+        const reg = createRegistryWithMocks([
+            createMockConnector({
+                name: "prom1", type: "prometheus", signalType: "metrics",
+                healthCheck: async () => ({ status: "up", latencyMs: 12 }),
+            }),
+            createMockConnector({
+                name: "loki1", type: "loki", signalType: "logs",
+                healthCheck: async () => ({ status: "down", latencyMs: 0, message: "connection refused" }),
+            }),
+        ]);
+        const result = await listSourcesHandler(reg);
+        const data = JSON.parse(result.content[0].text);
+        assert.equal(data.sources.length, 2);
+        assert.equal(data.sources[0].name, "prom1");
+        assert.equal(data.sources[0].status, "up");
+        assert.equal(data.sources[0].latencyMs, 12);
+        assert.equal(data.sources[1].name, "loki1");
+        assert.equal(data.sources[1].status, "down");
+    });
+});
+describe("listServicesHandler", () => {
+    it("returns empty for no connectors", async () => {
+        const reg = new ConnectorRegistry();
+        const result = await listServicesHandler(reg, {});
+        const data = JSON.parse(result.content[0].text);
+        assert.equal(data.total, 0);
+        assert.deepEqual(data.services, []);
+    });
+    it("deduplicates services from multiple connectors", async () => {
+        const reg = createRegistryWithMocks([
+            createMockConnector({
+                name: "prom1", type: "prometheus", signalType: "metrics",
+                listServices: async () => [
+                    { name: "api-gateway", source: "prom1", signalType: "metrics" },
+                    { name: "payment-service", source: "prom1", signalType: "metrics" },
+                ],
+            }),
+            createMockConnector({
+                name: "loki1", type: "loki", signalType: "logs",
+                listServices: async () => [
+                    { name: "api-gateway", source: "loki1", signalType: "logs" },
+                    { name: "order-service", source: "loki1", signalType: "logs" },
+                ],
+            }),
+        ]);
+        const result = await listServicesHandler(reg, {});
+        const data = JSON.parse(result.content[0].text);
+        assert.equal(data.total, 3);
+        const apiGw = data.services.find((s) => s.name === "api-gateway");
+        assert.ok(apiGw);
+        assert.deepEqual(apiGw.sources.sort(), ["loki1", "prom1"]);
+        assert.deepEqual(apiGw.signalTypes.sort(), ["logs", "metrics"]);
+    });
+    it("filters services case-insensitively", async () => {
+        const reg = createRegistryWithMocks([
+            createMockConnector({
+                name: "prom1", type: "prometheus", signalType: "metrics",
+                listServices: async () => [
+                    { name: "API-Gateway", source: "prom1", signalType: "metrics" },
+                    { name: "payment-service", source: "prom1", signalType: "metrics" },
+                ],
+            }),
+        ]);
+        const result = await listServicesHandler(reg, { filter: "api" });
+        const data = JSON.parse(result.content[0].text);
+        assert.equal(data.total, 1);
+        assert.equal(data.services[0].name, "API-Gateway");
+    });
+    it("handles connector errors gracefully", async () => {
+        const reg = createRegistryWithMocks([
+            createMockConnector({
+                name: "prom1", type: "prometheus", signalType: "metrics",
+                listServices: async () => { throw new Error("connection failed"); },
+            }),
+            createMockConnector({
+                name: "loki1", type: "loki", signalType: "logs",
+                listServices: async () => [
+                    { name: "order-service", source: "loki1", signalType: "logs" },
+                ],
+            }),
+        ]);
+        const result = await listServicesHandler(reg, {});
+        const data = JSON.parse(result.content[0].text);
+        // Should still return results from working connector
+        assert.equal(data.total, 1);
+        assert.equal(data.services[0].name, "order-service");
+    });
+    it("returns empty when filter matches nothing", async () => {
+        const reg = createRegistryWithMocks([
+            createMockConnector({
+                name: "prom1", type: "prometheus", signalType: "metrics",
+                listServices: async () => [
+                    { name: "payment-service", source: "prom1", signalType: "metrics" },
+                ],
+            }),
+        ]);
+        const result = await listServicesHandler(reg, { filter: "nonexistent" });
+        const data = JSON.parse(result.content[0].text);
+        assert.equal(data.total, 0);
+    });
+});

package/dist/tools/list-services.d.ts

@@ -0,0 +1,22 @@
+import type { ConnectorRegistry } from "../connectors/registry.js";
+export declare const listServicesDefinition: {
+    name: "list_services";
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            filter: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+};
+export declare function listServicesHandler(registry: ConnectorRegistry, args: {
+    filter?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/list-services.js

@@ -0,0 +1,57 @@
+export const listServicesDefinition = {
+    name: "list_services",
+    description: "List all monitored services discovered across all connected backends. Returns service names, their data sources, and signal types (metrics/logs).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            filter: {
+                type: "string",
+                description: "Optional filter to match service names",
+            },
+        },
+    },
+};
+export async function listServicesHandler(registry, args) {
+    const connectors = registry.getAll();
+    const allServices = [];
+    for (const connector of connectors) {
+        try {
+            const services = await connector.listServices();
+            allServices.push(...services);
+        }
+        catch (err) {
+            console.error(`Failed to list services from ${connector.name}:`, err);
+        }
+    }
+    // Deduplicate by name, merge signal types
+    const merged = new Map();
+    for (const svc of allServices) {
+        const existing = merged.get(svc.name);
+        if (existing) {
+            if (!existing.sources.includes(svc.source))
+                existing.sources.push(svc.source);
+            if (!existing.signalTypes.includes(svc.signalType))
+                existing.signalTypes.push(svc.signalType);
+        }
+        else {
+            merged.set(svc.name, {
+                name: svc.name,
+                sources: [svc.source],
+                signalTypes: [svc.signalType],
+            });
+        }
+    }
+    let services = Array.from(merged.values());
+    if (args.filter) {
+        const f = args.filter.toLowerCase();
+        services = services.filter((s) => s.name.toLowerCase().includes(f));
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ services, total: services.length }, null, 2),
+            },
+        ],
+    };
+}

package/dist/tools/list-sources.d.ts

@@ -0,0 +1,15 @@
+import type { ConnectorRegistry } from "../connectors/registry.js";
+export declare const listSourcesDefinition: {
+    name: "list_sources";
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {};
+    };
+};
+export declare function listSourcesHandler(registry: ConnectorRegistry): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/list-sources.js

@@ -0,0 +1,27 @@
+export const listSourcesDefinition = {
+    name: "list_sources",
+    description: "List all configured observability backends and their connection status. Use this to discover what data sources are available.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+    },
+};
+export async function listSourcesHandler(registry) {
+    const healthResults = await registry.healthCheckAll();
+    const connectors = registry.getAll();
+    const sources = connectors.map((c) => ({
+        name: c.name,
+        type: c.type,
+        signalType: c.signalType,
+        status: healthResults[c.name]?.status || "unknown",
+        latencyMs: healthResults[c.name]?.latencyMs,
+    }));
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ sources }, null, 2),
+            },
+        ],
+    };
+}

package/dist/tools/query-logs.d.ts

@@ -0,0 +1,49 @@
+import type { ConnectorRegistry } from "../connectors/registry.js";
+export declare const queryLogsDefinition: {
+    name: "query_logs";
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            service: {
+                type: string;
+                description: string;
+            };
+            query: {
+                type: string;
+                description: string;
+            };
+            duration: {
+                type: string;
+                description: string;
+            };
+            level: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function queryLogsHandler(registry: ConnectorRegistry, args: {
+    service: string;
+    query?: string;
+    duration?: string;
+    level?: string;
+    limit?: number;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/query-logs.js

@@ -0,0 +1,93 @@
+import { validateDuration, validateServiceName, errorResponse } from "./validation.js";
+export const queryLogsDefinition = {
+    name: "query_logs",
+    description: "Query logs for a service over a given timeframe. Returns log entries with a summary including error/warning counts and top error patterns. Supports filtering by log level and search query.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            service: {
+                type: "string",
+                description: "Service name (e.g. 'payment-service')",
+            },
+            query: {
+                type: "string",
+                description: "Optional search query to filter log messages (regex supported)",
+            },
+            duration: {
+                type: "string",
+                description: "Time range to query (e.g. '5m', '1h', '24h'). Default: '5m'",
+            },
+            level: {
+                type: "string",
+                description: "Filter by log level: 'error', 'warn', 'info', 'debug'",
+            },
+            limit: {
+                type: "number",
+                description: "Maximum number of log entries to return. Default: 100",
+            },
+        },
+        required: ["service"],
+    },
+};
+export async function queryLogsHandler(registry, args) {
+    const svcErr = validateServiceName(args.service);
+    if (svcErr)
+        return errorResponse(svcErr);
+    const duration = args.duration || "5m";
+    const durationErr = validateDuration(duration);
+    if (durationErr)
+        return errorResponse(durationErr);
+    const connectors = registry.getBySignal("logs");
+    if (connectors.length === 0) {
+        return {
+            content: [
+                { type: "text", text: JSON.stringify({ error: "No log backends configured" }) },
+            ],
+            isError: true,
+        };
+    }
+    const results = [];
+    const errors = [];
+    for (const connector of connectors) {
+        if (!connector.queryLogs)
+            continue;
+        try {
+            const result = await connector.queryLogs({
+                service: args.service,
+                query: args.query,
+                duration,
+                level: args.level,
+                limit: args.limit,
+            });
+            results.push(result);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Log query failed on ${connector.name}:`, msg);
+            errors.push(`${connector.name}: ${msg}`);
+        }
+    }
+    if (results.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: errors.length > 0 ? `Query failed: ${errors.join("; ")}` : "No logs returned",
+                        service: args.service,
+                        duration,
+                    }),
+                },
+            ],
+            isError: errors.length > 0,
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(results.length === 1 ? results[0] : results, null, 2),
+            },
+        ],
+    };
+}

package/dist/tools/query-metrics.d.ts

@@ -0,0 +1,44 @@
+import type { ConnectorRegistry } from "../connectors/registry.js";
+export declare const queryMetricsDefinition: {
+    name: "query_metrics";
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            service: {
+                type: string;
+                description: string;
+            };
+            metric: {
+                type: string;
+                description: string;
+            };
+            duration: {
+                type: string;
+                description: string;
+            };
+            source: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function queryMetricsHandler(registry: ConnectorRegistry, args: {
+    service: string;
+    metric: string;
+    duration?: string;
+    source?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/query-metrics.js

@@ -0,0 +1,91 @@
+import { validateDuration, validateMetricName, validateServiceName, errorResponse } from "./validation.js";
+export const queryMetricsDefinition = {
+    name: "query_metrics",
+    description: "Query a specific metric for a service over a given timeframe. Returns time-series data with pre-computed summary statistics (current, average, min, max, trend). Available metrics: cpu, memory, error_rate, request_rate, latency_p99, latency_p50, latency_avg.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            service: {
+                type: "string",
+                description: "Service name (e.g. 'api-gateway', 'payment-service')",
+            },
+            metric: {
+                type: "string",
+                description: "Metric name: cpu, memory, error_rate, request_rate, latency_p99, latency_p50, latency_avg",
+            },
+            duration: {
+                type: "string",
+                description: "Time range to query (e.g. '5m', '1h', '24h'). Default: '5m'",
+            },
+            source: {
+                type: "string",
+                description: "Specific source name to query. If omitted, queries all metrics backends.",
+            },
+        },
+        required: ["service", "metric"],
+    },
+};
+export async function queryMetricsHandler(registry, args) {
+    const svcErr = validateServiceName(args.service);
+    if (svcErr)
+        return errorResponse(svcErr);
+    const duration = args.duration || "5m";
+    const durationErr = validateDuration(duration);
+    if (durationErr)
+        return errorResponse(durationErr);
+    const metricErr = validateMetricName(args.metric, registry);
+    if (metricErr)
+        return errorResponse(metricErr);
+    const connectors = args.source
+        ? [registry.getByName(args.source)].filter(Boolean)
+        : registry.getBySignal("metrics");
+    if (connectors.length === 0) {
+        return {
+            content: [{ type: "text", text: JSON.stringify({ error: "No metrics backends configured" }) }],
+            isError: true,
+        };
+    }
+    const results = [];
+    const errors = [];
+    for (const connector of connectors) {
+        if (!connector?.queryMetrics)
+            continue;
+        try {
+            const result = await connector.queryMetrics({
+                service: args.service,
+                metric: args.metric,
+                duration,
+            });
+            results.push(result);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Metrics query failed on ${connector.name}:`, msg);
+            errors.push(`${connector.name}: ${msg}`);
+        }
+    }
+    if (results.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: errors.length > 0 ? `Query failed: ${errors.join("; ")}` : "No data returned",
+                        service: args.service,
+                        metric: args.metric,
+                        duration,
+                    }),
+                },
+            ],
+            isError: errors.length > 0,
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(results.length === 1 ? results[0] : results, null, 2),
+            },
+        ],
+    };
+}

package/dist/tools/validation.d.ts

@@ -0,0 +1,17 @@
+import type { ConnectorRegistry } from "../connectors/registry.js";
+export declare function validateDuration(duration: string): string | null;
+export declare function validateMetricName(metric: string, registry: ConnectorRegistry): string | null;
+/**
+ * Sanitize a label value for use in PromQL/LogQL queries.
+ * Only allows alphanumeric, hyphens, underscores, dots, colons.
+ * Rejects anything that could be used for injection.
+ */
+export declare function sanitizeLabelValue(value: string): string | null;
+export declare function validateServiceName(service: string): string | null;
+export declare function errorResponse(message: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};