@thotischner/observability-mcp 1.8.1 → 3.0.0

package/dist/tools/topology.js

@@ -14,11 +14,15 @@
 // connector later requires zero changes here.
 import { isTopologyProvider } from "../connectors/interface.js";
 import { defaultContext } from "../context.js";
-export async function aggregateTopology(registry) {
+export async function aggregateTopology(registry, tenant) {
     const sources = [];
     const resources = [];
     const edges = [];
-    for (const c of registry.getAll()) {
+    // Tenant-scoped when a tenant is supplied (call sites at the MCP
+    // tool layer pass ctx.tenant); undefined preserves the original
+    // global behaviour for internal / non-request callers.
+    const connectors = tenant ? registry.getByTenant(tenant) : registry.getAll();
+    for (const c of connectors) {
         if (!isTopologyProvider(c))
             continue;
         try {
@@ -79,8 +83,8 @@ 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);
+export async function getTopologyHandler(registry, args = {}, ctx = defaultContext()) {
+    const agg = await aggregateTopology(registry, ctx.tenant);
     // Filtering — all optional. Filters compose conjunctively.
     let resources = agg.resources;
     let edges = agg.edges;
@@ -133,8 +137,8 @@ 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);
+export async function getBlastRadiusHandler(registry, args, ctx = defaultContext()) {
+    const agg = await aggregateTopology(registry, ctx.tenant);
     const found = resolveResource(args.resource, agg.resources);
     if ("error" in found) {
         return {

package/dist/topology/merge.d.ts

@@ -0,0 +1,22 @@
+import type { Resource, Edge, TopologySnapshot } from "../types.js";
+/** Labels we treat as canonical-name carriers. First-match wins. */
+export declare const CANONICAL_LABEL_KEYS: readonly ["app.kubernetes.io/name", "app.kubernetes.io/instance", "app", "service", "service.name", "k8s-app"];
+/** Lower-cased label-key lookup; first match in CANONICAL_LABEL_KEYS
+ *  ordering wins so two providers with different label conventions
+ *  still converge if they both ship a known label. */
+export declare function canonicalNameFor(r: Resource): string | undefined;
+export interface MergeResult {
+    resources: Resource[];
+    edges: Edge[];
+    /** Map from original (source-scoped) id → merged canonical id. Used
+     *  to rewrite edges that referenced one of the collapsed nodes. */
+    idMap: Map<string, string>;
+}
+/**
+ * Merge a set of provider snapshots into one unified graph. The
+ * input is the flat union of every provider's resources+edges; the
+ * output collapses every group of nodes that share a canonical name
+ * (and a compatible kind) into a single node, then rewrites the
+ * edge endpoints accordingly.
+ */
+export declare function mergeTopologies(snapshots: TopologySnapshot[]): MergeResult;

package/dist/topology/merge.js

@@ -0,0 +1,178 @@
+// Topology merger — collapses Resources/Edges that come from
+// multiple providers into a single deduped graph.
+//
+// The default unified-view is the union of every provider's
+// snapshot, with no dedup. That's fine for unrelated providers
+// (k8s + AWS in different accounts) but breaks down once two
+// providers describe the same logical service (k8s `payment`
+// Deployment + ECS `payment-service` + Tempo `trace_service`
+// `payment`). Without a merger, get_blast_radius walks them as
+// three independent nodes and the LLM sees ghost relationships
+// instead of one real chain.
+//
+// Reconciliation rules, in priority order:
+//   1. Explicit override via attributes.canonicalName
+//   2. Match on any CANONICAL_LABEL_KEYS entry (case-insensitive)
+//   3. Name + kind-compatibility table
+//
+// See docs/topology-vocabulary.md for the rationale.
+/** Labels we treat as canonical-name carriers. First-match wins. */
+export const CANONICAL_LABEL_KEYS = [
+    "app.kubernetes.io/name",
+    "app.kubernetes.io/instance",
+    "app",
+    "service",
+    "service.name",
+    "k8s-app",
+];
+/** Pairs of kinds that are allowed to merge when their canonical
+ *  names match. Order doesn't matter (we normalise to sorted pair). */
+const MERGEABLE_KIND_PAIRS = new Set([
+    ["deployment", "cloud_service"],
+    ["deployment", "trace_service"],
+    ["cloud_service", "trace_service"],
+    ["pod", "container"],
+].map((p) => p.slice().sort().join("|")));
+function kindsMergeable(a, b) {
+    if (a === b)
+        return true;
+    return MERGEABLE_KIND_PAIRS.has([a, b].sort().join("|"));
+}
+/** Lower-cased label-key lookup; first match in CANONICAL_LABEL_KEYS
+ *  ordering wins so two providers with different label conventions
+ *  still converge if they both ship a known label. */
+export function canonicalNameFor(r) {
+    const override = typeof r.attributes?.canonicalName === "string"
+        ? r.attributes.canonicalName
+        : undefined;
+    if (override)
+        return override.toLowerCase();
+    if (!r.labels)
+        return undefined;
+    const lower = new Map();
+    for (const [k, v] of Object.entries(r.labels)) {
+        lower.set(k.toLowerCase(), v);
+    }
+    for (const key of CANONICAL_LABEL_KEYS) {
+        const v = lower.get(key.toLowerCase());
+        if (typeof v === "string" && v.length > 0)
+            return v.toLowerCase();
+    }
+    return undefined;
+}
+/**
+ * Merge a set of provider snapshots into one unified graph. The
+ * input is the flat union of every provider's resources+edges; the
+ * output collapses every group of nodes that share a canonical name
+ * (and a compatible kind) into a single node, then rewrites the
+ * edge endpoints accordingly.
+ */
+export function mergeTopologies(snapshots) {
+    const allResources = [];
+    const allEdges = [];
+    for (const s of snapshots) {
+        allResources.push(...s.resources);
+        allEdges.push(...s.edges);
+    }
+    // Group by (canonical-name + kind-bucket). Resources without a
+    // canonical name are passed through unchanged (one bucket each).
+    const groups = new Map();
+    const passthrough = [];
+    for (const r of allResources) {
+        const canonical = canonicalNameFor(r);
+        if (!canonical) {
+            passthrough.push(r);
+            continue;
+        }
+        // Bucket key tries to merge across compatible kinds: we group on
+        // canonical-name alone, then verify pairwise compatibility when
+        // collapsing.
+        const key = canonical;
+        const existing = groups.get(key);
+        if (existing)
+            existing.push(r);
+        else
+            groups.set(key, [r]);
+    }
+    const merged = [...passthrough];
+    const idMap = new Map();
+    for (const bucket of groups.values()) {
+        if (bucket.length === 1) {
+            merged.push(bucket[0]);
+            continue;
+        }
+        // Verify all kinds in the bucket are pairwise mergeable. If any
+        // pair isn't, fall back to passing every member through
+        // unchanged — better a slightly verbose graph than a wrong join.
+        let allCompatible = true;
+        for (let i = 0; i < bucket.length && allCompatible; i++) {
+            for (let j = i + 1; j < bucket.length && allCompatible; j++) {
+                if (!kindsMergeable(bucket[i].kind, bucket[j].kind)) {
+                    allCompatible = false;
+                }
+            }
+        }
+        if (!allCompatible) {
+            merged.push(...bucket);
+            continue;
+        }
+        const collapsed = collapseBucket(bucket);
+        merged.push(collapsed);
+        for (const r of bucket) {
+            if (r.id !== collapsed.id)
+                idMap.set(r.id, collapsed.id);
+        }
+    }
+    // Rewrite edge endpoints + dedupe identical (from,to,relation)
+    // tuples that arose from the collapse.
+    const seen = new Set();
+    const edges = [];
+    for (const e of allEdges) {
+        const from = idMap.get(e.from) ?? e.from;
+        const to = idMap.get(e.to) ?? e.to;
+        if (from === to)
+            continue; // self-loop after collapse → drop
+        const key = `${from}->${to}|${e.relation}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        edges.push({ ...e, from, to });
+    }
+    return { resources: merged, edges, idMap };
+}
+function collapseBucket(bucket) {
+    // Stable choice for the canonical id: pick the first resource
+    // sorted lexicographically by source then id. Source rather than
+    // alphabetical so the choice doesn't flip when a label changes.
+    const sorted = [...bucket].sort((a, b) => {
+        const s = a.source.localeCompare(b.source);
+        return s !== 0 ? s : a.id.localeCompare(b.id);
+    });
+    const primary = sorted[0];
+    const labels = { ...primary.labels };
+    const attributes = { ...(primary.attributes ?? {}) };
+    const mergedFrom = [];
+    for (const r of sorted) {
+        if (r.labels)
+            for (const [k, v] of Object.entries(r.labels))
+                labels[k] = v;
+        if (r.attributes)
+            for (const [k, v] of Object.entries(r.attributes))
+                attributes[k] = v;
+        mergedFrom.push(`${r.source}:${r.id}`);
+    }
+    attributes.mergedFrom = mergedFrom;
+    // Pick the most-specific kind for the merged node: cloud_service
+    // > deployment > pod > trace_service > anything else. The merge
+    // rules above already capped the bucket to compatible kinds.
+    const kindPriority = ["cloud_service", "deployment", "pod", "trace_service", "container"];
+    const kind = kindPriority.find((k) => sorted.some((r) => r.kind === k)) ?? primary.kind;
+    return {
+        id: primary.id,
+        kind,
+        name: primary.name,
+        source: primary.source,
+        labels,
+        attributes,
+    };
+}

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

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

package/dist/topology/merge.test.js

@@ -0,0 +1,110 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mergeTopologies, canonicalNameFor } from "./merge.js";
+function r(id, kind, opts = {}) {
+    return {
+        id,
+        kind,
+        name: opts.name ?? id,
+        source: opts.source ?? "test",
+        labels: opts.labels ?? {},
+        attributes: opts.canonical ? { canonicalName: opts.canonical } : undefined,
+    };
+}
+function e(from, to, relation = "RUNS_ON", source = "test") {
+    return { from, to, relation, source, confidence: 1.0 };
+}
+function snap(resources, edges = []) {
+    return { source: "test", resources, edges, revision: 1 };
+}
+test("canonicalNameFor: attributes.canonicalName wins, lowercased", () => {
+    const got = canonicalNameFor(r("x", "deployment", { canonical: "Payment-Service" }));
+    assert.equal(got, "payment-service");
+});
+test("canonicalNameFor: first matching CANONICAL_LABEL_KEYS entry wins", () => {
+    // app.kubernetes.io/name beats app
+    assert.equal(canonicalNameFor(r("x", "deployment", { labels: { "app.kubernetes.io/name": "wins", app: "loses" } })), "wins");
+    // app beats service when app.kubernetes.io/name absent
+    assert.equal(canonicalNameFor(r("x", "deployment", { labels: { app: "wins", service: "loses" } })), "wins");
+});
+test("canonicalNameFor: case-insensitive label-key match", () => {
+    assert.equal(canonicalNameFor(r("x", "deployment", { labels: { "App": "Yes" } })), "yes");
+});
+test("canonicalNameFor: returns undefined when no canonical signal present", () => {
+    assert.equal(canonicalNameFor(r("x", "deployment")), undefined);
+    assert.equal(canonicalNameFor(r("x", "deployment", { labels: { tier: "frontend" } })), undefined);
+});
+test("mergeTopologies: empty input returns empty result", () => {
+    const m = mergeTopologies([]);
+    assert.deepEqual(m.resources, []);
+    assert.deepEqual(m.edges, []);
+    assert.equal(m.idMap.size, 0);
+});
+test("mergeTopologies: passes resources without canonical name unchanged", () => {
+    const s = snap([r("a", "node", { source: "k8s" }), r("b", "namespace", { source: "k8s" })]);
+    const m = mergeTopologies([s]);
+    assert.equal(m.resources.length, 2);
+    assert.equal(m.idMap.size, 0);
+});
+test("mergeTopologies: collapses k8s Deployment + cloud_service with same canonical name", () => {
+    const k8s = snap([r("dep-payment", "deployment", { source: "k8s", labels: { app: "payment" } })]);
+    const aws = snap([r("ecs-payment", "cloud_service", { source: "aws", canonical: "payment" })]);
+    const m = mergeTopologies([k8s, aws]);
+    assert.equal(m.resources.length, 1, "two providers, one canonical service");
+    const merged = m.resources[0];
+    // Higher-priority kind wins (cloud_service > deployment)
+    assert.equal(merged.kind, "cloud_service");
+    assert.deepEqual((merged.attributes?.mergedFrom).sort(), [
+        "aws:ecs-payment",
+        "k8s:dep-payment",
+    ]);
+    // idMap maps the non-canonical id to the canonical one (first by
+    // source asc, then id asc: aws < k8s, so aws's id wins).
+    assert.equal(merged.id, "ecs-payment");
+    assert.equal(m.idMap.get("dep-payment"), "ecs-payment");
+});
+test("mergeTopologies: incompatible kinds in the bucket → no merge (graph stays verbose)", () => {
+    // `pod` and `function` are not in MERGEABLE_KIND_PAIRS — even if
+    // the names collide we keep both.
+    const k8s = snap([r("p1", "pod", { source: "k8s", labels: { app: "payment" } })]);
+    const aws = snap([r("fn1", "function", { source: "aws", canonical: "payment" })]);
+    const m = mergeTopologies([k8s, aws]);
+    assert.equal(m.resources.length, 2);
+    assert.equal(m.idMap.size, 0);
+});
+test("mergeTopologies: rewrites edges that referenced a collapsed id", () => {
+    const k8s = snap([r("dep-payment", "deployment", { source: "k8s", labels: { app: "payment" } })], [e("pod-1", "dep-payment", "RUNS_AS", "k8s")]);
+    const aws = snap([r("ecs-payment", "cloud_service", { source: "aws", canonical: "payment" })], [e("ecs-payment", "rds-1", "READS_FROM", "aws")]);
+    const m = mergeTopologies([k8s, aws]);
+    // dep-payment was collapsed into ecs-payment
+    const edges = m.edges;
+    // The k8s edge's TO endpoint must be rewritten to ecs-payment.
+    assert.ok(edges.some((x) => x.from === "pod-1" && x.to === "ecs-payment"));
+    // The aws edge stays put.
+    assert.ok(edges.some((x) => x.from === "ecs-payment" && x.to === "rds-1"));
+});
+test("mergeTopologies: self-loops created by the collapse are dropped", () => {
+    // Two resources merge into one. An edge that pointed from A to B
+    // becomes A→A after rewrite; drop it.
+    const k8s = snap([
+        r("dep-payment", "deployment", { source: "k8s", labels: { app: "payment" } }),
+        r("ecs-payment", "cloud_service", { source: "aws", canonical: "payment" }),
+    ], [e("dep-payment", "ecs-payment", "ALIAS_OF", "synthetic")]);
+    const m = mergeTopologies([k8s]);
+    assert.equal(m.resources.length, 1);
+    assert.equal(m.edges.filter((x) => x.from === x.to).length, 0, "self-loops after collapse must be removed");
+});
+test("mergeTopologies: duplicate (from,to,relation) tuples deduped after rewrite", () => {
+    const k8s = snap([
+        r("a", "deployment", { source: "k8s", labels: { app: "payment" } }),
+        r("b", "cloud_service", { source: "aws", canonical: "payment" }),
+        r("client", "deployment", { source: "k8s" }),
+    ], [
+        e("client", "a", "CALLS", "k8s"),
+        e("client", "b", "CALLS", "aws"),
+    ]);
+    const m = mergeTopologies([k8s]);
+    // After collapse, both edges become client→b CALLS — dedup to one.
+    const callEdges = m.edges.filter((x) => x.relation === "CALLS");
+    assert.equal(callEdges.length, 1);
+});

package/dist/transport/sessionStore.d.ts

@@ -0,0 +1,66 @@
+export interface SessionStore {
+    /** Stable backend identifier (used in /api/info diagnostics). */
+    readonly backend: string;
+    /** Get a JSON-serialisable value by key. */
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    /** Set a value with no expiry. */
+    set<T = unknown>(key: string, value: T): Promise<void>;
+    /** Set a value that auto-expires after `ttlSeconds`. */
+    setEx<T = unknown>(key: string, ttlSeconds: number, value: T): Promise<void>;
+    /** Remove a key. No-op if missing. */
+    del(key: string): Promise<void>;
+    /** List all keys matching a glob-style prefix (used by SCIM /
+     *  DCR enumeration). Not required to be efficient; backends MAY
+     *  impose a soft cap (and document it). */
+    keys(prefix: string): Promise<string[]>;
+    /** Best-effort shutdown — flush + disconnect any pooled clients. */
+    close(): Promise<void>;
+}
+/** Single-process, in-memory store. Default when OMCP_REDIS_URL is
+ *  unset. Lazy expiry — entries are evicted on the next access. */
+export declare class InMemorySessionStore implements SessionStore {
+    readonly backend = "memory";
+    private readonly map;
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(key: string, value: T): Promise<void>;
+    setEx<T = unknown>(key: string, ttlSeconds: number, value: T): Promise<void>;
+    del(key: string): Promise<void>;
+    keys(prefix: string): Promise<string[]>;
+    close(): Promise<void>;
+    /** Test-only: introspect size. */
+    size(): number;
+}
+/** Redis-backed store. Constructed lazily via `connectRedisStore` so
+ *  the `redis` driver only loads when actually used. */
+export declare class RedisSessionStore implements SessionStore {
+    readonly backend = "redis";
+    private readonly client;
+    private readonly prefix;
+    constructor(client: RedisClientLike, prefix?: string);
+    private k;
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(key: string, value: T): Promise<void>;
+    setEx<T = unknown>(key: string, ttlSeconds: number, value: T): Promise<void>;
+    del(key: string): Promise<void>;
+    keys(prefix: string): Promise<string[]>;
+    close(): Promise<void>;
+}
+/** Minimum surface a Redis client must implement. Lets us inject a
+ *  fake in tests and stays compatible across the `redis` / `ioredis`
+ *  package shapes. */
+export interface RedisClientLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, opts?: {
+        EX?: number;
+    }): Promise<string | null | undefined>;
+    del(key: string): Promise<number>;
+    keys(pattern: string): Promise<string[]>;
+    quit(): Promise<unknown>;
+}
+/**
+ * Resolve the session store from env. Default: InMemorySessionStore.
+ * When OMCP_REDIS_URL is set: load `redis` dynamically, connect, and
+ * return a RedisSessionStore. On any connect failure, log + fall back
+ * to InMemory (the gateway must boot even when Redis is down).
+ */
+export declare function resolveSessionStore(env?: NodeJS.ProcessEnv): Promise<SessionStore>;

package/dist/transport/sessionStore.js

@@ -0,0 +1,138 @@
+// Shared session store — abstract backend for any short-lived state
+// the gateway needs to keep across replicas: MCP Streamable HTTP
+// session metadata, OIDC flow state (PKCE verifier, nonce, redirect
+// target), DCR-registered client metadata, federation upstream
+// catalogue cache.
+//
+// Two implementations ship in v2.0:
+//
+//   InMemorySessionStore — the default; preserves the pre-F8 behaviour
+//     (single-replica, ephemeral on restart). No new dep, no new env.
+//
+//   RedisSessionStore — opt-in via OMCP_REDIS_URL. Backs all consumers
+//     with a shared Redis so multi-replica deployments stop losing
+//     sessions on rollouts and so federated upstreams can share a
+//     cache. Driver loaded via dynamic import so the `redis` package
+//     only loads when the store is configured.
+//
+// Consumers MUST treat returns as eventually-consistent across
+// replicas: a get() right after a set() on a different replica may
+// return undefined while replication catches up. Use TTLs for any
+// state that must self-cleanup (the store's `setEx` honours the
+// requested ttl seconds; `set` is no-expiry).
+/** Single-process, in-memory store. Default when OMCP_REDIS_URL is
+ *  unset. Lazy expiry — entries are evicted on the next access. */
+export class InMemorySessionStore {
+    backend = "memory";
+    map = new Map();
+    async get(key) {
+        const entry = this.map.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt <= Date.now()) {
+            this.map.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    async set(key, value) {
+        this.map.set(key, { value, expiresAt: Number.POSITIVE_INFINITY });
+    }
+    async setEx(key, ttlSeconds, value) {
+        this.map.set(key, { value, expiresAt: Date.now() + ttlSeconds * 1000 });
+    }
+    async del(key) {
+        this.map.delete(key);
+    }
+    async keys(prefix) {
+        const out = [];
+        const now = Date.now();
+        for (const [k, v] of this.map) {
+            if (v.expiresAt <= now) {
+                this.map.delete(k);
+                continue;
+            }
+            if (k.startsWith(prefix))
+                out.push(k);
+        }
+        return out;
+    }
+    async close() {
+        this.map.clear();
+    }
+    /** Test-only: introspect size. */
+    size() {
+        return this.map.size;
+    }
+}
+/** Redis-backed store. Constructed lazily via `connectRedisStore` so
+ *  the `redis` driver only loads when actually used. */
+export class RedisSessionStore {
+    backend = "redis";
+    client;
+    prefix;
+    constructor(client, prefix = "omcp:") {
+        this.client = client;
+        this.prefix = prefix;
+    }
+    k(key) {
+        return `${this.prefix}${key}`;
+    }
+    async get(key) {
+        const raw = await this.client.get(this.k(key));
+        if (raw == null)
+            return undefined;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async set(key, value) {
+        await this.client.set(this.k(key), JSON.stringify(value));
+    }
+    async setEx(key, ttlSeconds, value) {
+        await this.client.set(this.k(key), JSON.stringify(value), {
+            EX: ttlSeconds,
+        });
+    }
+    async del(key) {
+        await this.client.del(this.k(key));
+    }
+    async keys(prefix) {
+        const found = await this.client.keys(`${this.k(prefix)}*`);
+        return found.map((k) => k.slice(this.prefix.length));
+    }
+    async close() {
+        try {
+            await this.client.quit();
+        }
+        catch {
+            /* socket may already be down */
+        }
+    }
+}
+/**
+ * Resolve the session store from env. Default: InMemorySessionStore.
+ * When OMCP_REDIS_URL is set: load `redis` dynamically, connect, and
+ * return a RedisSessionStore. On any connect failure, log + fall back
+ * to InMemory (the gateway must boot even when Redis is down).
+ */
+export async function resolveSessionStore(env = process.env) {
+    const url = env.OMCP_REDIS_URL?.trim();
+    if (!url)
+        return new InMemorySessionStore();
+    try {
+        const { createClient } = await import("redis");
+        const client = createClient({ url });
+        client.on("error", (err) => console.warn("RedisSessionStore: client error: %s", err instanceof Error ? err.message : String(err)));
+        await client.connect();
+        console.log("RedisSessionStore: connected (url scheme=%s, prefix=%s)", new URL(url).protocol.replace(/:$/, ""), env.OMCP_REDIS_KEY_PREFIX ?? "omcp:");
+        return new RedisSessionStore(client, env.OMCP_REDIS_KEY_PREFIX ?? "omcp:");
+    }
+    catch (err) {
+        console.warn("RedisSessionStore: connect failed, falling back to in-memory store: %s", err instanceof Error ? err.message : String(err));
+        return new InMemorySessionStore();
+    }
+}

package/dist/transport/sessionStore.test.d.ts

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