@thotischner/observability-mcp 1.5.1 → 1.7.0

package/dist/index.js

@@ -8,7 +8,9 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { loadConfig, saveConfig, DEFAULT_HEALTH_THRESHOLDS, DEFAULT_SETTINGS } from "./config/loader.js";
 import { ConnectorRegistry, getSupportedTypes } from "./connectors/registry.js";
+import { isTopologyProvider } from "./connectors/interface.js";
 import { defaultContext, principalContext } from "./context.js";
+import { enforceEntitledAccess, enterpriseGateStatus, enterpriseGateInfo, enterprisePolicyView, enterpriseCatalogView, enterpriseAuditTail, authorizeAdmin, updateRbacPolicy, updateCatalog, } from "./enterprise-gate.js";
 import { loadCredentials, credentialsConfigured, extractToken, resolveToken, } from "./auth/credentials.js";
 import { getPluginLoader } from "./connectors/loader.js";
 import { resolveHubCatalogUrl, describeInstalled, mergeCatalog, fetchHubCatalog, } from "./connectors/hub.js";
@@ -22,6 +24,7 @@ import { queryMetricsHandler } from "./tools/query-metrics.js";
 import { queryLogsHandler } from "./tools/query-logs.js";
 import { getServiceHealthHandler, setHealthThresholds } from "./tools/get-service-health.js";
 import { detectAnomaliesHandler } from "./tools/detect-anomalies.js";
+import { getTopologyHandler, getBlastRadiusHandler } from "./tools/topology.js";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { readFileSync, writeFileSync, mkdtempSync, rmSync } from "node:fs";
@@ -121,7 +124,10 @@ async function main() {
             "When to use: call this first to learn which source names exist and are healthy before passing `source` to other tools, or to debug why a query returns no data.",
             "Behavior: read-only, no side effects. Returns one entry per source with its name, type, configured URL, signal types (metrics/logs), and a live up/down status. Never throws for an unreachable backend — the backend is reported as down instead.",
             "Related: use `list_services` to see what is monitored within these sources.",
-        ].join(" "), {}, async () => withToolMetrics("list_sources", () => listSourcesHandler(registry, ctx)));
+        ].join(" "), {}, async () => {
+            await enforceEntitledAccess(ctx, { tool: "list_sources" });
+            return withToolMetrics("list_sources", () => listSourcesHandler(registry, ctx));
+        });
         mcpServer.tool("list_services", [
             "Discover the service names that can be queried, aggregated across every connected backend.",
             "When to use: call this before `query_metrics`, `query_logs`, or `get_service_health` to obtain the exact, case-sensitive service name those tools require.",
@@ -132,7 +138,10 @@ async function main() {
                 .string()
                 .optional()
                 .describe("Optional case-insensitive substring to narrow the result to matching service names (e.g. 'payment'). Omit to list every discovered service."),
-        }, async (args) => withToolMetrics("list_services", () => listServicesHandler(registry, args, ctx)));
+        }, async (args) => {
+            await enforceEntitledAccess(ctx, { tool: "list_services" });
+            return withToolMetrics("list_services", () => listServicesHandler(registry, args, ctx));
+        });
         const metricsList = getAvailableMetricNames(registry);
         const metricNames = registry.getBySignal("metrics").flatMap(c => c.getMetrics().map(m => m.name));
         const uniqueNames = [...new Set(metricNames)];
@@ -161,7 +170,10 @@ 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."),
-        }, async (args) => withToolMetrics("query_metrics", () => queryMetricsHandler(registry, args, ctx)));
+        }, async (args) => {
+            await enforceEntitledAccess(ctx, { tool: "query_metrics", source: args?.source, service: args?.service });
+            return withToolMetrics("query_metrics", () => queryMetricsHandler(registry, args, ctx));
+        });
         mcpServer.tool("query_logs", [
             "Fetch recent log entries for ONE service over a look-back window, with a pre-computed summary (error/warning counts and the most frequent error patterns).",
             "When to use: to inspect what a service actually logged, or to investigate an error spike surfaced by `detect_anomalies` / `get_service_health`. For numeric metrics use `query_metrics` instead.",
@@ -189,7 +201,10 @@ async function main() {
                 .positive()
                 .optional()
                 .describe("Optional. Maximum number of log entries to return (most recent first). Default: 100."),
-        }, async (args) => withToolMetrics("query_logs", () => queryLogsHandler(registry, args, ctx)));
+        }, async (args) => {
+            await enforceEntitledAccess(ctx, { tool: "query_logs", source: args?.source, service: args?.service });
+            return withToolMetrics("query_logs", () => queryLogsHandler(registry, args, ctx));
+        });
         mcpServer.tool("get_service_health", [
             "Produce a single aggregated health verdict for ONE service by combining its metrics and logs.",
             "When to use: the fastest way to answer 'is this service healthy right now and why?'. Use `query_metrics`/`query_logs` to drill into the underlying numbers, or `detect_anomalies` to scan many services at once.",
@@ -199,7 +214,10 @@ async function main() {
             service: z
                 .string()
                 .describe("Required. Exact, case-sensitive service name exactly as returned by `list_services` (e.g. 'payment-service')."),
-        }, async (args) => withToolMetrics("get_service_health", () => getServiceHealthHandler(registry, args, ctx)));
+        }, async (args) => {
+            await enforceEntitledAccess(ctx, { tool: "get_service_health", service: args?.service });
+            return withToolMetrics("get_service_health", () => getServiceHealthHandler(registry, args, ctx));
+        });
         mcpServer.tool("detect_anomalies", [
             "Scan one or all monitored services for abnormal behavior and return the findings ranked by severity.",
             "When to use: the entry point for 'is anything wrong anywhere?' triage. Once a service is flagged, follow up with `get_service_health` for the verdict or `query_metrics`/`query_logs` for the raw evidence.",
@@ -218,7 +236,52 @@ async function main() {
                 .enum(["low", "medium", "high"])
                 .optional()
                 .describe("Optional. Detection threshold: 'low' flags only strong deviations (>3σ), 'medium' is balanced (>2σ), 'high' is most sensitive and noisier (>1.5σ). Default: 'medium'."),
-        }, async (args) => withToolMetrics("detect_anomalies", () => detectAnomaliesHandler(registry, args, ctx)));
+        }, async (args) => {
+            await enforceEntitledAccess(ctx, { tool: "detect_anomalies", source: args?.source, service: args?.service });
+            return withToolMetrics("detect_anomalies", () => detectAnomaliesHandler(registry, args, ctx));
+        });
+        mcpServer.tool("get_topology", [
+            "Return the infrastructure topology graph (Resources and Edges) from every topology-capable connector.",
+            "When to use: when an agent needs to reason about which workload runs on which host, who owns whom, or which scope (namespace/project/folder) a resource belongs to. Pair with `get_blast_radius` for shared-host RCA.",
+            "Behavior: read-only, no side effects. Returns `{ sources, resources, edges, total, truncated }`. Filters compose: `source` to one connector, `kind` to one resource type (e.g. 'pod', 'node', 'deployment'), `scope` to members of a namespace/folder/project. Output is capped by `limit` (default 500, max 5000) and edges referencing dropped resources are removed.",
+            "Related: `get_blast_radius` to evaluate the impact of a host failure; `list_sources` to discover topology-capable connectors.",
+        ].join(" "), {
+            source: z
+                .string()
+                .optional()
+                .describe("Optional. Restrict the graph to one topology connector by source name (see `list_sources`). Default: merge across all connectors."),
+            kind: z
+                .string()
+                .optional()
+                .describe("Optional. Restrict to resources of one kind. Common values for Kubernetes: 'pod', 'node', 'deployment', 'replicaset', 'namespace'. Other connectors may emit different kinds (e.g. 'vm', 'hypervisor', 'volume'). Default: all kinds."),
+            scope: z
+                .string()
+                .optional()
+                .describe("Optional. Restrict to resources contained in a scope (anything pointed to by `IN_NAMESPACE` edges). Pass the scope's resource id (e.g. 'k8s:namespace:default') or its name (e.g. 'default'). Default: no scope filter."),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(5000)
+                .optional()
+                .describe("Optional. Maximum resources to return; edges are trimmed to the kept set. Default 500, max 5000."),
+        }, async (args) => {
+            await enforceEntitledAccess(ctx, { tool: "get_topology", source: args?.source });
+            return withToolMetrics("get_topology", () => getTopologyHandler(registry, args, ctx));
+        });
+        mcpServer.tool("get_blast_radius", [
+            "Given a resource, return who else fails if its underlying host(s) fail.",
+            "When to use: cross-cutting RCA — when several services degrade together and you suspect a shared host. Works for any RUNS_ON relationship: pod→node, vm→hypervisor, container→host.",
+            "Behavior: read-only, no side effects. Resolves `resource` to a Resource (accepts canonical id, exact name, or unique substring), determines its host(s) via RUNS_ON, then lists every other resource that runs on those hosts, bucketed by ownership root (the terminal `OWNED_BY` target — e.g. the Deployment, not the ReplicaSet). If the target is itself a host, its tenants are reported. Returns a structured error if the resource is ambiguous or unknown.",
+            "Related: `get_topology` for the full graph; `get_service_health` for the per-service verdict on each co-tenant.",
+        ].join(" "), {
+            resource: z
+                .string()
+                .describe("Required. Resource to evaluate. Accepts the canonical id (e.g. 'k8s:pod:default/checkout-7f89d'), the exact resource name (e.g. 'checkout-7f89d'), or a unique substring of either."),
+        }, async (args) => {
+            await enforceEntitledAccess(ctx, { tool: "get_blast_radius" });
+            return withToolMetrics("get_blast_radius", () => getBlastRadiusHandler(registry, args, ctx));
+        });
         return mcpServer;
     }
     // --- HTTP server ---
@@ -313,6 +376,7 @@ async function main() {
         res.json({
             name: "observability-mcp",
             version: SERVER_VERSION,
+            enterpriseGate: await enterpriseGateStatus(),
             mcpProtocolVersion: "2025-03-26",
             build: {
                 commit: process.env.GIT_COMMIT || null,
@@ -336,6 +400,58 @@ async function main() {
     app.get("/api/connectors", (_req, res) => {
         res.json({ connectors: describeInstalled(getPluginLoader().list()) });
     });
+    // --- Enterprise console (read-only introspection) -------------------
+    // Drives the management UI's Enterprise page. Read-only in this phase;
+    // never exposes the entitlement token or any key. Same trusted-local
+    // management plane as the other /api/* endpoints (see auth-and-tls).
+    app.get("/api/enterprise/status", async (_req, res) => {
+        try {
+            res.json(await enterpriseGateInfo());
+        }
+        catch (e) {
+            res.status(500).json({ error: String(e) });
+        }
+    });
+    app.get("/api/enterprise/policy", (_req, res) => {
+        res.json(enterprisePolicyView());
+    });
+    app.get("/api/enterprise/catalog", (_req, res) => {
+        res.json(enterpriseCatalogView());
+    });
+    app.get("/api/enterprise/audit", async (req, res) => {
+        const limit = Math.min(Number(req.query.limit) || 50, 500);
+        try {
+            res.json(await enterpriseAuditTail(limit));
+        }
+        catch (e) {
+            res.status(500).json({ error: String(e) });
+        }
+    });
+    // Phase 2: edit the RBAC policy. NOT on the open local plane — requires
+    // an API-key principal the CURRENT policy grants `enterprise:admin`.
+    app.put("/api/enterprise/policy", async (req, res) => {
+        const cred = resolveToken(extractToken(req.headers), loadCredentials());
+        const principal = cred ? cred.name : null;
+        const authz = await authorizeAdmin(principal);
+        if (!authz.ok)
+            return res.status(authz.status).json({ error: authz.error });
+        const result = await updateRbacPolicy(principal, req.body);
+        if (!result.ok)
+            return res.status(result.status).json({ error: result.error });
+        res.json({ ok: true });
+    });
+    // Phase 3: edit the product catalog. Same admin model as the RBAC write.
+    app.put("/api/enterprise/catalog", async (req, res) => {
+        const cred = resolveToken(extractToken(req.headers), loadCredentials());
+        const principal = cred ? cred.name : null;
+        const authz = await authorizeAdmin(principal);
+        if (!authz.ok)
+            return res.status(authz.status).json({ error: authz.error });
+        const result = await updateCatalog(principal, req.body);
+        if (!result.ok)
+            return res.status(result.status).json({ error: result.error });
+        res.json({ ok: true });
+    });
     // Server-side proxy of the connector hub catalog (so the browser
     // needn't reach the hub directly — works behind a proxy / against a
     // mirror via HUB_CATALOG_URL). Installed status merged in.
@@ -619,6 +735,36 @@ async function main() {
             res.status(500).json({ error: "Failed to get health data" });
         }
     });
+    // --- Topology API ---
+    // Returns the union of topology snapshots across all topology-capable
+    // connectors (today only "kubernetes"). One JSON document so the UI can
+    // render summary + grouped views without N round-trips.
+    app.get("/api/topology", async (_req, res) => {
+        try {
+            const sources = [];
+            const allResources = [];
+            const allEdges = [];
+            for (const c of registry.getAll()) {
+                if (!isTopologyProvider(c))
+                    continue;
+                const snap = await c.getTopologySnapshot();
+                sources.push({
+                    source: snap.source,
+                    type: c.type,
+                    revision: snap.revision,
+                    resources: snap.resources.length,
+                    edges: snap.edges.length,
+                });
+                allResources.push(...snap.resources);
+                allEdges.push(...snap.edges);
+            }
+            res.json({ sources, resources: allResources, edges: allEdges });
+        }
+        catch (err) {
+            console.error("topology endpoint failed:", err);
+            res.status(500).json({ error: "Failed to read topology" });
+        }
+    });
     // --- Settings API ---
     // Get general settings
     app.get("/api/settings", (_req, res) => {

package/dist/sdk/index.d.ts

@@ -1,7 +1,7 @@
 export type { ObservabilityConnector } from "../connectors/interface.js";
 export { manifestSchema } from "./manifest-schema.js";
 export type { ValidatedConnectorManifest } from "./manifest-schema.js";
-export type { SignalType, SourceConfig, SourceAuth, SourceTls, ConnectorHealth, ServiceInfo, MetricInfo, MetricQuery, MetricResult, MetricSummary, DataPoint, LogQuery, LogResult, LogEntry, LogSummary, MetricDefinition, } from "../types.js";
+export type { SignalType, SourceConfig, SourceAuth, SourceTls, ConnectorHealth, ServiceInfo, MetricInfo, MetricQuery, MetricResult, MetricSummary, DataPoint, LogQuery, LogResult, LogEntry, LogSummary, MetricDefinition, Resource, Edge, TopologySnapshot, TopologyChangeEvent, TopologyChangeListener, } from "../types.js";
 /**
  * Manifest shape declared in a plugin's `manifest.json`. The server
  * validates plugin manifests against this at load time.
@@ -18,7 +18,7 @@ export interface ConnectorManifest {
     /** Semver of this connector build. */
     version: string;
     description: string;
-    signalTypes: Array<"metrics" | "logs" | "traces">;
+    signalTypes: Array<"metrics" | "logs" | "traces" | "topology">;
     homepage?: string;
     license?: string;
     logo?: string;

package/dist/sdk/manifest-schema.d.ts

@@ -9,6 +9,7 @@ export declare const manifestSchema: z.ZodObject<{
         metrics: "metrics";
         logs: "logs";
         traces: "traces";
+        topology: "topology";
     }>>;
     homepage: z.ZodOptional<z.ZodString>;
     license: z.ZodOptional<z.ZodString>;

package/dist/sdk/manifest-schema.js

@@ -15,7 +15,7 @@ export const manifestSchema = z.object({
         message: "version must be semver",
     }),
     description: z.string().min(1),
-    signalTypes: z.array(z.enum(["metrics", "logs", "traces"])).min(1),
+    signalTypes: z.array(z.enum(["metrics", "logs", "traces", "topology"])).min(1),
     homepage: z.string().url().optional(),
     license: z.string().optional(),
     logo: z.string().optional(),

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

@@ -1,6 +1,6 @@
 import { defaultContext } from "../context.js";
 import { calculateHealthScore } from "../analysis/health.js";
-import { detectRecentAnomaly } from "../analysis/anomaly.js";
+import { detectRobustAnomaly, classifyMetric } from "../analysis/anomaly.js";
 import { sanitizeForLog } from "../util/sanitize.js";
 let _thresholds = null;
 export function setHealthThresholds(t) {
@@ -94,17 +94,20 @@ export async function getServiceHealthHandler(registry, args, _ctx = defaultCont
     };
 }
 function checkAnomaly(values, metric, service, source, anomalies) {
-    const result = detectRecentAnomaly(values);
+    // Robust, metric-type-aware detector (same path as detect_anomalies):
+    // latency/error_rate/saturation are one-sided, so a *decrease* (e.g.
+    // latency dropping) is correctly NOT flagged as an anomaly.
+    const result = detectRobustAnomaly(values, { metricKind: classifyMetric(metric) });
     if (result.isAnomaly) {
-        const deviationPercent = result.baselineAvg === 0
+        const deviationPercent = result.baselineValue === 0
             ? 100
-            : Math.round(((result.recentAvg - result.baselineAvg) / result.baselineAvg) * 100);
+            : Math.round(((result.recentValue - result.baselineValue) / result.baselineValue) * 100);
         anomalies.push({
             metric,
-            severity: Math.abs(result.zScore) >= 3 ? "high" : Math.abs(result.zScore) >= 2 ? "medium" : "low",
-            description: `${metric} is ${result.zScore.toFixed(1)}σ ${result.zScore > 0 ? "above" : "below"} baseline (${result.baselineAvg.toFixed(2)} → ${result.recentAvg.toFixed(2)})`,
-            currentValue: result.recentAvg,
-            baselineValue: result.baselineAvg,
+            severity: Math.abs(result.score) >= 6 ? "high" : Math.abs(result.score) >= 4 ? "medium" : "low",
+            description: `${metric}: ${result.reason}`,
+            currentValue: result.recentValue,
+            baselineValue: result.baselineValue,
             deviationPercent,
             source,
             service,

package/dist/tools/handlers.test.js

@@ -4,6 +4,7 @@ import { ConnectorRegistry } from "../connectors/registry.js";
 import { listSourcesHandler } from "./list-sources.js";
 import { listServicesHandler } from "./list-services.js";
 import { detectAnomaliesHandler } from "./detect-anomalies.js";
+import { getServiceHealthHandler } from "./get-service-health.js";
 // --- Mock Connector ---
 function createMockConnector(overrides) {
     return {
@@ -209,3 +210,33 @@ describe("detectAnomaliesHandler — A5 memory/OOM coverage", () => {
         assert.equal(data.anomalies.length, 0);
     });
 });
+describe("getServiceHealthHandler — one-sided latency (regression)", () => {
+    const series = (vals) => ({
+        source: "prom1", service: "payment-service", metric: "x", unit: "",
+        values: vals.map((v, i) => ({ timestamp: new Date(Date.now() - (vals.length - i) * 9000).toISOString(), value: v })),
+        summary: { current: vals[vals.length - 1], average: vals[0], min: Math.min(...vals), max: Math.max(...vals), trend: "falling" },
+    });
+    it("a DECREASING latency_p99 is NOT flagged as an anomaly", async () => {
+        const reg = new ConnectorRegistry();
+        const mock = {
+            connect: async () => { }, disconnect: async () => { },
+            healthCheck: async () => ({ status: "up", latencyMs: 1 }),
+            getDefaultMetrics: () => [], getMetrics: () => [],
+            listServices: async () => [{ name: "payment-service", source: "prom1", signalType: "metrics" }],
+            name: "prom1", type: "prometheus", signalType: "metrics",
+            queryMetrics: async ({ metric }) => {
+                if (metric === "latency_p99")
+                    return series(Array.from({ length: 30 }, (_, i) => 1.0 - i * 0.025)); // 1.0 → 0.275, strictly down
+                if (metric === "cpu")
+                    return series(Array.from({ length: 30 }, () => 20 + (Math.random() < 0 ? 1 : 0)));
+                return series(Array.from({ length: 30 }, () => 0.01)); // error_rate flat
+            },
+        };
+        reg.connectors.set("prom1", mock);
+        reg.sourceConfigs.set("prom1", { name: "prom1", type: "prometheus", url: "http://m", enabled: true });
+        const result = await getServiceHealthHandler(reg, { service: "payment-service" });
+        const data = JSON.parse(result.content[0].text);
+        const latAnom = (data.anomalies || []).find((a) => a.metric === "latency_p99");
+        assert.equal(latAnom, undefined, `latency dropping must not be an anomaly, got: ${JSON.stringify(latAnom)}`);
+    });
+});

package/dist/tools/topology.d.ts

@@ -0,0 +1,64 @@
+import type { ConnectorRegistry } from "../connectors/registry.js";
+import type { Resource, Edge } from "../types.js";
+import { type RequestContext } from "../context.js";
+interface AggregatedTopology {
+    sources: Array<{
+        source: string;
+        type: string;
+        revision: number;
+        resources: number;
+        edges: number;
+    }>;
+    resources: Resource[];
+    edges: Edge[];
+}
+export declare function aggregateTopology(registry: ConnectorRegistry): Promise<AggregatedTopology>;
+/**
+ * Resolve a caller-supplied identifier to a Resource. Accepts:
+ *   - exact canonical id (e.g. "k8s:pod:default/checkout-7f89d")
+ *   - exact resource name (e.g. "checkout-7f89d")
+ *   - case-insensitive substring of name (only used if uniquely matching)
+ *
+ * Stays generic — no knowledge of kind-specific id grammars.
+ */
+export declare function resolveResource(query: string, resources: Resource[]): Resource | {
+    error: string;
+    candidates?: string[];
+};
+export declare const getTopologyDefinition: {
+    name: "get_topology";
+    description: string;
+};
+export interface GetTopologyArgs {
+    source?: string;
+    kind?: string;
+    scope?: string;
+    limit?: number;
+}
+export declare function getTopologyHandler(registry: ConnectorRegistry, args?: GetTopologyArgs, _ctx?: RequestContext): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare const getBlastRadiusDefinition: {
+    name: "get_blast_radius";
+    description: string;
+};
+export interface GetBlastRadiusArgs {
+    resource: string;
+}
+export declare function getBlastRadiusHandler(registry: ConnectorRegistry, args: GetBlastRadiusArgs, _ctx?: RequestContext): Promise<{
+    isError: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: undefined;
+}>;
+export {};

package/dist/tools/topology.js

@@ -0,0 +1,233 @@
+// MCP tools that expose the infrastructure topology graph to agents.
+//
+// Two tools live here:
+//   - `get_topology`     — returns the merged resource/edge graph across
+//                          every topology-capable connector, optionally
+//                          filtered by source/kind/scope. Useful as a
+//                          starting point for any cross-cutting question.
+//   - `get_blast_radius` — given a resource, returns who else is co-tenant
+//                          on the same host(s). The canonical "if this
+//                          host fails, who else fails?" question.
+//
+// Both stay generic — they pivot on the `RUNS_ON` and `OWNED_BY` relations
+// rather than any specific kind. Adding a vCenter/NetBox/AWS topology
+// connector later requires zero changes here.
+import { isTopologyProvider } from "../connectors/interface.js";
+import { defaultContext } from "../context.js";
+export async function aggregateTopology(registry) {
+    const sources = [];
+    const resources = [];
+    const edges = [];
+    for (const c of registry.getAll()) {
+        if (!isTopologyProvider(c))
+            continue;
+        try {
+            const snap = await c.getTopologySnapshot();
+            sources.push({
+                source: snap.source,
+                type: c.type,
+                revision: snap.revision,
+                resources: snap.resources.length,
+                edges: snap.edges.length,
+            });
+            resources.push(...snap.resources);
+            edges.push(...snap.edges);
+        }
+        catch {
+            // A misbehaving connector must not poison the agent's view of the graph.
+        }
+    }
+    return { sources, resources, edges };
+}
+/**
+ * Resolve a caller-supplied identifier to a Resource. Accepts:
+ *   - exact canonical id (e.g. "k8s:pod:default/checkout-7f89d")
+ *   - exact resource name (e.g. "checkout-7f89d")
+ *   - case-insensitive substring of name (only used if uniquely matching)
+ *
+ * Stays generic — no knowledge of kind-specific id grammars.
+ */
+export function resolveResource(query, resources) {
+    if (!query)
+        return { error: "Missing resource query" };
+    const exactId = resources.find((r) => r.id === query);
+    if (exactId)
+        return exactId;
+    const exactName = resources.filter((r) => r.name === query);
+    if (exactName.length === 1)
+        return exactName[0];
+    if (exactName.length > 1) {
+        return {
+            error: `Name '${query}' is ambiguous across ${exactName.length} resources; pass the full id`,
+            candidates: exactName.map((r) => r.id),
+        };
+    }
+    const q = query.toLowerCase();
+    const fuzzy = resources.filter((r) => r.name.toLowerCase().includes(q) || r.id.toLowerCase().includes(q));
+    if (fuzzy.length === 1)
+        return fuzzy[0];
+    if (fuzzy.length > 1) {
+        return {
+            error: `Query '${query}' matched ${fuzzy.length} resources; pass the full id`,
+            candidates: fuzzy.slice(0, 25).map((r) => r.id),
+        };
+    }
+    return { error: `No resource found matching '${query}'` };
+}
+// --- get_topology ------------------------------------------------------
+export const getTopologyDefinition = {
+    name: "get_topology",
+    description: "Return the infrastructure topology graph as Resources and Edges. Use this when an agent needs to reason about which workload runs where, who owns whom, or which scope (namespace/project/folder) a resource belongs to.",
+};
+export async function getTopologyHandler(registry, args = {}, _ctx = defaultContext()) {
+    const agg = await aggregateTopology(registry);
+    // Filtering — all optional. Filters compose conjunctively.
+    let resources = agg.resources;
+    let edges = agg.edges;
+    if (args.source) {
+        resources = resources.filter((r) => r.source === args.source);
+        edges = edges.filter((e) => e.source === args.source);
+    }
+    if (args.kind) {
+        resources = resources.filter((r) => r.kind === args.kind);
+    }
+    if (args.scope) {
+        // Match either by scope resource id (e.g. "k8s:namespace:default") or by name (e.g. "default").
+        const inScope = new Set();
+        for (const e of agg.edges) {
+            if (e.relation !== "IN_NAMESPACE")
+                continue;
+            const target = agg.resources.find((r) => r.id === e.to);
+            if (!target)
+                continue;
+            if (target.id === args.scope || target.name === args.scope)
+                inScope.add(e.from);
+        }
+        resources = resources.filter((r) => inScope.has(r.id));
+    }
+    // Edges must still reference resources that survived filtering.
+    const keepIds = new Set(resources.map((r) => r.id));
+    edges = edges.filter((e) => keepIds.has(e.from) && keepIds.has(e.to));
+    // Soft truncation so an agent can't accidentally pull a 10k-node graph
+    // into context — defaults are generous but capped.
+    const limit = Math.min(Math.max(args.limit ?? 500, 1), 5000);
+    const truncated = resources.length > limit;
+    if (truncated) {
+        resources = resources.slice(0, limit);
+        const keep2 = new Set(resources.map((r) => r.id));
+        edges = edges.filter((e) => keep2.has(e.from) && keep2.has(e.to));
+    }
+    const payload = {
+        sources: agg.sources,
+        resources,
+        edges,
+        total: { resources: agg.resources.length, edges: agg.edges.length },
+        truncated,
+    };
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+    };
+}
+// --- get_blast_radius --------------------------------------------------
+export const getBlastRadiusDefinition = {
+    name: "get_blast_radius",
+    description: "Given a resource, return the impact set if its underlying host(s) fail. Pivots on the generic RUNS_ON relation, so it works for pod→node, vm→hypervisor, container→host alike. Use this for cross-cutting RCA when several services degrade together.",
+};
+export async function getBlastRadiusHandler(registry, args, _ctx = defaultContext()) {
+    const agg = await aggregateTopology(registry);
+    const found = resolveResource(args.resource, agg.resources);
+    if ("error" in found) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: JSON.stringify(found, null, 2) }],
+        };
+    }
+    // Index edges once.
+    const byId = new Map(agg.resources.map((r) => [r.id, r]));
+    const runsOnOut = new Map(); // child → host
+    const runsOnIn = new Map(); // host → children
+    const ownedByOut = new Map(); // child → owner
+    for (const e of agg.edges) {
+        if (e.relation === "RUNS_ON") {
+            runsOnOut.set(e.from, e.to);
+            const s = runsOnIn.get(e.to) || new Set();
+            s.add(e.from);
+            runsOnIn.set(e.to, s);
+        }
+        else if (e.relation === "OWNED_BY") {
+            if (!ownedByOut.has(e.from))
+                ownedByOut.set(e.from, e.to);
+        }
+    }
+    function ownershipRoot(id) {
+        let cur = id;
+        for (let i = 0; i < 16; i++) {
+            const next = ownedByOut.get(cur);
+            if (!next || next === cur)
+                return cur;
+            cur = next;
+        }
+        return cur;
+    }
+    // Determine which hosts the target depends on. If the resource is itself
+    // a host (incoming RUNS_ON exists), the host is the resource itself.
+    const hosts = [];
+    if (runsOnIn.has(found.id)) {
+        hosts.push(found.id);
+    }
+    else if (runsOnOut.has(found.id)) {
+        hosts.push(runsOnOut.get(found.id));
+    }
+    if (hosts.length === 0) {
+        const payload = {
+            target: { id: found.id, name: found.name, kind: found.kind },
+            hosts: [],
+            note: "This resource has no RUNS_ON edges in the current topology — either it is itself a top-level host with no tenants yet, or its connector does not emit RUNS_ON.",
+        };
+        return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+    }
+    const perHost = [];
+    for (const hostId of hosts) {
+        const host = byId.get(hostId);
+        if (!host)
+            continue;
+        const childIds = Array.from(runsOnIn.get(hostId) || []);
+        // Bucket children by their ownership root.
+        const buckets = new Map();
+        for (const cid of childIds) {
+            const child = byId.get(cid);
+            if (!child)
+                continue;
+            const rootId = ownershipRoot(cid);
+            const root = byId.get(rootId);
+            const bucket = buckets.get(rootId) || {
+                ownershipRoot: rootId,
+                ownershipRootName: root ? root.name : rootId,
+                ownershipRootKind: root ? root.kind : "?",
+                members: [],
+            };
+            bucket.members.push({ id: child.id, name: child.name, kind: child.kind });
+            buckets.set(rootId, bucket);
+        }
+        const coTenants = Array.from(buckets.values()).sort((a, b) => b.members.length - a.members.length);
+        perHost.push({
+            host: { id: host.id, name: host.name, kind: host.kind },
+            ownershipRoots: coTenants.length,
+            coTenants,
+        });
+    }
+    // Surface a one-line recommendation when ≥2 services share a host —
+    // exactly the "blast radius if it fails" case that justifies this tool.
+    const sharedHosts = perHost.filter((h) => h.ownershipRoots > 1);
+    const summary = sharedHosts.length > 0
+        ? `${sharedHosts.length} of ${perHost.length} host(s) carry ≥2 services — those hosts are blast-radius candidates if they fail.`
+        : `No host carries more than one service besides the target — limited shared-host blast radius.`;
+    const payload = {
+        target: { id: found.id, name: found.name, kind: found.kind },
+        hosts: perHost,
+        summary,
+    };
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+    };
+}

package/dist/tools/topology.test.d.ts

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