@thotischner/observability-mcp 1.8.1 → 3.0.1

package/dist/tools/get-anomaly-history.d.ts

@@ -0,0 +1,35 @@
+import type { ConnectorRegistry } from "../connectors/registry.js";
+import { type RequestContext } from "../context.js";
+export declare const getAnomalyHistoryDefinition: {
+    name: "get_anomaly_history";
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            service: {
+                type: string;
+                description: string;
+            };
+            duration: {
+                type: string;
+                description: string;
+            };
+            method: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function getAnomalyHistoryHandler(registry: ConnectorRegistry, args: {
+    service: string;
+    duration?: string;
+    method?: string;
+}, ctx?: RequestContext): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+}>;

package/dist/tools/get-anomaly-history.js

@@ -0,0 +1,126 @@
+// get_anomaly_history — Phase F15.
+//
+// Reads anomaly scores previously written to the TSDB by the
+// AnomalyHistory writer. The tool is a thin convenience wrapper: it
+// builds the PromQL query `omcp_anomaly_score{service="..."}` and
+// dispatches via any Prometheus-shaped connector in the caller's
+// tenant.
+//
+// Operators wire the round-trip themselves (Prometheus scrapes the
+// same remote-write endpoint the writer pushes to) — the gateway
+// doesn't need a direct TSDB query path because it already speaks
+// PromQL via the Prometheus connector.
+import { defaultContext } from "../context.js";
+import { validateDuration, validateServiceName, errorResponse } from "./validation.js";
+export const getAnomalyHistoryDefinition = {
+    name: "get_anomaly_history",
+    description: [
+        "Replay historical anomaly scores for a service from the TSDB the gateway writes to (omcp_anomaly_score series).",
+        "When to use: post-mortem reconstruction (what did the gateway see at 03:42?), trend analysis on detector noise, or pulling context for the LLM when an incident is reviewed after the fact.",
+        "Prerequisites: the operator must have OMCP_ANOMALY_HISTORY_REMOTE_WRITE configured AND a Prometheus connector pointed at the same TSDB so the round-trip closes.",
+        "Behavior: read-only. Returns the time-series of scores with per-method/severity labels. Empty result means either no anomalies in the window or history is disabled.",
+        "Related: `detect_anomalies` for the live scores; `query_metrics` if you want to write the PromQL by hand.",
+    ].join(" "),
+    inputSchema: {
+        type: "object",
+        properties: {
+            service: { type: "string", description: "Service name to filter on." },
+            duration: { type: "string", description: "Rolling window (e.g. '1h', '24h'). Default '1h'." },
+            method: { type: "string", description: "Filter by detector method ('mad', 'seasonality', 'correlator'). Optional." },
+        },
+        required: ["service"],
+    },
+};
+export async function getAnomalyHistoryHandler(registry, args, ctx = defaultContext()) {
+    const svcErr = validateServiceName(args.service);
+    if (svcErr)
+        return errorResponse(svcErr);
+    const duration = args.duration || "1h";
+    const durationErr = validateDuration(duration);
+    if (durationErr)
+        return errorResponse(durationErr);
+    // Pick any metrics connector. The operator is expected to have
+    // their TSDB scraped by Prometheus, so any metric source can serve
+    // the query. We don't try to auto-detect "the right source" — the
+    // query is global by metric name.
+    const candidates = registry
+        .getByTenant(ctx.tenant)
+        .filter((c) => typeof c.queryMetrics === "function");
+    if (candidates.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: "No metrics backend configured to query the TSDB. Configure a Prometheus source pointed at the same TSDB OMCP_ANOMALY_HISTORY_REMOTE_WRITE writes to.",
+                    }),
+                },
+            ],
+            isError: true,
+        };
+    }
+    // Build the PromQL. The recording metric `omcp_anomaly_score` is
+    // expected to exist; if the writer is disabled or never fired, the
+    // query just returns an empty series — that's a valid result.
+    const labelFilters = [`service="${escLabel(args.service)}"`];
+    if (args.method)
+        labelFilters.push(`method="${escLabel(args.method)}"`);
+    const metric = `omcp_anomaly_score{${labelFilters.join(",")}}`;
+    // Fan out across every metrics connector; first non-empty answer wins.
+    for (const c of candidates) {
+        if (!c.queryMetrics)
+            continue;
+        try {
+            const r = await c.queryMetrics({
+                service: args.service,
+                metric,
+                duration,
+            });
+            if (r && Array.isArray(r.values) && r.values.length > 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                service: args.service,
+                                duration,
+                                method: args.method,
+                                source: r.source,
+                                values: r.values,
+                                summary: r.summary,
+                                metric,
+                            }),
+                        },
+                    ],
+                    isError: false,
+                };
+            }
+        }
+        catch (err) {
+            console.warn("get_anomaly_history: %s threw: %s", c.name, err instanceof Error ? err.message : String(err));
+        }
+    }
+    // No connector returned data — either the metric doesn't exist or
+    // there were no anomalies in the window. Both are useful answers.
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    service: args.service,
+                    duration,
+                    method: args.method,
+                    values: [],
+                    summary: { count: 0 },
+                    metric,
+                    hint: "No anomaly history found. Either the window is clean, or OMCP_ANOMALY_HISTORY_REMOTE_WRITE was unset when the anomalies fired, or the configured Prometheus source isn't scraping the TSDB this writer pushes to.",
+                }),
+            },
+        ],
+        isError: false,
+    };
+}
+/** Escape a PromQL label value (backslash + double-quote). */
+function escLabel(v) {
+    return v.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}

package/dist/tools/get-service-health.d.ts

@@ -18,7 +18,7 @@ export declare const getServiceHealthDefinition: {
 };
 export declare function getServiceHealthHandler(registry: ConnectorRegistry, args: {
     service: string;
-}, _ctx?: RequestContext): Promise<{
+}, ctx?: RequestContext): Promise<{
     content: {
         type: "text";
         text: string;

package/dist/tools/get-service-health.js

@@ -20,9 +20,10 @@ export const getServiceHealthDefinition = {
         required: ["service"],
     },
 };
-export async function getServiceHealthHandler(registry, args, _ctx = defaultContext()) {
-    const metricsConnectors = registry.getBySignal("metrics");
-    const logConnectors = registry.getBySignal("logs");
+export async function getServiceHealthHandler(registry, args, ctx = defaultContext()) {
+    const tenantConnectors = registry.getByTenant(ctx.tenant);
+    const metricsConnectors = tenantConnectors.filter((c) => c.signalType === "metrics");
+    const logConnectors = tenantConnectors.filter((c) => c.signalType === "logs");
     // Gather metrics
     let cpu = 0, memory = 0, errorRate = 0, latencyP99 = 0;
     const anomalies = [];

package/dist/tools/list-services.d.ts

@@ -15,7 +15,7 @@ export declare const listServicesDefinition: {
 };
 export declare function listServicesHandler(registry: ConnectorRegistry, args: {
     filter?: string;
-}, _ctx?: RequestContext): Promise<{
+}, ctx?: RequestContext): Promise<{
     content: {
         type: "text";
         text: string;

package/dist/tools/list-services.js

@@ -12,8 +12,9 @@ export const listServicesDefinition = {
         },
     },
 };
-export async function listServicesHandler(registry, args, _ctx = defaultContext()) {
-    const connectors = registry.getAll();
+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 = [];
     for (const connector of connectors) {
         try {

package/dist/tools/list-sources.d.ts

@@ -8,7 +8,7 @@ export declare const listSourcesDefinition: {
         properties: {};
     };
 };
-export declare function listSourcesHandler(registry: ConnectorRegistry, _ctx?: RequestContext): Promise<{
+export declare function listSourcesHandler(registry: ConnectorRegistry, ctx?: RequestContext): Promise<{
     content: {
         type: "text";
         text: string;

package/dist/tools/list-sources.js

@@ -7,9 +7,13 @@ export const listSourcesDefinition = {
         properties: {},
     },
 };
-export async function listSourcesHandler(registry, _ctx = defaultContext()) {
+export async function listSourcesHandler(registry, ctx = defaultContext()) {
     const healthResults = await registry.healthCheckAll();
-    const connectors = registry.getAll();
+    // Tenant-scoped: caller only sees sources tagged with their tenant
+    // plus untagged (global) sources. Pre-E7 deployments (no tenant
+    // labels on any source) behave identically — every source is
+    // global and visible to every tenant.
+    const connectors = registry.getByTenant(ctx.tenant);
     const sources = connectors.map((c) => ({
         name: c.name,
         type: c.type,

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

@@ -36,7 +36,7 @@ export declare function queryLogsHandler(registry: ConnectorRegistry, args: {
     duration?: string;
     level?: string;
     limit?: number;
-}, _ctx?: RequestContext): Promise<{
+}, ctx?: RequestContext): Promise<{
     content: {
         type: "text";
         text: string;

package/dist/tools/query-logs.js

@@ -30,7 +30,7 @@ export const queryLogsDefinition = {
         required: ["service"],
     },
 };
-export async function queryLogsHandler(registry, args, _ctx = defaultContext()) {
+export async function queryLogsHandler(registry, args, ctx = defaultContext()) {
     const svcErr = validateServiceName(args.service);
     if (svcErr)
         return errorResponse(svcErr);
@@ -38,7 +38,7 @@ export async function queryLogsHandler(registry, args, _ctx = defaultContext())
     const durationErr = validateDuration(duration);
     if (durationErr)
         return errorResponse(durationErr);
-    const connectors = registry.getBySignal("logs");
+    const connectors = registry.getByTenant(ctx.tenant).filter((c) => c.signalType === "logs");
     if (connectors.length === 0) {
         return {
             content: [

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

@@ -36,7 +36,7 @@ export declare function queryMetricsHandler(registry: ConnectorRegistry, args: {
     duration?: string;
     source?: string;
     groupBy?: string;
-}, _ctx?: RequestContext): Promise<{
+}, ctx?: RequestContext): Promise<{
     content: {
         type: "text";
         text: string;

package/dist/tools/query-metrics.js

@@ -30,12 +30,12 @@ export const queryMetricsDefinition = {
         required: ["service", "metric"],
     },
 };
-export async function queryMetricsHandler(registry, args, _ctx = defaultContext()) {
+export async function queryMetricsHandler(registry, args, ctx = defaultContext()) {
     // 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 &&
+    if (ctx.allowedSources &&
         args.source &&
-        !_ctx.allowedSources.includes(args.source)) {
+        !ctx.allowedSources.includes(args.source)) {
         return errorResponse(`forbidden: source "${args.source}" is not in your allowed sources`);
     }
     const svcErr = validateServiceName(args.service);
@@ -51,12 +51,25 @@ export async function queryMetricsHandler(registry, args, _ctx = defaultContext(
     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).`);
     }
+    // Tenant-scoped resolution: an explicit `source` from the agent
+    // must belong to the caller's tenant (or be a global / untagged
+    // source) — cross-tenant sources resolve to undefined exactly like
+    // a missing source, preserving the no-existence-leak posture used
+    // elsewhere in the tenancy layer.
     const connectors = args.source
-        ? [registry.getByName(args.source)].filter(Boolean)
-        : registry.getBySignal("metrics");
+        ? [registry.getByNameForTenant(args.source, ctx.tenant)].filter(Boolean)
+        : registry.getByTenant(ctx.tenant).filter((c) => c.signalType === "metrics");
     if (connectors.length === 0) {
+        // Distinct messages but identical posture: the source-named branch
+        // could land here either because the source doesn't exist OR
+        // belongs to another tenant — both surface as "not found", same
+        // shape, no existence leak. The fan-out branch lands here only on
+        // an empty registry.
+        const msg = args.source
+            ? `Source "${args.source}" not found`
+            : "No metrics backends configured";
         return {
-            content: [{ type: "text", text: JSON.stringify({ error: "No metrics backends configured" }) }],
+            content: [{ type: "text", text: JSON.stringify({ error: msg }) }],
             isError: true,
         };
     }

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

@@ -0,0 +1,47 @@
+import type { ConnectorRegistry } from "../connectors/registry.js";
+import { type RequestContext } from "../context.js";
+export declare const queryTracesDefinition: {
+    name: "query_traces";
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            service: {
+                type: string;
+                description: string;
+            };
+            duration: {
+                type: string;
+                description: string;
+            };
+            filter: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+            errorsOnly: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function queryTracesHandler(registry: ConnectorRegistry, args: {
+    service: string;
+    duration?: string;
+    filter?: string;
+    limit?: number;
+    errorsOnly?: boolean;
+}, ctx?: RequestContext): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+}>;
+/** Pure percentile over a numeric array. Returns 0 for empty input. */
+export declare function percentile(values: number[], p: number): number;

package/dist/tools/query-traces.js

@@ -0,0 +1,145 @@
+// query_traces — Phase F13.
+//
+// Surfaces distributed traces from any connector that implements the
+// queryTraces capability. Fans out across every traces-signal
+// connector in the caller's tenant, merges the returned trace
+// summaries, and recomputes a global p50/p95 over the merged set
+// (rather than blindly averaging per-source summaries).
+//
+// Backend support today: a Tempo connector + a Jaeger shim ship as
+// filesystem plugins. Any connector that implements queryTraces
+// participates automatically — no changes needed in the tool layer
+// when a new backend lands.
+import { defaultContext } from "../context.js";
+import { validateDuration, validateServiceName, errorResponse } from "./validation.js";
+export const queryTracesDefinition = {
+    name: "query_traces",
+    description: [
+        "Query distributed traces for a service over a given timeframe.",
+        "Returns ranked trace summaries with duration, error status, and span count, plus a p50/p95 duration aggregate across the returned set.",
+        "When to use: investigating tail-latency outliers, walking call chains across services for a known time window, or pulling related traces for an anomaly the metric/log tools surfaced first.",
+        "Behavior: read-only; results may be capped via `limit` (default 50). `filter` accepts the backend's native query language (TraceQL on Tempo, tag query on Jaeger). When `errorsOnly=true`, only traces with at least one error span are returned.",
+        "Related: `query_metrics` for the per-service latency series; `get_blast_radius` for the topology a trace traverses.",
+    ].join(" "),
+    inputSchema: {
+        type: "object",
+        properties: {
+            service: { type: "string", description: "Service name (e.g. 'payment-service')" },
+            duration: { type: "string", description: "Rolling time window (e.g. '5m', '1h'). Default '15m'." },
+            filter: { type: "string", description: "Backend-native filter (TraceQL on Tempo, tag query on Jaeger). Optional." },
+            limit: { type: "number", description: "Soft cap on returned trace summaries. Default 50." },
+            errorsOnly: { type: "boolean", description: "If true, only traces with at least one error span." },
+        },
+        required: ["service"],
+    },
+};
+export async function queryTracesHandler(registry, args, ctx = defaultContext()) {
+    const svcErr = validateServiceName(args.service);
+    if (svcErr)
+        return errorResponse(svcErr);
+    const duration = args.duration || "15m";
+    const durationErr = validateDuration(duration);
+    if (durationErr)
+        return errorResponse(durationErr);
+    // signalType filter: traces-aware connectors should report "traces"
+    // (the new signal type) but we also accept any connector that
+    // declares queryTraces — back-compat for connectors that haven't
+    // updated their signalType yet.
+    const candidates = registry
+        .getByTenant(ctx.tenant)
+        .filter((c) => typeof c.queryTraces === "function");
+    if (candidates.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ error: "No trace backends configured" }),
+                },
+            ],
+            isError: true,
+        };
+    }
+    const results = [];
+    const errors = [];
+    for (const connector of candidates) {
+        if (!connector.queryTraces)
+            continue;
+        try {
+            const r = await connector.queryTraces({
+                service: args.service,
+                duration,
+                filter: args.filter,
+                limit: args.limit,
+                errorsOnly: args.errorsOnly,
+            });
+            results.push(r);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Trace query failed on ${connector.name}:`, msg);
+            errors.push(`${connector.name}: ${msg}`);
+        }
+    }
+    if (results.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: errors.length > 0 ? `Query failed: ${errors.join("; ")}` : "No traces returned",
+                        service: args.service,
+                        duration,
+                    }),
+                },
+            ],
+            isError: errors.length > 0,
+        };
+    }
+    // Merge: every source returns its own ranked set; we keep the union
+    // and recompute a global p50/p95 over the merged set so the summary
+    // reflects what the tool actually returned to the caller.
+    const merged = [];
+    for (const r of results)
+        merged.push(...r.traces);
+    // Sort hottest-first by duration, then truncate to the requested limit.
+    merged.sort((a, b) => b.durationMs - a.durationMs);
+    const limit = args.limit ?? 50;
+    const capped = merged.slice(0, limit);
+    const errorCount = capped.filter((t) => t.hasError).length;
+    const summary = {
+        total: capped.length,
+        errorCount,
+        p50DurationMs: percentile(capped.map((t) => t.durationMs), 0.5),
+        p95DurationMs: percentile(capped.map((t) => t.durationMs), 0.95),
+    };
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    service: args.service,
+                    duration,
+                    sources: results.map((r) => r.source),
+                    summary,
+                    traces: capped,
+                    errors: errors.length > 0 ? errors : undefined,
+                }),
+            },
+        ],
+        isError: false,
+    };
+}
+/** Pure percentile over a numeric array. Returns 0 for empty input. */
+export function percentile(values, p) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    // Linear interpolation between the two surrounding samples.
+    const rank = p * (sorted.length - 1);
+    const lo = Math.floor(rank);
+    const hi = Math.ceil(rank);
+    if (lo === hi)
+        return sorted[lo] ?? 0;
+    const frac = rank - lo;
+    return Math.round((sorted[lo] ?? 0) * (1 - frac) + (sorted[hi] ?? 0) * frac);
+}

package/dist/tools/query-traces.test.d.ts

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

package/dist/tools/query-traces.test.js

@@ -0,0 +1,110 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { queryTracesHandler, percentile } from "./query-traces.js";
+function span(traceId, durationMs, opts = {}) {
+    return {
+        traceId,
+        rootName: "GET /pay",
+        rootService: opts.service ?? "payment-service",
+        durationMs,
+        spanCount: 4,
+        hasError: opts.hasError ?? false,
+        startTs: "2026-06-06T00:00:00.000Z",
+    };
+}
+function fakeRegistry(connectors) {
+    return {
+        getByTenant: (_tenant) => connectors,
+    };
+}
+function parseResponse(r) {
+    return JSON.parse(r.content[0].text);
+}
+test("percentile: empty → 0; single value → that value; linear interpolation otherwise", () => {
+    assert.equal(percentile([], 0.5), 0);
+    assert.equal(percentile([10], 0.5), 10);
+    assert.equal(percentile([1, 2, 3, 4, 5], 0.5), 3);
+    // 95th of [1..20] sits between index 18 (19) and 19 (20)
+    const vs = Array.from({ length: 20 }, (_, i) => i + 1);
+    assert.ok(percentile(vs, 0.95) >= 19 && percentile(vs, 0.95) <= 20);
+});
+test("query_traces: rejects invalid service name", async () => {
+    const r = await queryTracesHandler(fakeRegistry([]), { service: "bad name with space" });
+    assert.equal(r.isError, true);
+});
+test("query_traces: rejects invalid duration", async () => {
+    const r = await queryTracesHandler(fakeRegistry([]), { service: "ok", duration: "bogus" });
+    assert.equal(r.isError, true);
+});
+test("query_traces: no trace backends configured → isError + clear message", async () => {
+    // Connectors without queryTraces are skipped.
+    const conn = { name: "prom", signalType: "metrics" };
+    const r = await queryTracesHandler(fakeRegistry([conn]), { service: "ok" });
+    assert.equal(r.isError, true);
+    assert.match(parseResponse(r).error, /No trace backends/);
+});
+test("query_traces: merges spans from every connector that returned, caps to limit, ranks by duration", async () => {
+    const tempo = {
+        name: "tempo",
+        signalType: "metrics",
+        queryTraces: async () => ({
+            source: "tempo",
+            service: "payment",
+            traces: [span("aaa", 100), span("bbb", 800), span("ccc", 300)],
+            summary: { total: 3, errorCount: 0, p50DurationMs: 300, p95DurationMs: 800 },
+        }),
+    };
+    const jaeger = {
+        name: "jaeger",
+        signalType: "metrics",
+        queryTraces: async () => ({
+            source: "jaeger",
+            service: "payment",
+            traces: [span("ddd", 500, { hasError: true }), span("eee", 200)],
+            summary: { total: 2, errorCount: 1, p50DurationMs: 350, p95DurationMs: 500 },
+        }),
+    };
+    const r = await queryTracesHandler(fakeRegistry([tempo, jaeger]), { service: "payment", limit: 4 });
+    const body = parseResponse(r);
+    assert.deepEqual(body.sources.sort(), ["jaeger", "tempo"]);
+    assert.equal(body.traces.length, 4, "limit honoured");
+    // Sorted hottest-first
+    assert.equal(body.traces[0].durationMs, 800);
+    assert.equal(body.traces[1].durationMs, 500);
+    assert.equal(body.summary.errorCount, 1);
+});
+test("query_traces: surfaces per-connector errors but still returns successful results", async () => {
+    const ok = {
+        name: "tempo",
+        signalType: "metrics",
+        queryTraces: async () => ({
+            source: "tempo",
+            service: "payment",
+            traces: [span("aaa", 50)],
+            summary: { total: 1, errorCount: 0, p50DurationMs: 50, p95DurationMs: 50 },
+        }),
+    };
+    const broken = {
+        name: "jaeger",
+        signalType: "metrics",
+        queryTraces: async () => {
+            throw new Error("upstream 503");
+        },
+    };
+    const r = await queryTracesHandler(fakeRegistry([ok, broken]), { service: "payment" });
+    const body = parseResponse(r);
+    assert.equal(body.errors.length, 1);
+    assert.equal(body.traces.length, 1);
+});
+test("query_traces: all backends fail → isError true + errors surfaced", async () => {
+    const broken = {
+        name: "tempo",
+        signalType: "metrics",
+        queryTraces: async () => {
+            throw new Error("upstream gone");
+        },
+    };
+    const r = await queryTracesHandler(fakeRegistry([broken]), { service: "payment" });
+    assert.equal(r.isError, true);
+    assert.match(parseResponse(r).error, /upstream gone/);
+});

package/dist/tools/registry-names.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Canonical list of MCP tool names exposed by createMcpServer().
+ *
+ * Used by:
+ *   - the Product validator (typo guard): a Product's `tools` allow-
+ *     list must reference names that actually register, otherwise a
+ *     bound credential opens an /mcp session with an empty tool set
+ *     and the agent silently fails.
+ *   - the keystone integration test in registry-names.test.ts that
+ *     reads index.ts and asserts the registerTool() call sites match
+ *     this list 1:1 — a missing entry or an extra one trips the test.
+ *
+ * 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 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
+ *  operator-facing taxonomy stable even when tool descriptions evolve. */
+export type ToolCategory = "discovery" | "query" | "diagnose" | "topology";
+export interface ToolRegistryEntry {
+    name: RegisteredToolName;
+    category: ToolCategory;
+    /** One-liner — what the tool does, no fluff. The full multi-paragraph
+     *  description lives in createMcpServer's registerTool() call; this
+     *  is the catalogue summary the picker shows alongside the name. */
+    summary: string;
+}
+export declare const REGISTERED_TOOLS: readonly ToolRegistryEntry[];
+/** Validate a candidate Product tools[] array. Returns the unknown
+ *  names (empty array = all OK). Pure helper — the caller decides
+ *  how to surface the rejection (the API handler emits a 422 with a
+ *  hint of valid names; the YAML loader could decide to warn). */
+export declare function unknownToolNames(tools: readonly string[]): string[];