@thotischner/observability-mcp 3.0.1 → 3.1.0

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

@@ -22,10 +22,43 @@ export declare const queryLogsDefinition: {
                 type: string;
                 description: string;
             };
+            labels: {
+                type: string;
+                additionalProperties: {
+                    type: string;
+                };
+                description: string;
+            };
             limit: {
                 type: string;
                 description: string;
             };
+            aggregate: {
+                type: string;
+                description: string;
+                properties: {
+                    op: {
+                        type: string;
+                        enum: string[];
+                    };
+                    by: {
+                        type: string;
+                        items: {
+                            type: string;
+                        };
+                        description: string;
+                    };
+                    k: {
+                        type: string;
+                        description: string;
+                    };
+                    step: {
+                        type: string;
+                        description: string;
+                    };
+                };
+                required: string[];
+            };
         };
         required: string[];
     };
@@ -36,6 +69,13 @@ export declare function queryLogsHandler(registry: ConnectorRegistry, args: {
     duration?: string;
     level?: string;
     limit?: number;
+    labels?: Record<string, string>;
+    aggregate?: {
+        op: "count_over_time" | "sum" | "topk";
+        by?: string[];
+        k?: number;
+        step?: string;
+    };
 }, ctx?: RequestContext): Promise<{
     content: {
         type: "text";

package/dist/tools/query-logs.js

@@ -1,8 +1,8 @@
 import { defaultContext } from "../context.js";
-import { validateDuration, validateServiceName, errorResponse } from "./validation.js";
+import { validateDuration, validateServiceName, validateLogLabels, validateLogAggregate, 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.",
+    description: "Query logs for a service over a given timeframe. Returns log entries with a summary including error/warning counts and top error patterns. Filter by log level, a free-text/regex search, OR structured `labels` (exact-match on backend-extracted fields like method/status/url/environment — far more reliable than regex on structured JSON logs).",
     inputSchema: {
         type: "object",
         properties: {
@@ -22,9 +22,25 @@ export const queryLogsDefinition = {
                 type: "string",
                 description: "Filter by log level: 'error', 'warn', 'info', 'debug'",
             },
+            labels: {
+                type: "object",
+                additionalProperties: { type: "string" },
+                description: "Structured equality filters on backend-extracted fields, AND'd together, e.g. {\"method\":\"GET\",\"url\":\"/\",\"status\":\"200\",\"environment\":\"prod\"}. Prefer this over `query` for structured JSON logs — the literal text rarely appears verbatim. Label names must be [a-zA-Z_][a-zA-Z0-9_]* (max 20).",
+            },
             limit: {
                 type: "number",
-                description: "Maximum number of log entries to return. Default: 100",
+                description: "Maximum number of log entries to return. Default: 100. Ignored when `aggregate` is set.",
+            },
+            aggregate: {
+                type: "object",
+                description: "Server-side aggregation — returns grouped counts, not raw rows, so you get a number instead of a haystack. op: 'count_over_time' (time series of counts per bucket), 'sum' (total per group over the window), 'topk' (top-k groups by total). Example: {\"op\":\"topk\",\"by\":[\"url\"],\"k\":10} for the busiest paths. Honours `labels`/`query` filters.",
+                properties: {
+                    op: { type: "string", enum: ["count_over_time", "sum", "topk"] },
+                    by: { type: "array", items: { type: "string" }, description: "Group-by label names (required for topk)." },
+                    k: { type: "number", description: "Top-k count (default 10)." },
+                    step: { type: "string", description: "Bucket size for count_over_time, e.g. '15m'. Defaults to ~1/60th of the window." },
+                },
+                required: ["op"],
             },
         },
         required: ["service"],
@@ -38,6 +54,12 @@ export async function queryLogsHandler(registry, args, ctx = defaultContext()) {
     const durationErr = validateDuration(duration);
     if (durationErr)
         return errorResponse(durationErr);
+    const labelsErr = validateLogLabels(args.labels);
+    if (labelsErr)
+        return errorResponse(labelsErr);
+    const aggErr = validateLogAggregate(args.aggregate);
+    if (aggErr)
+        return errorResponse(aggErr);
     const connectors = registry.getByTenant(ctx.tenant).filter((c) => c.signalType === "logs");
     if (connectors.length === 0) {
         return {
@@ -47,6 +69,49 @@ export async function queryLogsHandler(registry, args, ctx = defaultContext()) {
             isError: true,
         };
     }
+    // Aggregate mode (Q-LOG2): route to the connector's queryLogAggregate.
+    if (args.aggregate) {
+        const aggResults = [];
+        const aggErrors = [];
+        let capable = 0;
+        for (const connector of connectors) {
+            if (!connector.queryLogAggregate)
+                continue;
+            capable++;
+            try {
+                const q = {
+                    service: args.service,
+                    duration,
+                    labels: args.labels,
+                    query: args.query,
+                    op: args.aggregate.op,
+                    by: args.aggregate.by,
+                    k: args.aggregate.k,
+                    step: args.aggregate.step,
+                };
+                aggResults.push(await connector.queryLogAggregate(q));
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.error(`Log aggregate failed on ${connector.name}:`, msg);
+                aggErrors.push(`${connector.name}: ${msg}`);
+            }
+        }
+        if (capable === 0) {
+            return errorResponse("No log backend supports aggregation (queryLogAggregate).");
+        }
+        if (aggResults.length === 0) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: aggErrors.length ? `Aggregate failed: ${aggErrors.join("; ")}` : "No data returned", service: args.service, duration }) }],
+                isError: aggErrors.length > 0,
+            };
+        }
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(aggResults.length === 1 ? aggResults[0] : aggResults, null, 2) },
+            ],
+        };
+    }
     const results = [];
     const errors = [];
     for (const connector of connectors) {
@@ -59,6 +124,7 @@ export async function queryLogsHandler(registry, args, ctx = defaultContext()) {
                 duration,
                 level: args.level,
                 limit: args.limit,
+                labels: args.labels,
             });
             results.push(result);
         }

package/dist/tools/validation.d.ts

@@ -8,6 +8,19 @@ export declare function validateMetricName(metric: string, registry: ConnectorRe
  */
 export declare function sanitizeLabelValue(value: string): string | null;
 export declare function validateServiceName(service: string): string | null;
+/**
+ * Validate a structured `labels` filter map for query_logs. Fail-closed:
+ * any bad key/value rejects the whole request rather than silently
+ * dropping a filter (a dropped filter could widen results past what the
+ * caller intended). Bounds the map size + value length so a crafted input
+ * can't build a pathological query.
+ */
+export declare function validateLogLabels(labels: unknown): string | null;
+/**
+ * Validate the query_logs `aggregate` spec. Fail-closed, like the labels
+ * validator. Returns an error string or null.
+ */
+export declare function validateLogAggregate(aggregate: unknown): string | null;
 export declare function errorResponse(message: string): {
     content: {
         type: "text";

package/dist/tools/validation.js

@@ -41,6 +41,80 @@ export function validateServiceName(service) {
     }
     return null;
 }
+/** A Prometheus/Loki label name: letter/underscore, then word chars. */
+const LABEL_NAME_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+/**
+ * Validate a structured `labels` filter map for query_logs. Fail-closed:
+ * any bad key/value rejects the whole request rather than silently
+ * dropping a filter (a dropped filter could widen results past what the
+ * caller intended). Bounds the map size + value length so a crafted input
+ * can't build a pathological query.
+ */
+export function validateLogLabels(labels) {
+    if (labels === undefined)
+        return null;
+    if (typeof labels !== "object" || labels === null || Array.isArray(labels)) {
+        return "Invalid labels: must be an object mapping label names to string values.";
+    }
+    const entries = Object.entries(labels);
+    if (entries.length > 20) {
+        return "Too many labels (max 20).";
+    }
+    for (const [k, v] of entries) {
+        if (!LABEL_NAME_RE.test(k)) {
+            return `Invalid label name "${k}". Must match [a-zA-Z_][a-zA-Z0-9_]* (no dots, dashes, or quotes).`;
+        }
+        if (typeof v !== "string") {
+            return `Invalid value for label "${k}": must be a string.`;
+        }
+        if (v.length > 1024) {
+            return `Value for label "${k}" too long (max 1024 chars).`;
+        }
+    }
+    return null;
+}
+const AGGREGATE_OPS = new Set(["count_over_time", "sum", "topk"]);
+/**
+ * Validate the query_logs `aggregate` spec. Fail-closed, like the labels
+ * validator. Returns an error string or null.
+ */
+export function validateLogAggregate(aggregate) {
+    if (aggregate === undefined)
+        return null;
+    if (typeof aggregate !== "object" || aggregate === null || Array.isArray(aggregate)) {
+        return "Invalid aggregate: must be an object with an `op`.";
+    }
+    const a = aggregate;
+    if (typeof a.op !== "string" || !AGGREGATE_OPS.has(a.op)) {
+        return `Invalid aggregate.op. Must be one of: ${[...AGGREGATE_OPS].join(", ")}.`;
+    }
+    if (a.by !== undefined) {
+        if (!Array.isArray(a.by) || !a.by.every((x) => typeof x === "string")) {
+            return "aggregate.by must be an array of label-name strings.";
+        }
+        if (a.by.length > 10)
+            return "aggregate.by has too many labels (max 10).";
+        for (const name of a.by) {
+            if (!LABEL_NAME_RE.test(name)) {
+                return `Invalid aggregate.by label "${name}". Must match [a-zA-Z_][a-zA-Z0-9_]*.`;
+            }
+        }
+    }
+    if (a.k !== undefined) {
+        if (typeof a.k !== "number" || !Number.isFinite(a.k) || a.k <= 0 || a.k > 1000) {
+            return "aggregate.k must be a positive integer (max 1000).";
+        }
+    }
+    if (a.step !== undefined) {
+        if (typeof a.step !== "string" || validateDuration(a.step)) {
+            return "aggregate.step must be a duration like '15m', '1h'.";
+        }
+    }
+    if (a.op === "topk" && (a.by === undefined || a.by.length === 0)) {
+        return "aggregate.op 'topk' requires at least one `by` label to rank.";
+    }
+    return null;
+}
 export function errorResponse(message) {
     return {
         content: [{ type: "text", text: JSON.stringify({ error: message }) }],

package/dist/tools/validation.test.js

@@ -1,6 +1,59 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { validateDuration, validateServiceName, sanitizeLabelValue, errorResponse } from "./validation.js";
+import { validateDuration, validateServiceName, sanitizeLabelValue, validateLogLabels, validateLogAggregate, errorResponse } from "./validation.js";
+describe("validateLogAggregate (Q-LOG2)", () => {
+    it("accepts undefined and valid specs", () => {
+        assert.equal(validateLogAggregate(undefined), null);
+        assert.equal(validateLogAggregate({ op: "count_over_time" }), null);
+        assert.equal(validateLogAggregate({ op: "sum", by: ["url", "status"] }), null);
+        assert.equal(validateLogAggregate({ op: "topk", by: ["url"], k: 5, step: "15m" }), null);
+    });
+    it("rejects a bad/missing op", () => {
+        assert.ok(validateLogAggregate({}));
+        assert.ok(validateLogAggregate({ op: "median" }));
+        assert.ok(validateLogAggregate("nope"));
+    });
+    it("rejects bad by labels", () => {
+        assert.ok(validateLogAggregate({ op: "sum", by: ["a.b"] }));
+        assert.ok(validateLogAggregate({ op: "sum", by: "url" }));
+    });
+    it("rejects bad k and step", () => {
+        assert.ok(validateLogAggregate({ op: "topk", by: ["url"], k: 0 }));
+        assert.ok(validateLogAggregate({ op: "topk", by: ["url"], k: 99999 }));
+        assert.ok(validateLogAggregate({ op: "count_over_time", step: "soon" }));
+    });
+    it("requires a by label for topk", () => {
+        assert.ok(validateLogAggregate({ op: "topk" }));
+        assert.ok(validateLogAggregate({ op: "topk", by: [] }));
+    });
+});
+describe("validateLogLabels (Q-LOG1)", () => {
+    it("accepts undefined (no filter) and a valid map", () => {
+        assert.equal(validateLogLabels(undefined), null);
+        assert.equal(validateLogLabels({ method: "GET", status: "200", environment: "prod" }), null);
+    });
+    it("rejects non-object inputs", () => {
+        assert.ok(validateLogLabels("nope"));
+        assert.ok(validateLogLabels(["a"]));
+        assert.ok(validateLogLabels(42));
+    });
+    it("rejects label names with dots, dashes, or quotes (injection-safe, fail-closed)", () => {
+        assert.ok(validateLogLabels({ "a.b": "x" }));
+        assert.ok(validateLogLabels({ "a-b": "x" }));
+        assert.ok(validateLogLabels({ 'a"x': "y" }));
+        assert.ok(validateLogLabels({ "1abc": "x" })); // can't start with a digit
+    });
+    it("rejects non-string and over-long values", () => {
+        assert.ok(validateLogLabels({ method: 123 }));
+        assert.ok(validateLogLabels({ method: "x".repeat(1025) }));
+    });
+    it("rejects too many labels", () => {
+        const many = {};
+        for (let i = 0; i < 21; i++)
+            many[`k${i}`] = "v";
+        assert.ok(validateLogLabels(many));
+    });
+});
 describe("validateDuration", () => {
     it("accepts valid durations", () => {
         assert.equal(validateDuration("5m"), null);

package/dist/types.d.ts

@@ -109,6 +109,54 @@ export interface LogQuery {
     duration: string;
     limit?: number;
     level?: string;
+    /** Structured label/field equality filters, AND'd together. For Loki
+     *  these compile to LogQL label-filter expressions after `| json`, so
+     *  fields the backend already extracts (method, status, url, ip,
+     *  environment, …) become first-class selectors instead of brittle
+     *  free-text regex. */
+    labels?: Record<string, string>;
+}
+/** Server-side log aggregation (Q-LOG2). Pushes count/group/topk down to
+ *  the backend's metric-query path so an agent gets a *number*, not a
+ *  *haystack*. */
+export interface LogAggregateQuery {
+    service: string;
+    duration: string;
+    /** Same structured filters as LogQuery, applied before aggregation. */
+    labels?: Record<string, string>;
+    /** Optional line filter applied before aggregation. */
+    query?: string;
+    /** count_over_time → time series of counts per bucket; sum → total per
+     *  group over the window; topk → the top-k groups by total. */
+    op: "count_over_time" | "sum" | "topk";
+    /** Group-by label names. */
+    by?: string[];
+    /** k for topk (default 10). */
+    k?: number;
+    /** Bucket size for count_over_time, e.g. "15m". Defaults to the window. */
+    step?: string;
+}
+export interface LogAggregateSeries {
+    /** The group key (the `by` label values). Empty object for an ungrouped total. */
+    labels: Record<string, string>;
+    /** Single value — present for instant ops (sum / topk). */
+    value?: number;
+    /** Time series — present for count_over_time. */
+    points?: Array<{
+        t: number;
+        value: number;
+    }>;
+}
+export interface LogAggregateResult {
+    source: string;
+    op: string;
+    by: string[];
+    step?: string;
+    /** "instant" (vector) for sum/topk, "range" (matrix) for count_over_time. */
+    mode: "instant" | "range";
+    series: LogAggregateSeries[];
+    /** Operator-facing notes, e.g. that `limit` is ignored in aggregate mode. */
+    note?: string;
 }
 export interface DataPoint {
     timestamp: string;

package/dist/ui/index.html

@@ -4,7 +4,7 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Observability MCP Gateway</title>
-  <script>
+  <script nonce="__CSP_NONCE__">
     // Resolve the theme + density BEFORE first paint to avoid a flash.
     // Explicit user choice (localStorage) wins; otherwise follow the OS
     // setting for theme and default to comfortable density.
@@ -2656,7 +2656,7 @@ curl -s http://localhost:3000/api/enterprise/status</pre>
     <div class="drawer-bd" id="drawer-body"></div>
   </aside>
 
-<script>
+<script nonce="__CSP_NONCE__">
 let sourcesData=[], servicesData=[], supportedTypes=[], settings={}, healthThresholds={}, defaults={};
 let deleteTarget=null, deleteType=null;
 // Per-source metrics state
@@ -6251,9 +6251,8 @@ function saveMetric() {
 // --- Health Dashboard ---
 let healthData={};
 let healthInterval=null;
-// Score history per service, kept client-side. The server doesn't yet
-// expose a per-service score timeseries — this gives an at-a-glance trend
-// for the last ~7.5 minutes (30 points × 15s refresh).
+// Client-side live-score trend, kept as a fallback for when the server's
+// anomaly-history sink isn't active. ~7.5 minutes (30 points × 15s refresh).
 const SPARK_MAX = 30;
 const scoreHistory = {};
 function pushScore(name, score) {
@@ -6262,31 +6261,59 @@ function pushScore(name, score) {
   arr.push(score);
   if (arr.length > SPARK_MAX) arr.shift();
 }
-function sparkSvg(name, status) {
-  const pts = scoreHistory[name] || [];
+// Server-side anomaly-score history (Q21). Populated from
+// /api/health/anomaly-sparklines — the last hour of omcp_anomaly_score
+// from the anomaly-history sink. Survives reloads; preferred over the
+// client-side trend when present.
+let anomalySpark = { enabled:false, windowMs:0, series:{} };
+
+function drawSpark(values, status, domainMax, title){
   const w = 100, h = 36, pad = 2;
-  if (pts.length < 2) {
-    // Placeholder dashed midline until we have ≥2 samples.
+  if (!values || values.length < 2) {
     return `<svg class="hc-spark ${status}" viewBox="0 0 ${w} ${h}" preserveAspectRatio="none" aria-hidden="true">`
       + `<line class="spark-empty" x1="0" y1="${h/2}" x2="${w}" y2="${h/2}"/></svg>`;
   }
-  const min = 0, max = 100;
-  const step = (w - pad*2) / (pts.length - 1);
-  const y = v => h - pad - ((v - min) / (max - min)) * (h - pad*2);
-  const coords = pts.map((v, i) => `${pad + i*step},${y(v)}`);
+  const min = 0, max = domainMax;
+  const step = (w - pad*2) / (values.length - 1);
+  const y = v => h - pad - ((Math.max(min, Math.min(max, v)) - min) / (max - min || 1)) * (h - pad*2);
+  const coords = values.map((v, i) => `${pad + i*step},${y(v)}`);
   const line = coords.join(' ');
-  const area = `M${coords[0]} L${line.split(' ').join(' L')} L${pad + (pts.length-1)*step},${h-pad} L${pad},${h-pad} Z`;
+  const area = `M${coords[0]} L${line.split(' ').join(' L')} L${pad + (values.length-1)*step},${h-pad} L${pad},${h-pad} Z`;
   const last = coords[coords.length - 1].split(',');
   return `<svg class="hc-spark ${status}" viewBox="0 0 ${w} ${h}" preserveAspectRatio="none" aria-hidden="true">`
+    + (title?`<title>${esc(title)}</title>`:'')
     + `<path class="spark-fill" d="${area}"/>`
     + `<polyline class="spark-line" points="${line}"/>`
     + `<circle class="spark-dot" cx="${last[0]}" cy="${last[1]}" r="1.8"/>`
     + `</svg>`;
 }
 
+function sparkSvg(name, status) {
+  // Prefer the server anomaly-score series (real omcp_anomaly_score, last
+  // hour, survives reload). Anomaly scores are 0..1; widen the domain if a
+  // score ever exceeds 1 so spikes aren't clipped.
+  const series = (anomalySpark.series && anomalySpark.series[name]) || [];
+  if (series.length >= 2) {
+    const scores = series.map(p => p.score);
+    const domainMax = Math.max(1, ...scores);
+    const mins = anomalySpark.windowMs ? Math.round(anomalySpark.windowMs/60000) : 60;
+    return drawSpark(scores, status, domainMax, `anomaly score · ${series.length} pts · last ${mins}m`);
+  }
+  // Fallback: client-side live health-score trend (0..100).
+  return drawSpark(scoreHistory[name] || [], status, 100, 'live score trend');
+}
+
 async function loadHealthData() {
   try {
-    healthData=await(await fetch('/api/health')).json();
+    // Fetch health + the server-side anomaly-score sparkline data in
+    // parallel. The sparkline endpoint is best-effort: if it fails we
+    // simply fall back to the client-side live-score trend.
+    const [h, spark] = await Promise.all([
+      fetch('/api/health').then(r=>r.json()),
+      fetch('/api/health/anomaly-sparklines').then(r=>r.ok?r.json():null).catch(()=>null),
+    ]);
+    healthData=h;
+    if (spark && spark.series) anomalySpark = spark;
     renderHealthCards();
   } catch(e){ document.getElementById('health-cards').innerHTML='<div class="empty">Failed to load health data.</div>'; }
   if(!healthInterval) healthInterval=setInterval(()=>{ if(document.getElementById('page-health').classList.contains('active')) loadHealthData(); },15000);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thotischner/observability-mcp",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Unified observability gateway for AI agents — one MCP server for Prometheus, Loki, and any backend",
   "type": "module",
   "license": "Apache-2.0",