@thotischner/observability-mcp 3.3.2 → 3.5.0

package/dist/scim/query.d.ts

@@ -0,0 +1,32 @@
+export interface ScimFilter {
+    attr: string;
+    op: "eq";
+    /** Comparison value: a string, or a boolean for `active eq true`. */
+    value: string | boolean;
+}
+/** Parse a SCIM `filter` expression. Returns null for an empty/absent filter,
+ *  or throws {unsupported:true} for a syntactically-valid filter we don't
+ *  implement (a non-eq operator) so the caller can answer 400, not 200. */
+export declare function parseScimFilter(raw: string | undefined): ScimFilter | null;
+export interface ScimListResult<T> {
+    resources: T[];
+    totalResults: number;
+    startIndex: number;
+    itemsPerPage: number;
+}
+/**
+ * Apply a SCIM `eq` filter + startIndex/count pagination to a resource list.
+ * `filter`/`startIndex`/`count` are the raw query-string values.
+ *
+ * - filter: only `eq` (string, case-insensitive; or boolean for `active`).
+ * - startIndex: 1-based (SCIM); clamped to >= 1; default 1.
+ * - count: page size; clamped to [0, 1000]; absent → all remaining.
+ *
+ * Throws a {scimUnsupported:true} error for a non-eq filter so the route can
+ * return 400 rather than a misleading full list.
+ */
+export declare function applyScimList<T extends Record<string, unknown>>(all: T[], q: {
+    filter?: string;
+    startIndex?: string;
+    count?: string;
+}): ScimListResult<T>;

package/dist/scim/query.js

@@ -0,0 +1,73 @@
+// SCIM 2.0 list query: filter + pagination (RFC 7644 §3.4.2).
+//
+// Identity providers (Entra, Okta) reconcile by issuing
+//   GET /Users?filter=userName eq "alice@example.com"
+// and page large directories with startIndex/count. Without filter support a
+// provider has to pull the whole list and match client-side — slow and, for
+// Okta, a hard requirement. We support the `eq` operator on top-level string
+// attributes (userName, displayName, externalId, id) plus `active eq true`,
+// which covers what Entra/Okta actually send. Other operators are reported as
+// unsupported (400) rather than silently returning everything — silence here
+// would make a provider think "no match" when it means "not implemented".
+/** Parse a SCIM `filter` expression. Returns null for an empty/absent filter,
+ *  or throws {unsupported:true} for a syntactically-valid filter we don't
+ *  implement (a non-eq operator) so the caller can answer 400, not 200. */
+export function parseScimFilter(raw) {
+    if (!raw || !raw.trim())
+        return null;
+    const s = raw.trim();
+    // <attr> eq "value"   |   <attr> eq true|false
+    const m = /^([A-Za-z][\w.]*)\s+(eq)\s+(?:"([^"]*)"|(true|false))$/i.exec(s);
+    if (!m) {
+        // Either an unsupported operator (co, sw, gt, …) or malformed. Signal
+        // unsupported so the route returns 400 instead of an all-rows 200.
+        const err = new Error(`Unsupported or malformed SCIM filter: ${raw}`);
+        err.scimUnsupported = true;
+        throw err;
+    }
+    const attr = m[1];
+    const value = m[3] !== undefined ? m[3] : m[4].toLowerCase() === "true";
+    return { attr, op: "eq", value };
+}
+/** Read a top-level attribute off a SCIM resource for `eq` comparison.
+ *  Only flat attributes are supported (userName/displayName/externalId/id/
+ *  active) — nested paths (name.familyName) aren't part of the eq surface. */
+function attrValue(resource, attr) {
+    // Case-insensitive attribute match per the SCIM spec (attribute names are
+    // case-insensitive); providers send `userName`, some send `username`.
+    const key = Object.keys(resource).find((k) => k.toLowerCase() === attr.toLowerCase());
+    return key ? resource[key] : undefined;
+}
+/**
+ * Apply a SCIM `eq` filter + startIndex/count pagination to a resource list.
+ * `filter`/`startIndex`/`count` are the raw query-string values.
+ *
+ * - filter: only `eq` (string, case-insensitive; or boolean for `active`).
+ * - startIndex: 1-based (SCIM); clamped to >= 1; default 1.
+ * - count: page size; clamped to [0, 1000]; absent → all remaining.
+ *
+ * Throws a {scimUnsupported:true} error for a non-eq filter so the route can
+ * return 400 rather than a misleading full list.
+ */
+export function applyScimList(all, q) {
+    const filter = parseScimFilter(q.filter);
+    let filtered = all;
+    if (filter) {
+        filtered = all.filter((r) => {
+            const v = attrValue(r, filter.attr);
+            if (typeof filter.value === "boolean")
+                return Boolean(v) === filter.value;
+            // String eq is case-insensitive per the SCIM spec for these attrs.
+            return v !== undefined && String(v).toLowerCase() === filter.value.toLowerCase();
+        });
+    }
+    const total = filtered.length;
+    const startIndex = Math.max(1, Number.parseInt(q.startIndex ?? "1", 10) || 1);
+    const from = startIndex - 1;
+    const rawCount = q.count === undefined ? undefined : Number.parseInt(q.count, 10);
+    const count = rawCount === undefined || Number.isNaN(rawCount)
+        ? undefined
+        : Math.min(1000, Math.max(0, rawCount));
+    const page = count === undefined ? filtered.slice(from) : filtered.slice(from, from + count);
+    return { resources: page, totalResults: total, startIndex, itemsPerPage: page.length };
+}

package/dist/scim/query.test.d.ts

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

package/dist/scim/query.test.js

@@ -0,0 +1,71 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { parseScimFilter, applyScimList } from "./query.js";
+describe("parseScimFilter", () => {
+    it("returns null for absent/empty filter", () => {
+        assert.equal(parseScimFilter(undefined), null);
+        assert.equal(parseScimFilter("   "), null);
+    });
+    it("parses string eq (case-insensitive op)", () => {
+        assert.deepEqual(parseScimFilter('userName eq "alice@x.com"'), { attr: "userName", op: "eq", value: "alice@x.com" });
+        assert.deepEqual(parseScimFilter('displayName EQ "Admins"'), { attr: "displayName", op: "eq", value: "Admins" });
+    });
+    it("parses boolean eq for active", () => {
+        assert.deepEqual(parseScimFilter("active eq true"), { attr: "active", op: "eq", value: true });
+        assert.deepEqual(parseScimFilter("active eq false"), { attr: "active", op: "eq", value: false });
+    });
+    it("throws scimUnsupported for non-eq operators / malformed", () => {
+        for (const f of ['userName co "a"', 'userName sw "a"', 'userName pr', 'garbage']) {
+            assert.throws(() => parseScimFilter(f), (e) => e.scimUnsupported === true, `expected unsupported for: ${f}`);
+        }
+    });
+});
+describe("applyScimList", () => {
+    const users = [
+        { id: "1", userName: "alice@x.com", active: true },
+        { id: "2", userName: "bob@x.com", active: false },
+        { id: "3", userName: "carol@x.com", active: true },
+    ];
+    it("no filter, no pagination → all rows, correct envelope", () => {
+        const r = applyScimList(users, {});
+        assert.equal(r.totalResults, 3);
+        assert.equal(r.startIndex, 1);
+        assert.equal(r.itemsPerPage, 3);
+        assert.equal(r.resources.length, 3);
+    });
+    it("eq filter matches case-insensitively on the value", () => {
+        const r = applyScimList(users, { filter: 'userName eq "ALICE@X.COM"' });
+        assert.equal(r.totalResults, 1);
+        assert.equal(r.resources[0].id, "1");
+    });
+    it("eq filter with no match → empty, totalResults 0 (not all rows)", () => {
+        const r = applyScimList(users, { filter: 'userName eq "nobody@x.com"' });
+        assert.equal(r.totalResults, 0);
+        assert.equal(r.resources.length, 0);
+    });
+    it("boolean eq filters on active", () => {
+        assert.equal(applyScimList(users, { filter: "active eq true" }).totalResults, 2);
+        assert.equal(applyScimList(users, { filter: "active eq false" }).totalResults, 1);
+    });
+    it("pagination: startIndex + count slice; totalResults is the pre-page count", () => {
+        const r = applyScimList(users, { startIndex: "2", count: "1" });
+        assert.equal(r.totalResults, 3);
+        assert.equal(r.startIndex, 2);
+        assert.equal(r.itemsPerPage, 1);
+        assert.equal(r.resources[0].id, "2");
+    });
+    it("count=0 returns an empty page but the real totalResults", () => {
+        const r = applyScimList(users, { count: "0" });
+        assert.equal(r.totalResults, 3);
+        assert.equal(r.resources.length, 0);
+    });
+    it("filter + pagination compose", () => {
+        const r = applyScimList(users, { filter: "active eq true", startIndex: "2", count: "5" });
+        assert.equal(r.totalResults, 2); // alice + carol
+        assert.equal(r.resources.length, 1); // from index 2 of the 2 matches
+        assert.equal(r.resources[0].id, "3");
+    });
+    it("propagates the unsupported-filter error for the route to 400", () => {
+        assert.throws(() => applyScimList(users, { filter: 'userName co "x"' }), (e) => e.scimUnsupported === true);
+    });
+});

package/dist/scim/routes.js

@@ -4,7 +4,7 @@
 //   GET    /scim/v2/ServiceProviderConfig
 //   GET    /scim/v2/ResourceTypes
 //   GET    /scim/v2/Schemas
-//   GET    /scim/v2/Users        list (no filter support yet)
+//   GET    /scim/v2/Users        list (filter: <attr> eq "x"; startIndex/count)
 //   GET    /scim/v2/Users/:id
 //   POST   /scim/v2/Users
 //   PATCH  /scim/v2/Users/:id    minimal: replace top-level attrs
@@ -20,6 +20,7 @@
 import { timingSafeEqual } from "node:crypto";
 import { SCIM_SCHEMA_LIST_RESPONSE, SCIM_SCHEMA_USER, SCIM_SCHEMA_GROUP, scimError, } from "./types.js";
 import { ScimNotFoundError, ScimValidationError } from "./store.js";
+import { applyScimList } from "./query.js";
 const constantTimeBearerMatch = (raw, expected) => {
     if (!raw)
         return false;
@@ -57,7 +58,7 @@ export function registerScimRoutes(app, deps) {
             documentationUri: "https://thotischner.github.io/observability-mcp/scim-provisioning/",
             patch: { supported: true },
             bulk: { supported: false, maxOperations: 0, maxPayloadSize: 0 },
-            filter: { supported: false, maxResults: 200 },
+            filter: { supported: true, maxResults: 200 },
             changePassword: { supported: false },
             sort: { supported: false },
             etag: { supported: false },
@@ -108,14 +109,25 @@ export function registerScimRoutes(app, deps) {
         });
     });
     // ---- Users ----
-    app.get("/scim/v2/Users", (_req, res) => {
+    app.get("/scim/v2/Users", (req, res) => {
         const users = store.listUsers().map((u) => withGroups(u, store));
+        let page;
+        try {
+            page = applyScimList(users, req.query);
+        }
+        catch (e) {
+            if (e.scimUnsupported) {
+                res.status(400).json(scimError(400, e.message));
+                return;
+            }
+            throw e;
+        }
         res.json({
             schemas: [SCIM_SCHEMA_LIST_RESPONSE],
-            totalResults: users.length,
-            itemsPerPage: users.length,
-            startIndex: 1,
-            Resources: users,
+            totalResults: page.totalResults,
+            itemsPerPage: page.itemsPerPage,
+            startIndex: page.startIndex,
+            Resources: page.resources,
         });
     });
     app.get("/scim/v2/Users/:id", (req, res) => {
@@ -157,14 +169,25 @@ export function registerScimRoutes(app, deps) {
         res.status(204).end();
     });
     // ---- Groups ----
-    app.get("/scim/v2/Groups", (_req, res) => {
+    app.get("/scim/v2/Groups", (req, res) => {
         const groups = store.listGroups();
+        let page;
+        try {
+            page = applyScimList(groups, req.query);
+        }
+        catch (e) {
+            if (e.scimUnsupported) {
+                res.status(400).json(scimError(400, e.message));
+                return;
+            }
+            throw e;
+        }
         res.json({
             schemas: [SCIM_SCHEMA_LIST_RESPONSE],
-            totalResults: groups.length,
-            itemsPerPage: groups.length,
-            startIndex: 1,
-            Resources: groups,
+            totalResults: page.totalResults,
+            itemsPerPage: page.itemsPerPage,
+            startIndex: page.startIndex,
+            Resources: page.resources,
         });
     });
     app.get("/scim/v2/Groups/:id", (req, res) => {

package/dist/tools/enrich-ips.js

@@ -1,4 +1,4 @@
-import { ipv4ToInt } from "../enrich/ip-dataset.js";
+import { ipv4ToInt, ipv6ToBigInt } 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 /
@@ -7,9 +7,13 @@ import { errorResponse } from "./validation.js";
 // 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.",
+    description: "Resolve a batch of IPv4 or IPv6 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;
+/** A string is a valid IP if it parses as either IPv4 or IPv6. */
+function isValidIp(ip) {
+    return ipv4ToInt(ip) !== null || ipv6ToBigInt(ip) !== null;
+}
 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
@@ -22,7 +26,7 @@ _ctx = defaultContext()) {
     }
     const ips = args.ips;
     if (!Array.isArray(ips) || ips.length === 0) {
-        return errorResponse("`ips` must be a non-empty array of IPv4 address strings.");
+        return errorResponse("`ips` must be a non-empty array of IPv4 or IPv6 address strings.");
     }
     if (ips.length > MAX_IPS) {
         return errorResponse(`Too many IPs (${ips.length}); max ${MAX_IPS} per call.`);
@@ -31,7 +35,7 @@ _ctx = defaultContext()) {
     let invalid = 0;
     let matched = 0;
     for (const ip of ips) {
-        if (typeof ip !== "string" || ipv4ToInt(ip) === null) {
+        if (typeof ip !== "string" || !isValidIp(ip)) {
             invalid++;
             results.push({ ip: String(ip), found: false });
             continue;

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

@@ -35,4 +35,15 @@ describe("enrichIpsHandler (R6, issue #415 Gap B)", () => {
         assert.deepEqual(out.summary, { total: 3, matched: 1, unmatched: 1, invalid: 1 });
         assert.equal(out.datasetSize, 2);
     });
+    it("accepts IPv6 inputs and enriches them (not counted invalid)", () => {
+        const ds6 = IpEnrichmentDataset.fromCsv(["2001:db8::/32,US,,AS14618,Example Cloud,true", "1.2.3.0/24,DE,Berlin,AS3320,Example ISP,false"].join("\n"));
+        const out = parse(enrichIpsHandler(ds6, { ips: ["2001:db8::1", "2606:4700::1", "1.2.3.9"] }));
+        const v6hit = out.results.find((r) => r.ip === "2001:db8::1");
+        assert.equal(v6hit.found, true);
+        assert.equal(v6hit.org, "Example Cloud");
+        const v6miss = out.results.find((r) => r.ip === "2606:4700::1");
+        assert.equal(v6miss.found, false);
+        // A valid-but-unmatched IPv6 is "unmatched", NOT "invalid".
+        assert.deepEqual(out.summary, { total: 3, matched: 2, unmatched: 1, invalid: 0 });
+    });
 });

package/dist/tools/generate-postmortem.d.ts

@@ -1,5 +1,7 @@
 import type { ConnectorRegistry } from "../connectors/registry.js";
 import { type RequestContext } from "../context.js";
+/** Test seam: reset the cached template (so tests can vary the env). */
+export declare function _resetPostmortemTemplateCache(): void;
 export declare const generatePostmortemDefinition: {
     name: "generate_postmortem";
     description: string;

package/dist/tools/generate-postmortem.js

@@ -7,9 +7,37 @@
 // The synthesizer is pure compute (see ./../postmortem/synthesizer);
 // this handler is just the orchestration: pull each upstream
 // primitive in parallel, hand the result to the synthesizer.
+import { readFileSync } from "node:fs";
 import { defaultContext } from "../context.js";
 import { validateDuration, validateServiceName, errorResponse } from "./validation.js";
 import { synthesizePostmortem, } from "../postmortem/synthesizer.js";
+// Optional operator-supplied report template (v3.3 candidate). Set
+// OMCP_POSTMORTEM_TEMPLATE to a file of `{{token}}` placeholders to override
+// the built-in layout; unset → the default report. Read once and cached; a
+// read error falls back to the default (logged once) rather than failing the
+// tool — a broken template must not break incident reporting.
+let _templateCache;
+function loadPostmortemTemplate(env = process.env) {
+    if (_templateCache !== undefined)
+        return _templateCache ?? undefined;
+    const path = env.OMCP_POSTMORTEM_TEMPLATE?.trim();
+    if (!path) {
+        _templateCache = null;
+        return undefined;
+    }
+    try {
+        _templateCache = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        console.error("OMCP_POSTMORTEM_TEMPLATE unreadable, using the built-in layout:", err instanceof Error ? err.message : err);
+        _templateCache = null;
+    }
+    return _templateCache ?? undefined;
+}
+/** Test seam: reset the cached template (so tests can vary the env). */
+export function _resetPostmortemTemplateCache() {
+    _templateCache = undefined;
+}
 export const generatePostmortemDefinition = {
     name: "generate_postmortem",
     description: [
@@ -59,17 +87,37 @@ export async function generatePostmortemHandler(registry, args, ctx = defaultCon
         blastRadius,
         traces,
         logHighlights,
+        template: loadPostmortemTemplate(),
     });
+    // Which primitives actually carried data. A post-mortem synthesised from
+    // ZERO signal still renders a full, authoritative-looking document — an
+    // on-call could paste it into a ticket as if it were a real finding. Make
+    // the coverage explicit so an empty report is self-labelling (the
+    // "absent ≠ zero" class, cf. #453/#462).
+    const coverage = {
+        anomalies: anomalies.length > 0,
+        traces: traces.length > 0,
+        topology: blastRadius.nodes.length > 0,
+        logs: logHighlights.length > 0,
+    };
+    const anySignal = Object.values(coverage).some(Boolean);
+    const reportWithCoverage = { ...report, coverage, builtFromSignal: anySignal };
     if ((args.format || "markdown").toLowerCase() === "json") {
         return {
-            content: [{ type: "text", text: JSON.stringify(report) }],
+            content: [{ type: "text", text: JSON.stringify(reportWithCoverage) }],
             isError: false,
         };
     }
-    // Default: return the markdown body. The structured sections live
-    // in JSON if the caller asked for them.
+    // Default: return the markdown body. When there was no signal at all, lead
+    // with a banner so the document isn't mistaken for a real finding.
+    const banner = anySignal
+        ? ""
+        : "> ⚠️ **No signal in this window.** This report was built from zero anomalies, traces, " +
+            "topology, and log highlights. Either the window was genuinely clean, or the relevant " +
+            "backends aren't configured/writing (anomaly-history sink, traces connector, topology " +
+            "connector). Verify coverage before relying on this.\n\n";
     return {
-        content: [{ type: "text", text: report.markdown }],
+        content: [{ type: "text", text: banner + report.markdown }],
         isError: false,
     };
 }

package/dist/tools/generate-postmortem.test.d.ts

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

package/dist/tools/generate-postmortem.test.js

@@ -0,0 +1,72 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { writeFileSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ConnectorRegistry } from "../connectors/registry.js";
+import { generatePostmortemHandler, _resetPostmortemTemplateCache } from "./generate-postmortem.js";
+// R5 — a post-mortem built from ZERO signal (no anomaly/traces/topology/log
+// backend) must label itself, not render as an authoritative finding.
+describe("generatePostmortemHandler — no-signal honesty (R5)", () => {
+    it("markdown leads with a 'no signal' banner when nothing was found", async () => {
+        const reg = new ConnectorRegistry(); // no backends → every primitive empty
+        const out = await generatePostmortemHandler(reg, { service: "ghost-service", duration: "1h" });
+        const md = out.content[0].text;
+        assert.match(md, /No signal in this window/i);
+        assert.match(md, /backends aren't configured/i);
+    });
+    it("json form carries explicit coverage flags + builtFromSignal=false", async () => {
+        const reg = new ConnectorRegistry();
+        const out = await generatePostmortemHandler(reg, { service: "ghost-service", duration: "1h", format: "json" });
+        const report = JSON.parse(out.content[0].text);
+        assert.equal(report.builtFromSignal, false);
+        assert.deepEqual(report.coverage, { anomalies: false, traces: false, topology: false, logs: false });
+    });
+});
+describe("generatePostmortemHandler — custom template via OMCP_POSTMORTEM_TEMPLATE (C3)", () => {
+    it("renders the operator's template when the env file is set; falls back when unset", async () => {
+        const dir = mkdtempSync(join(tmpdir(), "pm-tpl-"));
+        const file = join(dir, "tpl.md");
+        writeFileSync(file, "## Incident: {{service}} over {{window}}\n\n{{synopsis}}");
+        const prev = process.env.OMCP_POSTMORTEM_TEMPLATE;
+        try {
+            process.env.OMCP_POSTMORTEM_TEMPLATE = file;
+            _resetPostmortemTemplateCache();
+            const reg = new ConnectorRegistry();
+            const md = (await generatePostmortemHandler(reg, { service: "payment", duration: "2h" })).content[0].text;
+            // The custom template body is used (the no-signal honesty banner may
+            // still prepend it — that's deliberate and template-independent).
+            assert.match(md, /## Incident: payment over 2h/);
+            assert.ok(!md.includes("# Post-mortem —"), "custom template replaces the default layout");
+            // Unset → back to the built-in layout.
+            delete process.env.OMCP_POSTMORTEM_TEMPLATE;
+            _resetPostmortemTemplateCache();
+            const md2 = (await generatePostmortemHandler(reg, { service: "payment", duration: "2h" })).content[0].text;
+            assert.match(md2, /# Post-mortem — payment/);
+        }
+        finally {
+            if (prev === undefined)
+                delete process.env.OMCP_POSTMORTEM_TEMPLATE;
+            else
+                process.env.OMCP_POSTMORTEM_TEMPLATE = prev;
+            _resetPostmortemTemplateCache();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("an unreadable template path falls back to the default layout, doesn't throw", async () => {
+        const prev = process.env.OMCP_POSTMORTEM_TEMPLATE;
+        try {
+            process.env.OMCP_POSTMORTEM_TEMPLATE = "/nonexistent/nope.md";
+            _resetPostmortemTemplateCache();
+            const md = (await generatePostmortemHandler(new ConnectorRegistry(), { service: "x", duration: "1h" })).content[0].text;
+            assert.match(md, /# Post-mortem — x/);
+        }
+        finally {
+            if (prev === undefined)
+                delete process.env.OMCP_POSTMORTEM_TEMPLATE;
+            else
+                process.env.OMCP_POSTMORTEM_TEMPLATE = prev;
+            _resetPostmortemTemplateCache();
+        }
+    });
+});

package/dist/tools/handlers.test.js

@@ -152,6 +152,36 @@ describe("listServicesHandler", () => {
         const data = JSON.parse(result.content[0].text);
         assert.equal(data.total, 0);
     });
+    it("no backends configured → note distinguishes 'none configured' from 'zero services' (R5)", async () => {
+        const data = JSON.parse((await listServicesHandler(new ConnectorRegistry(), {})).content[0].text);
+        assert.equal(data.total, 0);
+        assert.match(data.note, /No observability backends are configured/i);
+    });
+    it("all sources fail discovery → note + not a silent 'zero services' (R5)", async () => {
+        const reg = createRegistryWithMocks([
+            createMockConnector({ name: "prom1", type: "prometheus", signalType: "metrics", listServices: async () => { throw new Error("down"); } }),
+        ]);
+        const data = JSON.parse((await listServicesHandler(reg, {})).content[0].text);
+        assert.equal(data.total, 0);
+        assert.match(data.note, /failed on all 1 configured source/i);
+    });
+    it("partial source failure → result is flagged partial with the failed source (R5)", async () => {
+        const reg = createRegistryWithMocks([
+            createMockConnector({ name: "prom1", type: "prometheus", signalType: "metrics", listServices: async () => { throw new Error("down"); } }),
+            createMockConnector({ name: "loki1", type: "loki", signalType: "logs", listServices: async () => [{ name: "order-service", source: "loki1", signalType: "logs" }] }),
+        ]);
+        const data = JSON.parse((await listServicesHandler(reg, {})).content[0].text);
+        assert.equal(data.total, 1);
+        assert.equal(data.partial, true);
+        assert.deepEqual(data.failedSources, ["prom1"]);
+    });
+});
+describe("listSourcesHandler — no-data honesty (R5)", () => {
+    it("no backends configured → explanatory note, not a bare empty list", async () => {
+        const data = JSON.parse((await listSourcesHandler(new ConnectorRegistry())).content[0].text);
+        assert.deepEqual(data.sources, []);
+        assert.match(data.note, /No observability backends are configured/i);
+    });
 });
 describe("detectAnomaliesHandler — fleet coverage (issue #453B)", () => {
     it("fleet scan includes log-only services and reports per-service coverage", async () => {

package/dist/tools/list-services.js

@@ -16,6 +16,10 @@ export async function listServicesHandler(registry, args, ctx = defaultContext()
     // Tenant-scoped: only consult sources the caller can see.
     const connectors = registry.getByTenant(ctx.tenant);
     const allServices = [];
+    // Track per-connector discovery failures so an empty result isn't silently
+    // partial — a down source must not make half the fleet vanish without a
+    // signal (the "absent ≠ zero" class, cf. #453).
+    const failedSources = [];
     for (const connector of connectors) {
         try {
             const services = await connector.listServices();
@@ -23,6 +27,7 @@ export async function listServicesHandler(registry, args, ctx = defaultContext()
         }
         catch (err) {
             console.error(`Failed to list services from ${connector.name}:`, err);
+            failedSources.push(connector.name);
         }
     }
     // Deduplicate by name, merge signal types. Carry per-service `labels`
@@ -54,11 +59,33 @@ export async function listServicesHandler(registry, args, ctx = defaultContext()
         const f = args.filter.toLowerCase();
         services = services.filter((s) => s.name.toLowerCase().includes(f));
     }
+    // An empty result is ambiguous — say *why* so an agent doesn't read it as
+    // "this environment has no services". Distinguish: no backends configured,
+    // discovery failed on some/all sources, or genuinely none discovered.
+    let note;
+    if (connectors.length === 0) {
+        note = "No observability backends are configured for this tenant — add one via the Sources tab or config/sources.yaml. This is not 'zero services'.";
+    }
+    else if (failedSources.length === connectors.length) {
+        note = `Service discovery failed on all ${connectors.length} configured source(s) (${failedSources.join(", ")}) — the empty result is an error, not 'zero services'. Check source health via list_sources.`;
+    }
+    else if (services.length === 0 && !args.filter) {
+        note = "No services discovered — the configured backend(s) returned none in this tenant.";
+    }
     return {
         content: [
             {
                 type: "text",
-                text: JSON.stringify({ services, total: services.length }, null, 2),
+                text: JSON.stringify({
+                    services,
+                    total: services.length,
+                    // Only present when some (but not all) sources failed — a partial
+                    // result the caller should know is incomplete.
+                    ...(failedSources.length > 0 && failedSources.length < connectors.length
+                        ? { partial: true, failedSources }
+                        : {}),
+                    ...(note ? { note } : {}),
+                }, null, 2),
             },
         ],
     };

package/dist/tools/list-sources.js

@@ -21,11 +21,17 @@ export async function listSourcesHandler(registry, ctx = defaultContext()) {
         status: healthResults[c.name]?.status || "unknown",
         latencyMs: healthResults[c.name]?.latencyMs,
     }));
+    // An empty list is ambiguous on its own — name the cause so an agent
+    // doesn't read it as a transient/permission blip (the "absent ≠ zero"
+    // class). When nothing is configured, say so explicitly.
+    const note = sources.length === 0
+        ? "No observability backends are configured for this tenant. Add one via the Sources tab or config/sources.yaml — this is 'none configured', not a query error."
+        : undefined;
     return {
         content: [
             {
                 type: "text",
-                text: JSON.stringify({ sources }, null, 2),
+                text: JSON.stringify({ sources, ...(note ? { note } : {}) }, null, 2),
             },
         ],
     };

package/dist/tools/query-logs.js

@@ -59,7 +59,7 @@ export async function queryLogsHandler(registry, args, ctx = defaultContext(), o
         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.");
+        return errorResponse("raw_query is disabled. The operator must enable the raw-query capability (OMCP_RAW_QUERY=on globally, or per-credential via OMCP_KEY_RAW_QUERY) 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.");

package/dist/tools/query-metrics.js

@@ -50,7 +50,7 @@ export async function queryMetricsHandler(registry, args, ctx = defaultContext()
         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.");
+        return errorResponse("raw_query is disabled. The operator must enable the raw-query capability (OMCP_RAW_QUERY=on globally, or per-credential via OMCP_KEY_RAW_QUERY) to run verbatim PromQL — it bypasses the curated metric surface, so it is off by default.");
     }
     if (!isRaw) {
         if (!args.service)

package/dist/tools/topology.js

@@ -171,6 +171,25 @@ export const getBlastRadiusDefinition = {
 };
 export async function getBlastRadiusHandler(registry, args, ctx = defaultContext()) {
     const agg = await aggregateTopology(registry, ctx.tenant);
+    // No topology-capable connector → the resource can't be found because there
+    // IS no graph, not because the name is wrong. Say so explicitly instead of a
+    // generic "not found" that misattributes the cause (the "absent ≠ zero"
+    // class, consistent with get_topology's empty-graph note).
+    if (agg.sources.length === 0) {
+        return {
+            isError: true,
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        resource: args.resource,
+                        hosts: [],
+                        note: "No topology-capable connector is configured, so there is no blast radius to compute. " +
+                            "Add a topology source (the built-in `kubernetes` connector, or aws/gcp/istio/linkerd/consul) " +
+                            "— a metrics/logs-only deployment has no topology graph. This is not 'resource not found'.",
+                    }, null, 2),
+                }],
+        };
+    }
     const found = resolveResource(args.resource, agg.resources);
     if ("error" in found) {
         return {