@thotischner/observability-mcp 1.6.0 → 1.7.1

package/dist/connectors/topology.test.js

@@ -0,0 +1,165 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { isTopologyProvider } from "./interface.js";
+// A minimal connector that exposes no topology methods.
+function makeMetricsOnlyConnector() {
+    return {
+        name: "m1",
+        type: "prometheus",
+        signalType: "metrics",
+        async connect() { },
+        async healthCheck() {
+            return { status: "up", latencyMs: 0 };
+        },
+        async disconnect() { },
+        getDefaultMetrics() {
+            return [];
+        },
+        getMetrics() {
+            return [];
+        },
+        async listServices() {
+            return [];
+        },
+    };
+}
+// A fake topology connector that returns a tiny, well-formed graph.
+function makeTopologyConnector() {
+    const resources = [
+        {
+            id: "k8s:pod:default/checkout-7f89d",
+            kind: "pod",
+            name: "checkout-7f89d",
+            source: "kind-cluster",
+            labels: { app: "checkout" },
+            attributes: { uid: "11111111-1111-1111-1111-111111111111" },
+        },
+        {
+            id: "k8s:node:worker-1",
+            kind: "node",
+            name: "worker-1",
+            source: "kind-cluster",
+            labels: {},
+        },
+    ];
+    const edges = [
+        {
+            from: "k8s:pod:default/checkout-7f89d",
+            to: "k8s:node:worker-1",
+            relation: "RUNS_ON",
+            source: "kind-cluster",
+            confidence: 1.0,
+        },
+    ];
+    return {
+        name: "kind-cluster",
+        type: "kubernetes",
+        signalType: "topology",
+        async connect() { },
+        async healthCheck() {
+            return { status: "up", latencyMs: 0 };
+        },
+        async disconnect() { },
+        getDefaultMetrics() {
+            return [];
+        },
+        getMetrics() {
+            return [];
+        },
+        async listServices() {
+            return [];
+        },
+        async listResources() {
+            return resources;
+        },
+        async listEdges() {
+            return edges;
+        },
+        async getTopologySnapshot() {
+            return { source: "kind-cluster", resources, edges, revision: 1 };
+        },
+        watchTopology(listener) {
+            // emit an initial resync, then a no-op unsubscribe
+            queueMicrotask(() => listener({
+                type: "resync",
+                snapshot: { source: "kind-cluster", resources, edges, revision: 1 },
+            }));
+            return () => { };
+        },
+    };
+}
+describe("isTopologyProvider", () => {
+    it("returns false for metrics-only connectors", () => {
+        assert.equal(isTopologyProvider(makeMetricsOnlyConnector()), false);
+    });
+    it("returns true when all four topology methods are present", () => {
+        assert.equal(isTopologyProvider(makeTopologyConnector()), true);
+    });
+    it("returns false if any topology method is missing", () => {
+        const conn = makeTopologyConnector();
+        // Strip one method — partial topology support is not a TopologyProvider.
+        delete conn.watchTopology;
+        assert.equal(isTopologyProvider(conn), false);
+    });
+});
+describe("topology data model", () => {
+    it("Resource.id follows the k8s:<kind>:<namespace>/<name> shape for namespaced kinds", async () => {
+        const conn = makeTopologyConnector();
+        assert.ok(isTopologyProvider(conn));
+        const resources = await conn.listResources();
+        const pod = resources.find((r) => r.kind === "pod");
+        assert.ok(pod, "expected a pod resource");
+        assert.match(pod.id, /^k8s:pod:[^/]+\/.+$/);
+    });
+    it("Resource.id for cluster-scoped kinds has no namespace segment", async () => {
+        const conn = makeTopologyConnector();
+        assert.ok(isTopologyProvider(conn));
+        const resources = await conn.listResources();
+        const node = resources.find((r) => r.kind === "node");
+        assert.ok(node, "expected a node resource");
+        assert.match(node.id, /^k8s:node:[^/]+$/);
+    });
+    it("every Resource and Edge carries a non-empty source", async () => {
+        const conn = makeTopologyConnector();
+        assert.ok(isTopologyProvider(conn));
+        const snap = await conn.getTopologySnapshot();
+        for (const r of snap.resources)
+            assert.ok(r.source.length > 0);
+        for (const e of snap.edges)
+            assert.ok(e.source.length > 0);
+    });
+    it("Edge endpoints reference existing Resource ids", async () => {
+        const conn = makeTopologyConnector();
+        assert.ok(isTopologyProvider(conn));
+        const snap = await conn.getTopologySnapshot();
+        const ids = new Set(snap.resources.map((r) => r.id));
+        for (const e of snap.edges) {
+            assert.ok(ids.has(e.from), `dangling edge.from: ${e.from}`);
+            assert.ok(ids.has(e.to), `dangling edge.to: ${e.to}`);
+        }
+    });
+    it("confidence is bounded to [0,1]", async () => {
+        const conn = makeTopologyConnector();
+        assert.ok(isTopologyProvider(conn));
+        const edges = await conn.listEdges();
+        for (const e of edges) {
+            assert.ok(e.confidence >= 0 && e.confidence <= 1);
+        }
+    });
+});
+describe("watchTopology", () => {
+    it("delivers a resync event with the current snapshot", async () => {
+        const conn = makeTopologyConnector();
+        assert.ok(isTopologyProvider(conn));
+        const events = [];
+        const unsubscribe = conn.watchTopology((e) => events.push(e));
+        // Allow the queued microtask to fire.
+        await new Promise((resolve) => setImmediate(resolve));
+        unsubscribe();
+        assert.equal(events.length, 1);
+        assert.equal(events[0].type, "resync");
+        if (events[0].type === "resync") {
+            assert.ok(events[0].snapshot.revision >= 1);
+        }
+    });
+});

package/dist/index.js

@@ -8,6 +8,7 @@ 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";
@@ -23,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";
@@ -238,6 +240,48 @@ async function main() {
             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 ---
@@ -691,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/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 {};