@thotischner/observability-mcp 3.1.1 → 3.2.1

package/dist/enrich/ip-dataset.test.js

@@ -0,0 +1,85 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { ipv4ToInt, parseCidr, IpEnrichmentDataset } from "./ip-dataset.js";
+describe("ipv4ToInt", () => {
+    it("parses valid IPv4", () => {
+        assert.equal(ipv4ToInt("0.0.0.0"), 0);
+        assert.equal(ipv4ToInt("255.255.255.255"), 4294967295);
+        assert.equal(ipv4ToInt("1.2.3.4"), 0x01020304);
+    });
+    it("rejects malformed / out-of-range / non-IPv4", () => {
+        assert.equal(ipv4ToInt("1.2.3"), null);
+        assert.equal(ipv4ToInt("1.2.3.256"), null);
+        assert.equal(ipv4ToInt("1.2.3.4.5"), null);
+        assert.equal(ipv4ToInt("a.b.c.d"), null);
+        assert.equal(ipv4ToInt("::1"), null);
+        assert.equal(ipv4ToInt(""), null);
+    });
+});
+describe("parseCidr", () => {
+    it("parses a /24 to its inclusive range", () => {
+        const r = parseCidr("1.2.3.0/24");
+        assert.deepEqual(r, { start: 0x01020300, end: 0x010203ff, prefix: 24 });
+    });
+    it("treats a bare IP as /32", () => {
+        const r = parseCidr("203.0.113.5");
+        assert.equal(r?.prefix, 32);
+        assert.equal(r?.start, r?.end);
+    });
+    it("normalises a non-aligned base to the network address", () => {
+        // 1.2.3.42/24 → network 1.2.3.0
+        const r = parseCidr("1.2.3.42/24");
+        assert.equal(r?.start, 0x01020300);
+    });
+    it("handles /0 (whole space)", () => {
+        const r = parseCidr("0.0.0.0/0");
+        assert.deepEqual(r, { start: 0, end: 4294967295, prefix: 0 });
+    });
+    it("rejects bad prefixes / addresses", () => {
+        assert.equal(parseCidr("1.2.3.0/33"), null);
+        assert.equal(parseCidr("1.2.3.0/-1"), null);
+        assert.equal(parseCidr("nope/24"), null);
+    });
+});
+describe("IpEnrichmentDataset.fromCsv + lookup", () => {
+    const csv = [
+        "network,country,city,asn,org,hosting", // header skipped
+        "# a comment line",
+        "",
+        "10.0.0.0/8,US,,AS100,Example Cloud,true",
+        "10.1.2.0/24,US,Ashburn,AS100,Example Cloud Edge,true",
+        "203.0.113.5,DE,Berlin,AS3320,Example ISP,false",
+        "2001:db8::/32,XX,,,,", // IPv6 → skipped
+        "garbage-row",
+    ].join("\n");
+    it("parses rows, skips header/comments/blank, counts skipped", () => {
+        const ds = IpEnrichmentDataset.fromCsv(csv);
+        assert.equal(ds.size, 3); // 3 valid IPv4 rows
+        assert.equal(ds.skipped, 2); // IPv6 + garbage
+    });
+    it("returns the most specific (longest-prefix) match", () => {
+        const ds = IpEnrichmentDataset.fromCsv(csv);
+        // 10.1.2.5 is inside both /8 and /24 → the /24 (more specific) wins.
+        const hit = ds.lookup("10.1.2.5");
+        assert.equal(hit?.city, "Ashburn");
+        assert.equal(hit?.org, "Example Cloud Edge");
+        assert.equal(hit?.hosting, true);
+    });
+    it("falls back to the broader range when no specific one matches", () => {
+        const ds = IpEnrichmentDataset.fromCsv(csv);
+        const hit = ds.lookup("10.5.5.5"); // only in /8
+        assert.equal(hit?.asn, "AS100");
+        assert.equal(hit?.city, undefined); // empty cell omitted
+    });
+    it("matches a /32 exactly and parses hosting=false", () => {
+        const ds = IpEnrichmentDataset.fromCsv(csv);
+        const hit = ds.lookup("203.0.113.5");
+        assert.equal(hit?.country, "DE");
+        assert.equal(hit?.hosting, false);
+    });
+    it("returns null for an unmatched or invalid IP", () => {
+        const ds = IpEnrichmentDataset.fromCsv(csv);
+        assert.equal(ds.lookup("8.8.8.8"), null);
+        assert.equal(ds.lookup("not-an-ip"), null);
+    });
+});

package/dist/index.js

@@ -58,6 +58,8 @@ import { listSourcesHandler } from "./tools/list-sources.js";
 import { listServicesHandler } from "./tools/list-services.js";
 import { queryMetricsHandler } from "./tools/query-metrics.js";
 import { queryLogsHandler } from "./tools/query-logs.js";
+import { enrichIpsHandler } from "./tools/enrich-ips.js";
+import { IpEnrichmentDataset } from "./enrich/ip-dataset.js";
 import { queryTracesHandler } from "./tools/query-traces.js";
 import { getAnomalyHistoryHandler } from "./tools/get-anomaly-history.js";
 import { generatePostmortemHandler } from "./tools/generate-postmortem.js";
@@ -269,6 +271,33 @@ async function main() {
         return applyBudgetDecision(result, decision, tokens, toolName);
     }
     const REDACTION_ENABLED = String(process.env.OMCP_REDACTION ?? "on").toLowerCase() !== "off";
+    // Raw PromQL/LogQL passthrough capability — default OFF. A raw query bypasses
+    // the curated metric/log surface (catalog, selector scoping), so it is an
+    // explicit operator opt-in. Enable with OMCP_RAW_QUERY=on (or true/1).
+    const RAW_QUERY_ENABLED = ["on", "true", "1"].includes(String(process.env.OMCP_RAW_QUERY ?? "off").toLowerCase());
+    // Opt the anonymous/default identity into per-call redaction bypass. In an
+    // anonymous deployment (no OMCP_API_KEYS) there is no named credential to
+    // add to OMCP_KEY_BYPASS_REDACTION, so a per-call bypass_redaction can never
+    // succeed — the only lever was the blunt global OMCP_REDACTION=off. This
+    // flag lets a single-user self-hosted agent see raw values on its own logs
+    // via the per-call arg, while redaction stays the default. Default OFF.
+    const BYPASS_REDACTION_ANON = ["on", "true", "1"].includes(String(process.env.OMCP_BYPASS_REDACTION_ANON ?? "false").toLowerCase());
+    // Offline IP-enrichment dataset (issue #415 Gap B) — loaded once at boot from
+    // a local CSV (OMCP_IP_ENRICH_FILE). No external geo/ASN API is ever called,
+    // so it stays air-gapped. Unset / unreadable → enrich_ips returns a clear
+    // "not configured" notice rather than failing.
+    let ipEnrichment = null;
+    const ipEnrichFile = process.env.OMCP_IP_ENRICH_FILE;
+    if (ipEnrichFile) {
+        try {
+            ipEnrichment = IpEnrichmentDataset.fromCsv(readFileSync(ipEnrichFile, "utf8"));
+            console.log(`[enrich] IP enrichment dataset loaded from ${ipEnrichFile}: ${ipEnrichment.size} ranges` +
+                (ipEnrichment.skipped ? ` (${ipEnrichment.skipped} rows skipped)` : ""));
+        }
+        catch (err) {
+            console.error(`[enrich] failed to load OMCP_IP_ENRICH_FILE (${ipEnrichFile}): ${err instanceof Error ? err.message : String(err)} — enrich_ips will report 'not configured'`);
+        }
+    }
     function redactToolText(result, opts = {}) {
         if (!REDACTION_ENABLED)
             return result;
@@ -370,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" });
@@ -403,10 +432,12 @@ async function main() {
         ].join(" "), {
             service: z
                 .string()
-                .describe("Required. Exact, case-sensitive service name exactly as returned by `list_services` (e.g. 'api-gateway', 'payment-service')."),
+                .optional()
+                .describe("Required (unless `raw_query` is set). Exact, case-sensitive service name exactly as returned by `list_services` (e.g. 'api-gateway', 'payment-service')."),
             metric: z
                 .string()
-                .describe(`Required. Exact metric name to query. One of: ${uniqueNames.join(", ")}.`),
+                .optional()
+                .describe(`Required (unless ` + "`raw_query`" + ` is set). Exact metric name to query. One of: ${uniqueNames.join(", ")}.`),
             duration: z
                 .string()
                 .optional()
@@ -419,9 +450,17 @@ async function main() {
                 .string()
                 .optional()
                 .describe("Optional. Metric label to break the result down by, e.g. 'instance', 'pod', 'node'. When set, the response contains one series per distinct label value under `groups`. Default: a single aggregated series."),
+            labels: z
+                .record(z.string(), z.string())
+                .optional()
+                .describe("Optional. Exact-match label filters (e.g. {\"status\":\"500\",\"route\":\"/checkout\"}) AND'd into the metric's series selector — the PromQL equivalent of the query_logs `labels` param. Use this to scope a curated metric to a subset of series (e.g. error_rate for one route/status) instead of the all-series aggregate. Combine with `groupBy` to filter then break down. Label names must be valid Prometheus identifiers."),
+            raw_query: z
+                .string()
+                .optional()
+                .describe("Optional escape hatch: a verbatim PromQL expression, run as-is over the range — for ad-hoc queries the curated `metric` catalog can't express (any series, any function, broken down by any label). When set, `metric`/`service`/`groupBy`/`labels` are ignored. DISABLED by default; the operator must enable the raw-query capability (OMCP_RAW_QUERY=on) or the call is refused. Still tenant-scoped and source-allow-listed."),
         }, async (args) => {
             await enforceEntitledAccess(ctx, { tool: "query_metrics", source: args?.source, service: args?.service });
-            const result = await withToolMetrics("query_metrics", () => queryMetricsHandler(registry, args, ctx));
+            const result = await withToolMetrics("query_metrics", () => queryMetricsHandler(registry, args, ctx, { allowRawQuery: RAW_QUERY_ENABLED }));
             return chargeTokenBudget(result, ctx, "query_metrics");
         });
         registerTool("query_logs", [
@@ -432,7 +471,8 @@ async function main() {
         ].join(" "), {
             service: z
                 .string()
-                .describe("Required. Exact, case-sensitive service name exactly as returned by `list_services` (e.g. 'payment-service')."),
+                .optional()
+                .describe("Required (unless `raw_query` is set). Exact, case-sensitive service name exactly as returned by `list_services` (e.g. 'payment-service')."),
             query: z
                 .string()
                 .optional()
@@ -480,10 +520,14 @@ async function main() {
             bypass_redaction: z
                 .boolean()
                 .optional()
-                .describe("Optional. When true, request that PII/secret redaction be skipped for this single call. The server only honours this when the calling credential was explicitly authorised via OMCP_KEY_BYPASS_REDACTION; otherwise the request still gets redacted output. Default: false."),
+                .describe("Optional. When true, request that PII/secret redaction be skipped for this single call. The server only honours this when the calling identity is authorised to bypass — a credential listed in OMCP_KEY_BYPASS_REDACTION, or the anonymous identity when the operator set OMCP_BYPASS_REDACTION_ANON=true; otherwise the request still gets redacted output. Default: false."),
+            raw_query: z
+                .string()
+                .optional()
+                .describe("Optional escape hatch: a verbatim LogQL log query, run as-is — for selectors/pipelines the curated params can't express. When set, `service`/`labels`/`level`/`query` are ignored and it is mutually exclusive with `aggregate` (express aggregation in the LogQL itself). DISABLED by default; the operator must enable the raw-query capability (OMCP_RAW_QUERY=on) or the call is refused. Redaction still applies to the returned log lines."),
         }, async (args) => {
             await enforceEntitledAccess(ctx, { tool: "query_logs", source: args?.source, service: args?.service });
-            const result = await withToolMetrics("query_logs", () => queryLogsHandler(registry, args, ctx));
+            const result = await withToolMetrics("query_logs", () => queryLogsHandler(registry, args, ctx, { allowRawQuery: RAW_QUERY_ENABLED }));
             // Redact PII / secrets from the log payload before it crosses the
             // MCP boundary into the agent's context. Per-call bypass kicks in
             // only when BOTH (a) the credential is OMCP_KEY_BYPASS_REDACTION
@@ -545,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'."),
@@ -639,6 +683,19 @@ async function main() {
             await enforceEntitledAccess(ctx, { tool: "get_blast_radius" });
             return withToolMetrics("get_blast_radius", () => getBlastRadiusHandler(registry, args, ctx));
         });
+        registerTool("enrich_ips", [
+            "Resolve a batch of IPv4 addresses to geo (country/city), ASN/org, and a hosting/proxy flag.",
+            "When to use: answering 'where are these visitors from?' or 'which of these IPs are bots / datacenter / VPN exit nodes?' over access logs, without an out-of-band geo-API call per IP.",
+            "Behavior: read-only. Looks each IP up in a LOCAL offline dataset the operator configured (OMCP_IP_ENRICH_FILE) — there is no external network call, so it is safe in air-gapped deployments. Returns one row per input IP with found=true/false plus any known fields. If no dataset is configured it returns a clear notice explaining how to enable it.",
+            "Related: pull the IPs from `query_logs` (use `labels`/`aggregate` to find the IPs of interest first).",
+        ].join(" "), {
+            ips: z
+                .array(z.string())
+                .describe("Required. IPv4 address strings to enrich (e.g. ['203.0.113.5','198.51.100.9']). Max 1000 per call; invalid entries are returned with found=false rather than failing the batch."),
+        }, async (args) => {
+            await enforceEntitledAccess(ctx, { tool: "enrich_ips" });
+            return withToolMetrics("enrich_ips", async () => enrichIpsHandler(ipEnrichment, args, ctx));
+        });
         // Phase F10: federated tools — every upstream MCP server's tools
         // show up here under `<prefix>.<upstream-tool>`. The handler is a
         // pure proxy: it forwards args verbatim and returns the upstream's
@@ -1060,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()) {
@@ -3030,8 +3087,10 @@ async function main() {
         res.json({ ok: true });
     });
     // Stdio transport: one server over stdin/stdout, no HTTP listener.
+    // Stdio is inherently a local single-user channel, so the anonymous
+    // redaction-bypass opt-in applies here too.
     if (STDIO) {
-        const { mcpServer: server } = createMcpServer(defaultContext());
+        const { mcpServer: server } = createMcpServer(defaultContext({ allowBypassRedaction: BYPASS_REDACTION_ANON }));
         await server.connect(new StdioServerTransport());
         console.error(`observability-mcp running on stdio transport · connectors: ${registry
             .getAll()
@@ -3127,7 +3186,7 @@ async function main() {
     // coarse source allow-list into the RequestContext.
     async function gateCtx(req, res) {
         if (!credentialsConfigured())
-            return defaultContext();
+            return defaultContext({ allowBypassRedaction: BYPASS_REDACTION_ANON });
         const cred = resolveToken(extractToken(req.headers), loadCredentials());
         if (!cred) {
             res

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/enrich-ips.d.ts

@@ -0,0 +1,30 @@
+import { IpEnrichmentDataset } from "../enrich/ip-dataset.js";
+import { type RequestContext } from "../context.js";
+export declare const enrichIpsDefinition: {
+    name: "enrich_ips";
+    description: string;
+};
+export interface EnrichIpsArgs {
+    ips?: string[];
+}
+export interface IpEnrichmentResult {
+    ip: string;
+    found: boolean;
+    country?: string;
+    city?: string;
+    asn?: string;
+    org?: string;
+    hosting?: boolean;
+}
+export declare function enrichIpsHandler(dataset: IpEnrichmentDataset | null, args: EnrichIpsArgs, _ctx?: RequestContext): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};

package/dist/tools/enrich-ips.js

@@ -0,0 +1,60 @@
+import { ipv4ToInt } from "../enrich/ip-dataset.js";
+import { defaultContext } from "../context.js";
+import { errorResponse } from "./validation.js";
+// enrich_ips (issue #415 Gap B): resolve a batch of IPs to geo / ASN / org /
+// hosting-flag from the operator's LOCAL offline dataset. No external lookups,
+// so it is safe in air-gapped deployments. Disabled (returns a clear message)
+// when no dataset is configured.
+export const enrichIpsDefinition = {
+    name: "enrich_ips",
+    description: "Resolve a batch of IPv4 addresses to geo (country/city), ASN/org, and a hosting/proxy flag from a local offline dataset. Use this to answer 'where are these visitors from / which are bots or datacenter IPs' without an out-of-band geo API call. Requires the operator to have configured an offline dataset (OMCP_IP_ENRICH_FILE); returns a clear notice otherwise.",
+};
+const MAX_IPS = 1000;
+export function enrichIpsHandler(dataset, args, 
+// The RequestContext seam — enrich_ips doesn't scope by tenant today (the
+// dataset is a single process-wide table), but every tool handler threads
+// ctx so access-control / audit can attach without a signature change later.
+_ctx = defaultContext()) {
+    if (!dataset) {
+        return errorResponse("IP enrichment is not configured. Set OMCP_IP_ENRICH_FILE to a local CSV " +
+            "(network,country,city,asn,org,hosting) to enable offline geo/ASN/hosting " +
+            "lookups — there is no external API call, so it stays air-gapped.");
+    }
+    const ips = args.ips;
+    if (!Array.isArray(ips) || ips.length === 0) {
+        return errorResponse("`ips` must be a non-empty array of IPv4 address strings.");
+    }
+    if (ips.length > MAX_IPS) {
+        return errorResponse(`Too many IPs (${ips.length}); max ${MAX_IPS} per call.`);
+    }
+    const results = [];
+    let invalid = 0;
+    let matched = 0;
+    for (const ip of ips) {
+        if (typeof ip !== "string" || ipv4ToInt(ip) === null) {
+            invalid++;
+            results.push({ ip: String(ip), found: false });
+            continue;
+        }
+        const hit = dataset.lookup(ip);
+        if (hit) {
+            matched++;
+            results.push({ ip, found: true, ...hit });
+        }
+        else {
+            results.push({ ip, found: false });
+        }
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    results,
+                    summary: { total: ips.length, matched, unmatched: ips.length - matched - invalid, invalid },
+                    datasetSize: dataset.size,
+                }, null, 2),
+            },
+        ],
+    };
+}

package/dist/tools/enrich-ips.test.d.ts

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

package/dist/tools/enrich-ips.test.js

@@ -0,0 +1,38 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { IpEnrichmentDataset } from "../enrich/ip-dataset.js";
+import { enrichIpsHandler } from "./enrich-ips.js";
+function parse(result) {
+    return JSON.parse(result.content[0].text);
+}
+const ds = IpEnrichmentDataset.fromCsv(["1.2.3.0/24,US,Ashburn,AS14618,Example Cloud,true", "203.0.113.5,DE,Berlin,AS3320,Example ISP,false"].join("\n"));
+describe("enrichIpsHandler (R6, issue #415 Gap B)", () => {
+    it("returns a clear 'not configured' notice when no dataset is loaded", () => {
+        const out = parse(enrichIpsHandler(null, { ips: ["1.2.3.4"] }));
+        assert.match(out.error, /not configured/i);
+        assert.match(out.error, /OMCP_IP_ENRICH_FILE/);
+    });
+    it("rejects empty / missing ips", () => {
+        assert.match(parse(enrichIpsHandler(ds, { ips: [] })).error, /non-empty array/i);
+        assert.match(parse(enrichIpsHandler(ds, {})).error, /non-empty array/i);
+    });
+    it("rejects an over-large batch", () => {
+        const many = Array.from({ length: 1001 }, (_, i) => `1.2.3.${i % 255}`);
+        assert.match(parse(enrichIpsHandler(ds, { ips: many })).error, /Too many IPs/i);
+    });
+    it("enriches known IPs and reports found=false for misses + invalid", () => {
+        const out = parse(enrichIpsHandler(ds, { ips: ["1.2.3.99", "8.8.8.8", "not-an-ip"] }));
+        assert.equal(out.results.length, 3);
+        const matched = out.results.find((r) => r.ip === "1.2.3.99");
+        assert.equal(matched.found, true);
+        assert.equal(matched.city, "Ashburn");
+        assert.equal(matched.hosting, true);
+        const miss = out.results.find((r) => r.ip === "8.8.8.8");
+        assert.equal(miss.found, false);
+        assert.equal(miss.city, undefined);
+        const invalid = out.results.find((r) => r.ip === "not-an-ip");
+        assert.equal(invalid.found, false);
+        assert.deepEqual(out.summary, { total: 3, matched: 1, unmatched: 1, invalid: 1 });
+        assert.equal(out.datasetSize, 2);
+    });
+});

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-logs.d.ts

@@ -64,7 +64,7 @@ export declare const queryLogsDefinition: {
     };
 };
 export declare function queryLogsHandler(registry: ConnectorRegistry, args: {
-    service: string;
+    service?: string;
     query?: string;
     duration?: string;
     level?: string;
@@ -76,7 +76,10 @@ export declare function queryLogsHandler(registry: ConnectorRegistry, args: {
         k?: number;
         step?: string;
     };
-}, ctx?: RequestContext): Promise<{
+    raw_query?: string;
+}, ctx?: RequestContext, opts?: {
+    allowRawQuery?: boolean;
+}): Promise<{
     content: {
         type: "text";
         text: string;