@thotischner/observability-mcp 3.2.0 → 3.2.1

package/dist/conformance/mcp-2025-11-25.test.js

@@ -245,3 +245,133 @@ test("MCP 2025-11-25: server advertises protocolVersion equal to or newer than 2
     // recognised date-style version string.
     assert.match(r.protocolVersion, /^\d{4}-\d{2}-\d{2}$/, "protocolVersion must be a YYYY-MM-DD date");
 });
+// ---------------------------------------------------------------------------
+// Behavioural tools/call E2E (post-#415 hardening).
+//
+// These run over the REAL /mcp Streamable-HTTP transport against the booted
+// demo stack (integration.yml sets OMCP_CONFORMANCE_URL). They close the gap
+// that let #415 ship: a param can be ADVERTISED in tools/list yet silently
+// stripped by the SDK before it reaches the handler — an advertise-only
+// assertion passes anyway. Here we call the tool and assert the param TAKES
+// EFFECT over the wire. The demo mcp-server runs with OMCP_RAW_QUERY unset and
+// OMCP_IP_ENRICH_FILE unset, so the gate/not-configured assertions are
+// deterministic regardless of backend data.
+// ---------------------------------------------------------------------------
+async function callTool(session, name, args, id = 50) {
+    const { response } = await jsonRpc("tools/call", { name, arguments: args }, { id, session });
+    if (response.error)
+        return { error: response.error };
+    const r = response.result;
+    const text = r?.content?.[0]?.text;
+    let parsed;
+    try {
+        parsed = text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        parsed = undefined;
+    }
+    return { isError: r?.isError, parsed, text };
+}
+async function discoverService(session) {
+    const r = await callTool(session, "list_services", {}, 40);
+    const list = Array.isArray(r.parsed) ? r.parsed : r.parsed?.services;
+    const name = Array.isArray(list) && list[0] && (list[0].name || list[0].service);
+    return name || "payment-service"; // demo k3s service as fallback
+}
+test("E2E tools/call: query_logs raw_query is refused over the wire when capability off (#415 #3)", opts, async () => {
+    const session = await newSession();
+    const r = await callTool(session, "query_logs", { raw_query: '{job="x"}' });
+    // Proves raw_query SURVIVES transport (not stripped) AND the gate fires E2E.
+    const msg = JSON.stringify(r.parsed ?? r.text ?? "");
+    assert.match(msg, /raw_query is disabled/i, `expected gate refusal, got ${msg}`);
+});
+test("E2E tools/call: query_metrics raw_query is refused over the wire when capability off (#415 #3)", opts, async () => {
+    const session = await newSession();
+    const r = await callTool(session, "query_metrics", { raw_query: "up" });
+    const msg = JSON.stringify(r.parsed ?? r.text ?? "");
+    assert.match(msg, /raw_query is disabled/i, `expected gate refusal, got ${msg}`);
+});
+test("E2E tools/call: enrich_ips dispatches and reports not-configured over the wire (Gap B)", opts, async () => {
+    const session = await newSession();
+    const r = await callTool(session, "enrich_ips", { ips: ["203.0.113.5"] });
+    const msg = JSON.stringify(r.parsed ?? r.text ?? "");
+    // Proves the ips param survives transport and the tool dispatches; demo has
+    // no OMCP_IP_ENRICH_FILE so the deterministic "not configured" path fires.
+    assert.match(msg, /not configured/i, `expected not-configured notice, got ${msg}`);
+});
+test("E2E tools/call: query_logs aggregate takes effect over the wire — grouped result, not raw rows (#415 #2)", opts, async () => {
+    const session = await newSession();
+    const service = await discoverService(session);
+    const r = await callTool(session, "query_logs", {
+        service,
+        aggregate: { op: "count_over_time", step: "15m" },
+        duration: "1h",
+    });
+    // The aggregate result shape (op/mode/series) is structurally distinct from
+    // the raw-rows shape (entries/summary). Asserting the aggregate shape proves
+    // the `aggregate` param survived the SDK input parsing and reached the
+    // connector — even if the series is empty on a sparse demo window.
+    const p = Array.isArray(r.parsed) ? r.parsed[0] : r.parsed;
+    assert.ok(p, `expected an aggregate result, got ${JSON.stringify(r)}`);
+    assert.equal(p.op, "count_over_time", "result must carry the aggregate op");
+    assert.ok("mode" in p && Array.isArray(p.series), "result must be the aggregate shape (mode + series)");
+    assert.ok(!("entries" in p), "aggregate path must NOT return the raw-rows shape");
+});
+test("E2E tools/call: query_metrics labels param is accepted over the wire (#415 #4)", opts, async () => {
+    const session = await newSession();
+    const service = await discoverService(session);
+    const r = await callTool(session, "query_metrics", {
+        service,
+        metric: "cpu",
+        labels: { job: service },
+        duration: "5m",
+    });
+    // Must not be a transport/dispatch error; the labels param must be accepted
+    // (a structured "no data" result is fine — proves it reached the handler).
+    assert.ok(!r.error, `unexpected JSON-RPC error: ${JSON.stringify(r.error)}`);
+    assert.ok(r.parsed !== undefined || r.text !== undefined, "expected a CallToolResult payload");
+});
+test("E2E tools/call: get_anomaly_history dispatches without a PromQL 400 crash (H1 over the wire)", opts, async () => {
+    const session = await newSession();
+    const service = await discoverService(session);
+    const r = await callTool(session, "get_anomaly_history", { service, duration: "1h", method: "mad" });
+    // After the rawQuery fix the emitted PromQL is valid; empty data is a clean
+    // non-error result. The bug produced an invalid-query path that still
+    // returned non-error empty, so we assert the dispatch shape is well-formed.
+    assert.ok(!r.error, `unexpected JSON-RPC error: ${JSON.stringify(r.error)}`);
+    assert.ok(r.parsed !== undefined || r.text !== undefined, "expected a CallToolResult payload");
+});
+test("E2E tools/call: every registered tool dispatches over MCP and returns a CallToolResult", opts, async () => {
+    const session = await newSession();
+    const service = await discoverService(session);
+    // Minimal valid args per tool; tools with required args get discovered/dummy
+    // values. A clean isError result (e.g. query_traces 'no trace backends') is
+    // acceptable — we only require a shape-conformant dispatch, never a -32xxx.
+    const calls = {
+        list_sources: {},
+        list_services: {},
+        query_metrics: { service, metric: "cpu" },
+        query_logs: { service },
+        get_anomaly_history: { service },
+        generate_postmortem: { service },
+        query_traces: { service },
+        get_service_health: { service },
+        detect_anomalies: {},
+        get_topology: {},
+        get_blast_radius: { resource: service },
+        enrich_ips: { ips: ["203.0.113.5"] },
+    };
+    const { response: list } = await jsonRpc("tools/list", {}, { id: 41, session });
+    const names = (list.result?.tools ?? []).map((t) => t.name);
+    assert.ok(names.length >= 12, `expected >=12 tools, got ${names.length}`);
+    let id = 60;
+    for (const name of names) {
+        const args = calls[name] ?? {};
+        const { response } = await jsonRpc("tools/call", { name, arguments: args }, { id: id++, session });
+        if (response.error) {
+            assert.fail(`tool ${name} returned a JSON-RPC dispatch error: ${JSON.stringify(response.error)}`);
+        }
+        const r = response.result;
+        assert.ok(Array.isArray(r.content), `tool ${name} must return content[]`);
+    }
+});

package/dist/index.js

@@ -399,7 +399,7 @@ async function main() {
         registerTool("list_sources", [
             "List the configured observability backends (Prometheus, Loki, and any connector) and whether each is currently reachable.",
             "When to use: call this first to learn which source names exist and are healthy before passing `source` to other tools, or to debug why a query returns no data.",
-            "Behavior: read-only, no side effects. Returns one entry per source with its name, type, configured URL, signal types (metrics/logs), and a live up/down status. Never throws for an unreachable backend — the backend is reported as down instead.",
+            "Behavior: read-only, no side effects. Returns one entry per source with its name, type, signal types (metrics/logs), and a live up/down status (the backend URL is intentionally not exposed — it may carry embedded credentials). Never throws for an unreachable backend — the backend is reported as down instead.",
             "Related: use `list_services` to see what is monitored within these sources.",
         ].join(" "), {}, async () => {
             await enforceEntitledAccess(ctx, { tool: "list_sources" });
@@ -589,8 +589,8 @@ async function main() {
             "Query distributed traces for a service over a given timeframe.",
             "Returns ranked trace summaries (duration, span count, error status) with a p50/p95 aggregate across the returned set.",
             "When to use: investigate tail-latency outliers, walk call chains across services for a specific time window, or pull traces related to an anomaly that the metric/log tools surfaced first.",
-            "Prerequisites: get the exact service name from `list_services`. A Tempo / Jaeger / OTLP connector must be configured.",
-            "Behavior: read-only. `filter` accepts the backend's native query language (TraceQL on Tempo, tag query on Jaeger). When `errorsOnly=true`, only traces with at least one error span are returned. Default limit is 50.",
+            "Prerequisites: get the exact service name from `list_services`. A traces connector (e.g. Tempo, installable from the connector hub) must be configured — none is bundled by default, so without one this returns a clean 'No trace backends configured' result.",
+            "Behavior: read-only. `filter` accepts the backend's native query language (e.g. TraceQL on Tempo). When `errorsOnly=true`, only traces with at least one error span are returned. Default limit is 50.",
         ].join(" "), {
             service: z.string().describe("Service name (e.g. 'payment-service')."),
             duration: z.string().optional().describe("Rolling time window, e.g. '5m', '1h'. Default '15m'."),
@@ -1117,11 +1117,11 @@ async function main() {
     // get_anomaly_history queries them back via any Prometheus source
     // pointed at the same TSDB.
     //
-    // The detector-side hook that actually records per-anomaly scores
-    // is plumbed in F15b (it requires passing this instance into the
-    // detectAnomaliesHandler — minor surgery deferred). The
-    // infrastructure ships now so externally-written omcp_anomaly_score
-    // metrics are already queryable end-to-end.
+    // The detector-side hook that records per-anomaly scores is wired:
+    // this instance is passed into detectAnomaliesHandler at the
+    // detect_anomalies tool registration below, so every scan records its
+    // scores. Externally-written omcp_anomaly_score metrics are queryable
+    // end-to-end too.
     const anomalyHistory = new AnomalyHistory(anomalyHistoryFromEnv());
     anomalyHistory.start();
     if (anomalyHistory.isEnabled()) {

package/dist/sdk/manifest-schema.d.ts

@@ -18,8 +18,14 @@ export declare const manifestSchema: z.ZodObject<{
     capabilities: z.ZodOptional<z.ZodObject<{
         queryMetrics: z.ZodOptional<z.ZodBoolean>;
         queryLogs: z.ZodOptional<z.ZodBoolean>;
+        queryLogAggregate: z.ZodOptional<z.ZodBoolean>;
+        queryTraces: z.ZodOptional<z.ZodBoolean>;
         listServices: z.ZodOptional<z.ZodBoolean>;
         listAvailableMetrics: z.ZodOptional<z.ZodBoolean>;
+        listResources: z.ZodOptional<z.ZodBoolean>;
+        listEdges: z.ZodOptional<z.ZodBoolean>;
+        getTopologySnapshot: z.ZodOptional<z.ZodBoolean>;
+        watchTopology: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
     compat: z.ZodOptional<z.ZodObject<{
         serverVersion: z.ZodOptional<z.ZodString>;

package/dist/sdk/manifest-schema.js

@@ -24,8 +24,15 @@ export const manifestSchema = z.object({
         .object({
         queryMetrics: z.boolean().optional(),
         queryLogs: z.boolean().optional(),
+        queryLogAggregate: z.boolean().optional(),
+        queryTraces: z.boolean().optional(),
         listServices: z.boolean().optional(),
         listAvailableMetrics: z.boolean().optional(),
+        // Topology-provider capabilities (e.g. the Kubernetes connector).
+        listResources: z.boolean().optional(),
+        listEdges: z.boolean().optional(),
+        getTopologySnapshot: z.boolean().optional(),
+        watchTopology: z.boolean().optional(),
     })
         .optional(),
     compat: z

package/dist/tools/get-anomaly-history.js

@@ -67,13 +67,20 @@ export async function getAnomalyHistoryHandler(registry, args, ctx = defaultCont
         labelFilters.push(`method="${escLabel(args.method)}"`);
     const metric = `omcp_anomaly_score{${labelFilters.join(",")}}`;
     // Fan out across every metrics connector; first non-empty answer wins.
+    // CRITICAL: pass the hand-built selector via `rawQuery`, NOT `metric`.
+    // The connector's curated path wraps a bare `metric` in `{ {{selector}} }`,
+    // which for our already-complete selector produces invalid double-brace
+    // PromQL (`omcp_anomaly_score{service="x"}{ job="x" }`) → 400 → the catch
+    // below swallowed it and the tool always reported "no history". rawQuery is
+    // sent verbatim to /api/v1/query_range (the R4 passthrough).
     for (const c of candidates) {
         if (!c.queryMetrics)
             continue;
         try {
             const r = await c.queryMetrics({
                 service: args.service,
-                metric,
+                metric: "omcp_anomaly_score",
+                rawQuery: metric,
                 duration,
             });
             if (r && Array.isArray(r.values) && r.values.length > 0) {

package/dist/tools/get-anomaly-history.test.d.ts

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

package/dist/tools/get-anomaly-history.test.js

@@ -0,0 +1,62 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { getAnomalyHistoryHandler } from "./get-anomaly-history.js";
+// Regression guard for the wired-but-dead bug found in the v3.2 audit:
+// get_anomaly_history hand-builds a complete PromQL selector
+// (`omcp_anomaly_score{service="x",method="mad"}`) and must pass it via
+// `rawQuery` (verbatim passthrough), NOT via `metric`. The curated `metric`
+// path wraps the value in `{ {{selector}} }`, which for an already-complete
+// selector yields invalid double-brace PromQL → Prometheus 400 → the handler
+// swallowed it and always returned "no history". This test pins that the
+// connector receives a verbatim rawQuery and never the manglable metric path.
+function fakeRegistry(capture, result) {
+    const conn = {
+        name: "prom",
+        type: "prometheus",
+        signalType: "metrics",
+        async queryMetrics(q) {
+            capture(q);
+            if (!result)
+                throw new Error("no data");
+            return result;
+        },
+    };
+    return { getByTenant: () => [conn] };
+}
+function parse(r) {
+    return JSON.parse(r.content[0].text);
+}
+describe("get_anomaly_history — rawQuery wiring (audit regression)", () => {
+    it("routes the omcp_anomaly_score selector via rawQuery, not metric", async () => {
+        let captured;
+        const reg = fakeRegistry((q) => (captured = q), {
+            source: "prom",
+            service: "payment",
+            metric: "omcp_anomaly_score",
+            unit: "",
+            values: [{ timestamp: "2026-06-09T00:00:00.000Z", value: 0.7 }],
+            summary: { current: 0.7, average: 0.7, min: 0.7, max: 0.7, trend: "stable" },
+        });
+        const out = parse(await getAnomalyHistoryHandler(reg, { service: "payment", method: "mad", duration: "1h" }));
+        assert.ok(captured, "connector.queryMetrics must be called");
+        // The fix: rawQuery carries the verbatim selector.
+        assert.equal(captured.rawQuery, 'omcp_anomaly_score{service="payment",method="mad"}');
+        // And it must NOT be smuggled through the curated `metric` path (which would
+        // double-brace it). metric may be a bare name placeholder, but never the selector.
+        assert.doesNotMatch(String(captured.metric ?? ""), /\{/, "metric must not carry the brace selector");
+        // Sanity: the verbatim query has exactly one brace block (no double-brace).
+        assert.equal((captured.rawQuery.match(/\{/g) || []).length, 1);
+        assert.equal(out.isError, undefined);
+        assert.equal(out.values.length, 1);
+    });
+    it("omits the method filter when not given", async () => {
+        let captured;
+        const reg = fakeRegistry((q) => (captured = q), {
+            source: "prom", service: "api", metric: "omcp_anomaly_score", unit: "",
+            values: [{ timestamp: "2026-06-09T00:00:00.000Z", value: 1 }],
+            summary: { current: 1, average: 1, min: 1, max: 1, trend: "stable" },
+        });
+        await getAnomalyHistoryHandler(reg, { service: "api" });
+        assert.equal(captured.rawQuery, 'omcp_anomaly_score{service="api"}');
+    });
+});

package/dist/tools/handlers.test.js

@@ -90,6 +90,21 @@ describe("listServicesHandler", () => {
         assert.deepEqual(apiGw.sources.sort(), ["loki1", "prom1"]);
         assert.deepEqual(apiGw.signalTypes.sort(), ["logs", "metrics"]);
     });
+    it("carries per-service labels (e.g. discoveredVia) through the merge (audit: docs/loki.md)", async () => {
+        const reg = createRegistryWithMocks([
+            createMockConnector({
+                name: "loki1", type: "loki", signalType: "logs",
+                listServices: async () => [
+                    { name: "payment-service", source: "loki1", signalType: "logs", labels: { discoveredVia: "service_name" } },
+                ],
+            }),
+        ]);
+        const result = await listServicesHandler(reg, {});
+        const data = JSON.parse(result.content[0].text);
+        const svc = data.services.find((s) => s.name === "payment-service");
+        assert.ok(svc, "service must be present");
+        assert.equal(svc.labels?.discoveredVia, "service_name", "discoveredVia must surface in the tool output");
+    });
     it("filters services case-insensitively", async () => {
         const reg = createRegistryWithMocks([
             createMockConnector({

package/dist/tools/list-services.js

@@ -25,7 +25,10 @@ export async function listServicesHandler(registry, args, ctx = defaultContext()
             console.error(`Failed to list services from ${connector.name}:`, err);
         }
     }
-    // Deduplicate by name, merge signal types
+    // Deduplicate by name, merge signal types. Carry per-service `labels`
+    // (e.g. the Loki connector's `discoveredVia`, documented in docs/loki.md)
+    // through the merge so discovery metadata actually surfaces in the tool
+    // output; first source to set a given label key wins.
     const merged = new Map();
     for (const svc of allServices) {
         const existing = merged.get(svc.name);
@@ -34,12 +37,15 @@ export async function listServicesHandler(registry, args, ctx = defaultContext()
                 existing.sources.push(svc.source);
             if (!existing.signalTypes.includes(svc.signalType))
                 existing.signalTypes.push(svc.signalType);
+            if (svc.labels)
+                existing.labels = { ...svc.labels, ...(existing.labels ?? {}) };
         }
         else {
             merged.set(svc.name, {
                 name: svc.name,
                 sources: [svc.source],
                 signalTypes: [svc.signalType],
+                labels: svc.labels ? { ...svc.labels } : undefined,
             });
         }
     }

package/dist/tools/query-traces.js

@@ -6,10 +6,12 @@
 // summaries, and recomputes a global p50/p95 over the merged set
 // (rather than blindly averaging per-source summaries).
 //
-// Backend support today: a Tempo connector + a Jaeger shim ship as
-// filesystem plugins. Any connector that implements queryTraces
-// participates automatically — no changes needed in the tool layer
-// when a new backend lands.
+// Backend support: no traces backend is bundled by default. The Tempo
+// connector ships in the connector hub (install it to enable traces);
+// there is no Jaeger connector today. Any connector that implements the
+// optional queryTraces capability participates automatically — so on a
+// stack without one the tool returns a clean "No trace backends
+// configured" result rather than failing.
 import { defaultContext } from "../context.js";
 import { validateDuration, validateServiceName, errorResponse } from "./validation.js";
 export const queryTracesDefinition = {
@@ -18,7 +20,7 @@ export const queryTracesDefinition = {
         "Query distributed traces for a service over a given timeframe.",
         "Returns ranked trace summaries with duration, error status, and span count, plus a p50/p95 duration aggregate across the returned set.",
         "When to use: investigating tail-latency outliers, walking call chains across services for a known time window, or pulling related traces for an anomaly the metric/log tools surfaced first.",
-        "Behavior: read-only; results may be capped via `limit` (default 50). `filter` accepts the backend's native query language (TraceQL on Tempo, tag query on Jaeger). When `errorsOnly=true`, only traces with at least one error span are returned.",
+        "Behavior: read-only; results may be capped via `limit` (default 50). `filter` accepts the backend's native query language (e.g. TraceQL on Tempo). When `errorsOnly=true`, only traces with at least one error span are returned.",
         "Related: `query_metrics` for the per-service latency series; `get_blast_radius` for the topology a trace traverses.",
     ].join(" "),
     inputSchema: {

package/package.json

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