@thotischner/observability-mcp 3.1.1 → 3.2.1

package/dist/tools/query-logs.js

@@ -1,5 +1,5 @@
 import { defaultContext } from "../context.js";
-import { validateDuration, validateServiceName, validateLogLabels, validateLogAggregate, errorResponse } from "./validation.js";
+import { validateDuration, validateServiceName, validateLogLabels, validateLogAggregate, validateRawQuery, 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. 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).",
@@ -46,20 +46,37 @@ export const queryLogsDefinition = {
         required: ["service"],
     },
 };
-export async function queryLogsHandler(registry, args, ctx = defaultContext()) {
-    const svcErr = validateServiceName(args.service);
-    if (svcErr)
-        return errorResponse(svcErr);
+export async function queryLogsHandler(registry, args, ctx = defaultContext(), opts = {}) {
     const duration = args.duration || "5m";
     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);
+    // Raw LogQL passthrough — capability-gated, default off. Bypasses the curated
+    // stream-selector construction, so `service` is not required and is ignored.
+    // Mutually exclusive with `aggregate` (for metric LogQL use `aggregate`).
+    const rawErr = validateRawQuery(args.raw_query);
+    if (rawErr)
+        return errorResponse(rawErr);
+    const isRaw = !!args.raw_query;
+    if (isRaw && !opts.allowRawQuery) {
+        return errorResponse("raw_query is disabled. The operator must enable the raw-query capability (OMCP_RAW_QUERY=on) to run verbatim LogQL — it bypasses the curated log surface, so it is off by default.");
+    }
+    if (isRaw && args.aggregate) {
+        return errorResponse("raw_query and aggregate are mutually exclusive — a raw LogQL query expresses its own aggregation.");
+    }
+    if (!isRaw) {
+        if (!args.service)
+            return errorResponse("service is required (or set raw_query).");
+        const svcErr = validateServiceName(args.service);
+        if (svcErr)
+            return errorResponse(svcErr);
+        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 {
@@ -80,7 +97,7 @@ export async function queryLogsHandler(registry, args, ctx = defaultContext()) {
             capable++;
             try {
                 const q = {
-                    service: args.service,
+                    service: args.service ?? "",
                     duration,
                     labels: args.labels,
                     query: args.query,
@@ -119,12 +136,13 @@ export async function queryLogsHandler(registry, args, ctx = defaultContext()) {
             continue;
         try {
             const result = await connector.queryLogs({
-                service: args.service,
+                service: args.service ?? "",
                 query: args.query,
                 duration,
                 level: args.level,
                 limit: args.limit,
                 labels: args.labels,
+                rawQuery: args.raw_query,
             });
             results.push(result);
         }

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

@@ -31,12 +31,16 @@ export declare const queryMetricsDefinition: {
     };
 };
 export declare function queryMetricsHandler(registry: ConnectorRegistry, args: {
-    service: string;
-    metric: string;
+    service?: string;
+    metric?: string;
     duration?: string;
     source?: string;
     groupBy?: string;
-}, ctx?: RequestContext): Promise<{
+    labels?: Record<string, string>;
+    raw_query?: string;
+}, ctx?: RequestContext, opts?: {
+    allowRawQuery?: boolean;
+}): Promise<{
     content: {
         type: "text";
         text: string;

package/dist/tools/query-metrics.js

@@ -1,5 +1,5 @@
 import { defaultContext } from "../context.js";
-import { validateDuration, validateMetricName, validateServiceName, errorResponse } from "./validation.js";
+import { validateDuration, validateMetricName, validateServiceName, validateMetricLabels, validateRawQuery, 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.",
@@ -30,7 +30,7 @@ export const queryMetricsDefinition = {
         required: ["service", "metric"],
     },
 };
-export async function queryMetricsHandler(registry, args, ctx = defaultContext()) {
+export async function queryMetricsHandler(registry, args, ctx = defaultContext(), opts = {}) {
     // Coarse single-tenant source scoping: if the principal is restricted to a
     // source allow-list, deny an explicit out-of-scope source.
     if (ctx.allowedSources &&
@@ -38,18 +38,37 @@ export async function queryMetricsHandler(registry, args, ctx = defaultContext()
         !ctx.allowedSources.includes(args.source)) {
         return errorResponse(`forbidden: source "${args.source}" is not in your allowed sources`);
     }
-    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);
-    if (args.groupBy && !/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(args.groupBy)) {
-        return errorResponse(`Invalid groupBy "${args.groupBy}". Must be a valid Prometheus label name (alphanumeric + underscore, starting with letter/underscore).`);
+    // Raw PromQL passthrough — capability-gated, default off. Bypasses the
+    // curated metric catalog/selector, so service/metric/groupBy/labels are not
+    // required and are ignored. Still tenant-scoped + source-allow-listed below.
+    const rawErr = validateRawQuery(args.raw_query);
+    if (rawErr)
+        return errorResponse(rawErr);
+    const isRaw = !!args.raw_query;
+    if (isRaw && !opts.allowRawQuery) {
+        return errorResponse("raw_query is disabled. The operator must enable the raw-query capability (OMCP_RAW_QUERY=on) to run verbatim PromQL — it bypasses the curated metric surface, so it is off by default.");
+    }
+    if (!isRaw) {
+        if (!args.service)
+            return errorResponse("service is required (or set raw_query).");
+        const svcErr = validateServiceName(args.service);
+        if (svcErr)
+            return errorResponse(svcErr);
+        if (!args.metric)
+            return errorResponse("metric is required (or set raw_query).");
+        const metricErr = validateMetricName(args.metric, registry);
+        if (metricErr)
+            return errorResponse(metricErr);
+        if (args.groupBy && !/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(args.groupBy)) {
+            return errorResponse(`Invalid groupBy "${args.groupBy}". Must be a valid Prometheus label name (alphanumeric + underscore, starting with letter/underscore).`);
+        }
+        const labelsErr = validateMetricLabels(args.labels);
+        if (labelsErr)
+            return errorResponse(labelsErr);
     }
     // Tenant-scoped resolution: an explicit `source` from the agent
     // must belong to the caller's tenant (or be a global / untagged
@@ -80,10 +99,12 @@ export async function queryMetricsHandler(registry, args, ctx = defaultContext()
             continue;
         try {
             const result = await connector.queryMetrics({
-                service: args.service,
-                metric: args.metric,
+                service: args.service ?? "",
+                metric: args.metric ?? "",
                 duration,
                 groupBy: args.groupBy,
+                labels: args.labels,
+                rawQuery: args.raw_query,
             });
             results.push(result);
         }

package/dist/tools/query-raw-gate.test.d.ts

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

package/dist/tools/query-raw-gate.test.js

@@ -0,0 +1,52 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { ConnectorRegistry } from "../connectors/registry.js";
+import { PluginLoader } from "../connectors/loader.js";
+import { queryMetricsHandler } from "./query-metrics.js";
+import { queryLogsHandler } from "./query-logs.js";
+// R4 (issue #415 #3): raw_query is an escape hatch that bypasses the curated
+// metric/log surface, so it MUST be refused unless the operator enabled the
+// capability (opts.allowRawQuery, driven by OMCP_RAW_QUERY). These tests pin
+// the gate: the denial fires before any backend is touched, so an empty
+// registry is enough — and with the capability ON the call proceeds past the
+// gate to the normal "no backend configured" path.
+function parse(result) {
+    return JSON.parse(result.content[0].text);
+}
+describe("raw_query capability gate", () => {
+    const emptyRegistry = () => new ConnectorRegistry(new PluginLoader());
+    it("query_metrics refuses raw_query when capability is off (default)", async () => {
+        const out = parse(await queryMetricsHandler(emptyRegistry(), { raw_query: "up" }, undefined, { allowRawQuery: false }));
+        assert.match(out.error, /raw_query is disabled/i);
+        assert.match(out.error, /OMCP_RAW_QUERY/);
+    });
+    it("query_metrics defaults to refusing raw_query when no opts passed", async () => {
+        const out = parse(await queryMetricsHandler(emptyRegistry(), { raw_query: "up" }));
+        assert.match(out.error, /raw_query is disabled/i);
+    });
+    it("query_logs refuses raw_query when capability is off (default)", async () => {
+        const out = parse(await queryLogsHandler(emptyRegistry(), { raw_query: '{job="x"}' }, undefined, { allowRawQuery: false }));
+        assert.match(out.error, /raw_query is disabled/i);
+    });
+    it("query_metrics passes the gate when capability is on (reaches backend resolution)", async () => {
+        const out = parse(await queryMetricsHandler(emptyRegistry(), { raw_query: "up" }, undefined, { allowRawQuery: true }));
+        // Past the gate → normal no-backend path, NOT the capability denial.
+        assert.doesNotMatch(out.error ?? "", /raw_query is disabled/i);
+        assert.match(out.error, /No metrics backends configured/i);
+    });
+    it("query_logs passes the gate when capability is on (reaches backend resolution)", async () => {
+        const out = parse(await queryLogsHandler(emptyRegistry(), { raw_query: '{job="x"}' }, undefined, { allowRawQuery: true }));
+        assert.doesNotMatch(out.error ?? "", /raw_query is disabled/i);
+        assert.match(out.error, /No log backends configured/i);
+    });
+    it("query_logs rejects raw_query + aggregate as mutually exclusive", async () => {
+        const out = parse(await queryLogsHandler(emptyRegistry(), { raw_query: '{job="x"}', aggregate: { op: "count_over_time" } }, undefined, { allowRawQuery: true }));
+        assert.match(out.error, /mutually exclusive/i);
+    });
+    it("normal (non-raw) calls are unaffected by the capability flag", async () => {
+        // No raw_query → gate is a no-op even with capability off; falls through
+        // to normal validation/backend path.
+        const out = parse(await queryMetricsHandler(emptyRegistry(), { service: "api", metric: "cpu" }, undefined, { allowRawQuery: false }));
+        assert.doesNotMatch(out.error ?? "", /raw_query/i);
+    });
+});

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/dist/tools/registry-names.d.ts

@@ -13,7 +13,7 @@
  * Keep this list and the registerTool("name", ...) calls in
  * createMcpServer in sync. The test enforces it.
  */
-export declare const REGISTERED_TOOL_NAMES: readonly ["list_sources", "list_services", "query_metrics", "query_logs", "query_traces", "get_service_health", "detect_anomalies", "get_anomaly_history", "generate_postmortem", "get_topology", "get_blast_radius"];
+export declare const REGISTERED_TOOL_NAMES: readonly ["list_sources", "list_services", "query_metrics", "query_logs", "query_traces", "get_service_health", "detect_anomalies", "get_anomaly_history", "generate_postmortem", "get_topology", "get_blast_radius", "enrich_ips"];
 export type RegisteredToolName = typeof REGISTERED_TOOL_NAMES[number];
 /** Functional category of a tool, surfaced in /api/tools/registry and
  *  used by the Products UI to group the multi-select picker. Keeps

package/dist/tools/registry-names.js

@@ -25,6 +25,7 @@ export const REGISTERED_TOOL_NAMES = [
     "generate_postmortem",
     "get_topology",
     "get_blast_radius",
+    "enrich_ips",
 ];
 export const REGISTERED_TOOLS = [
     { name: "list_sources", category: "discovery", summary: "List configured observability backends + reachability." },
@@ -38,6 +39,7 @@ export const REGISTERED_TOOLS = [
     { name: "generate_postmortem", category: "diagnose", summary: "One-shot markdown post-mortem stitching anomaly history + traces + blast-radius + logs for a service." },
     { name: "get_topology", category: "topology", summary: "Return the infrastructure topology graph (resources + edges)." },
     { name: "get_blast_radius", category: "topology", summary: "Given a resource, return the impact set if its host(s) fail." },
+    { name: "enrich_ips", category: "query", summary: "Resolve IPv4 addresses to geo/ASN/org/hosting-flag from a local offline dataset." },
 ];
 /** Validate a candidate Product tools[] array. Returns the unknown
  *  names (empty array = all OK). Pure helper — the caller decides

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.1",
+  "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",