@thotischner/observability-mcp 3.1.0 → 3.2.0

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;
@@ -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,11 +471,16 @@ 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()
                 .describe("Optional. Filter expression matched against the log message; regular expressions are supported. Omit to return all entries in the window."),
+            labels: z
+                .record(z.string(), z.string())
+                .optional()
+                .describe("Optional. Exact-match filters on backend-extracted log fields (e.g. {\"method\":\"GET\",\"status\":\"200\",\"url\":\"/\",\"environment\":\"prod\"}). All AND'd together and compiled to LogQL label filters applied after `| json`, so structured JSON fields become first-class selectors — far more reliable than regex on the raw message. Combine with `aggregate` to filter then group. Backends without label extraction ignore it."),
             duration: z
                 .string()
                 .optional()
@@ -445,19 +489,45 @@ async function main() {
                 .enum(["error", "warn", "info", "debug"])
                 .optional()
                 .describe("Optional. Return only entries at this severity. Default: all levels."),
+            aggregate: z
+                .object({
+                op: z
+                    .enum(["count_over_time", "sum", "topk"])
+                    .describe("count_over_time = time series of counts per `step` bucket; sum = single total per group over the window; topk = the top `k` groups by total."),
+                by: z
+                    .array(z.string())
+                    .optional()
+                    .describe("Label names to group by, e.g. [\"url\"] or [\"status\"]. Required for topk."),
+                k: z
+                    .number()
+                    .int()
+                    .positive()
+                    .optional()
+                    .describe("For topk: how many top groups to return (1-1000)."),
+                step: z
+                    .string()
+                    .optional()
+                    .describe("For count_over_time: bucket width as <number><unit> m|h|d (e.g. '15m'). Default auto-derived from duration."),
+            })
+                .optional()
+                .describe("Optional. Server-side aggregation pushed down to LogQL metric queries — returns grouped counts, not raw rows, so you get a number instead of a haystack (and never hit `limit`). Honours `labels`/`query` filters. Example: {\"op\":\"topk\",\"by\":[\"url\"],\"k\":10} for the busiest paths; {\"op\":\"count_over_time\",\"step\":\"15m\"} for a request-count time series."),
             limit: z
                 .number()
                 .int()
                 .positive()
                 .optional()
-                .describe("Optional. Maximum number of log entries to return (most recent first). Default: 100."),
+                .describe("Optional. Maximum number of log entries to return (most recent first). Default: 100. Ignored when `aggregate` is set."),
             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
@@ -613,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
@@ -3004,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()
@@ -3101,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/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/query-logs-schema.test.d.ts

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

package/dist/tools/query-logs-schema.test.js

@@ -0,0 +1,38 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+// Regression guard for issue #415: the query_logs handler (query-logs.ts)
+// reads `labels` and `aggregate` from its args, and validateLogLabels /
+// validateLogAggregate enforce them — but the MCP-facing input schema is
+// declared INLINE in createMcpServer's registerTool("query_logs", …) block
+// in index.ts. In v3.1.0 that inline schema was never updated to advertise
+// `labels`/`aggregate`, so the MCP SDK stripped those keys before they
+// reached the handler: the params were unreachable over MCP and passing
+// them was a silent no-op. The handler unit tests passed because they call
+// the handler directly, bypassing the SDK schema layer.
+//
+// This test parses index.ts and asserts the query_logs registration block
+// declares both fields as schema entries, so the SDK validates and forwards
+// them. The live equivalent (real tools/list handshake) lives in the
+// conformance suite; this is the fast, server-less guard.
+const here = dirname(fileURLToPath(import.meta.url));
+const INDEX_TS = join(here, "..", "index.ts");
+function registerToolBlock(src, tool) {
+    const start = src.indexOf(`registerTool(\n    "${tool}"`);
+    assert.notEqual(start, -1, `registerTool("${tool}", …) not found in index.ts`);
+    // The block ends at the next registerTool( call (or EOF).
+    const next = src.indexOf("registerTool(", start + 1);
+    return src.slice(start, next === -1 ? undefined : next);
+}
+test("query_logs MCP schema advertises `labels` (issue #415 #1)", () => {
+    const block = registerToolBlock(readFileSync(INDEX_TS, "utf8"), "query_logs");
+    assert.match(block, /\blabels:\s*z\b/, "query_logs registration in index.ts must declare a `labels` schema field " +
+        "so the MCP SDK forwards it to the handler (else it is silently stripped).");
+});
+test("query_logs MCP schema advertises `aggregate` (issue #415 #2)", () => {
+    const block = registerToolBlock(readFileSync(INDEX_TS, "utf8"), "query_logs");
+    assert.match(block, /\baggregate:\s*z\b/, "query_logs registration in index.ts must declare an `aggregate` schema field " +
+        "so the MCP SDK forwards it to the handler (else it is silently stripped).");
+});

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;

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/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