@thotischner/observability-mcp 3.1.0 → 3.2.0

package/dist/tools/topology.js

@@ -146,6 +146,20 @@ export async function getTopologyHandler(registry, args = {}, ctx = defaultConte
         total: { resources: agg.resources.length, edges: agg.edges.length },
         truncated,
     };
+    // Signal vs. silence: when NO topology-capable connector contributed a
+    // snapshot, an empty {resources:[],edges:[]} is ambiguous to an agent —
+    // it can't tell "graph is genuinely empty" from "no topology backend is
+    // wired up". Mirror query_traces' explicit "no backend" message so the
+    // agent gets a clear signal instead of silence (issue #415).
+    if (agg.sources.length === 0) {
+        payload.note =
+            "No topology-capable connector is configured, so the graph is empty. " +
+                "Topology comes from connectors like the built-in `kubernetes` source " +
+                "or the aws/gcp/istio/linkerd/consul providers — add one (see the " +
+                "Sources tab or docs/plugin-architecture) to populate this graph. " +
+                "A deployment with only metrics/logs backends (e.g. Prometheus/Loki) " +
+                "has no topology to report here.";
+    }
     return {
         content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
     };

package/dist/tools/topology.test.js

@@ -153,6 +153,21 @@ describe("get_topology tool", () => {
         assert.equal(out.truncated, true);
         assert.equal(out.total.resources, fixture().resources.length);
     });
+    it("does not attach the no-connector note when topology is present", async () => {
+        const reg = await makeRegistry();
+        const out = parseTool(await getTopologyHandler(reg, {}));
+        assert.equal(out.note, undefined);
+    });
+    it("returns an explicit note when no topology connector is configured (issue #415)", async () => {
+        // Empty registry — no topology-capable connector. The agent must get a
+        // clear signal, not a silent empty graph.
+        const reg = new ConnectorRegistry(new PluginLoader());
+        const out = parseTool(await getTopologyHandler(reg, {}));
+        assert.deepEqual(out.resources, []);
+        assert.deepEqual(out.edges, []);
+        assert.equal(out.sources.length, 0);
+        assert.match(out.note, /no topology-capable connector/i);
+    });
 });
 describe("get_blast_radius tool", () => {
     it("reports shared-host blast radius for a co-located pod", async () => {

package/dist/tools/validation.d.ts

@@ -16,6 +16,23 @@ export declare function validateServiceName(service: string): string | null;
  * can't build a pathological query.
  */
 export declare function validateLogLabels(labels: unknown): string | null;
+/**
+ * Validate a structured `labels` filter map for query_metrics. The rules are
+ * identical to the log-label validator (valid Prometheus label names, bounded
+ * map size + value length, fail-closed) — metric labels compile to PromQL
+ * label-equality matchers and the values are escaped for PromQL at injection
+ * time, exactly as the log path escapes for LogQL.
+ */
+export declare const validateMetricLabels: typeof validateLogLabels;
+/**
+ * Validate a raw PromQL/LogQL passthrough string. The capability gate (is raw
+ * query allowed at all) lives at the handler; this only bounds the shape:
+ * non-empty string, length-capped so a crafted query can't build a
+ * pathological request. The query is sent verbatim to the backend (that is the
+ * point of a passthrough), so there is no syntax check — an invalid query just
+ * yields the backend's own parse error.
+ */
+export declare function validateRawQuery(raw: unknown): string | null;
 /**
  * Validate the query_logs `aggregate` spec. Fail-closed, like the labels
  * validator. Returns an error string or null.

package/dist/tools/validation.js

@@ -73,6 +73,33 @@ export function validateLogLabels(labels) {
     }
     return null;
 }
+/**
+ * Validate a structured `labels` filter map for query_metrics. The rules are
+ * identical to the log-label validator (valid Prometheus label names, bounded
+ * map size + value length, fail-closed) — metric labels compile to PromQL
+ * label-equality matchers and the values are escaped for PromQL at injection
+ * time, exactly as the log path escapes for LogQL.
+ */
+export const validateMetricLabels = validateLogLabels;
+/**
+ * Validate a raw PromQL/LogQL passthrough string. The capability gate (is raw
+ * query allowed at all) lives at the handler; this only bounds the shape:
+ * non-empty string, length-capped so a crafted query can't build a
+ * pathological request. The query is sent verbatim to the backend (that is the
+ * point of a passthrough), so there is no syntax check — an invalid query just
+ * yields the backend's own parse error.
+ */
+export function validateRawQuery(raw) {
+    if (raw === undefined)
+        return null;
+    if (typeof raw !== "string")
+        return "raw_query must be a string.";
+    if (raw.trim().length === 0)
+        return "raw_query must not be empty.";
+    if (raw.length > 8192)
+        return "raw_query too long (max 8192 chars).";
+    return null;
+}
 const AGGREGATE_OPS = new Set(["count_over_time", "sum", "topk"]);
 /**
  * Validate the query_logs `aggregate` spec. Fail-closed, like the labels

package/dist/tools/validation.test.js

@@ -1,6 +1,6 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { validateDuration, validateServiceName, sanitizeLabelValue, validateLogLabels, validateLogAggregate, errorResponse } from "./validation.js";
+import { validateDuration, validateServiceName, sanitizeLabelValue, validateLogLabels, validateLogAggregate, validateMetricLabels, validateRawQuery, errorResponse } from "./validation.js";
 describe("validateLogAggregate (Q-LOG2)", () => {
     it("accepts undefined and valid specs", () => {
         assert.equal(validateLogAggregate(undefined), null);
@@ -54,6 +54,29 @@ describe("validateLogLabels (Q-LOG1)", () => {
         assert.ok(validateLogLabels(many));
     });
 });
+describe("validateRawQuery (R4, issue #415 #3)", () => {
+    it("accepts undefined (not requested) and a normal query", () => {
+        assert.equal(validateRawQuery(undefined), null);
+        assert.equal(validateRawQuery('sum(rate(http_requests_total[5m]))'), null);
+    });
+    it("rejects non-strings, empty/whitespace, and over-long", () => {
+        assert.ok(validateRawQuery(42));
+        assert.ok(validateRawQuery(""));
+        assert.ok(validateRawQuery("   "));
+        assert.ok(validateRawQuery("x".repeat(8193)));
+    });
+});
+describe("validateMetricLabels (R3, issue #415 #4)", () => {
+    it("accepts undefined and a valid map (same rules as log labels)", () => {
+        assert.equal(validateMetricLabels(undefined), null);
+        assert.equal(validateMetricLabels({ status: "500", route: "/checkout" }), null);
+    });
+    it("rejects invalid label names and bad values, fail-closed", () => {
+        assert.ok(validateMetricLabels({ "a-b": "x" }));
+        assert.ok(validateMetricLabels({ status: 500 }));
+        assert.ok(validateMetricLabels("nope"));
+    });
+});
 describe("validateDuration", () => {
     it("accepts valid durations", () => {
         assert.equal(validateDuration("5m"), null);

package/dist/types.d.ts

@@ -102,6 +102,11 @@ export interface MetricQuery {
     duration: string;
     step?: string;
     groupBy?: string;
+    labels?: Record<string, string>;
+    /** Raw PromQL, run verbatim over query_range — bypasses the curated metric
+     *  catalog/selector. When set, `metric`/`groupBy`/`labels`/`service` are
+     *  ignored. Gated by the OMCP_RAW_QUERY capability at the tool layer. */
+    rawQuery?: string;
 }
 export interface LogQuery {
     service: string;
@@ -115,6 +120,11 @@ export interface LogQuery {
      *  environment, …) become first-class selectors instead of brittle
      *  free-text regex. */
     labels?: Record<string, string>;
+    /** Raw LogQL log-selector query, run verbatim — bypasses the curated
+     *  stream-selector/pipeline construction. When set, `service`/`labels`/
+     *  `level`/`query` are ignored. Gated by the OMCP_RAW_QUERY capability at
+     *  the tool layer. For metric LogQL (count_over_time/…) use `aggregate`. */
+    rawQuery?: 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

package/package.json

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