@thotischner/observability-mcp 1.7.0 → 1.7.1

package/dist/connectors/kubernetes.d.ts

@@ -29,6 +29,7 @@ export declare class KubernetesConnector implements ObservabilityConnector {
     readonly signalType: SignalType;
     name: string;
     private store;
+    private warnedVocab;
     private factory?;
     private informers;
     private providerOverride?;

package/dist/connectors/kubernetes.js

@@ -1,4 +1,5 @@
 import { TopologyStore, podResource, podEdges, nodeResource, deploymentResource, deploymentEdges, replicaSetResource, replicaSetEdges, namespaceResource, namespacedId, clusterScopedId, } from "./kubernetes-graph.js";
+import { validateSnapshot } from "./topology-vocabulary.js";
 // Default provider is loaded lazily so tests don't pay the
 // @kubernetes/client-node import cost (and so the module is usable in
 // environments where the SDK isn't installed yet — e.g. unit tests in CI
@@ -19,6 +20,7 @@ export class KubernetesConnector {
     signalType = "topology";
     name = "";
     store;
+    warnedVocab = new Set();
     factory;
     informers = [];
     providerOverride;
@@ -141,12 +143,20 @@ export class KubernetesConnector {
         return this.store?.listEdges() ?? [];
     }
     async getTopologySnapshot() {
-        return (this.store?.snapshot() ?? {
+        const snap = this.store?.snapshot() ?? {
             source: this.name,
             resources: [],
             edges: [],
             revision: 0,
-        });
+        };
+        for (const w of validateSnapshot(snap.resources, snap.edges)) {
+            const key = `${w.kind}:${w.value}`;
+            if (this.warnedVocab.has(key))
+                continue;
+            this.warnedVocab.add(key);
+            console.warn("topology vocabulary warning (source=%s): %s", this.name, w.message);
+        }
+        return snap;
     }
     watchTopology(listener) {
         if (!this.store)

package/dist/connectors/topology-vocabulary.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Canonical vocabulary for the connector-agnostic topology graph.
+ *
+ * The set is intentionally small: only values that are emitted by a shipped
+ * connector OR are reserved as the agreed name for a near-term connector.
+ * Adding a value is a documentation change in docs/topology-vocabulary.md
+ * plus an entry in the const arrays below; never invent a value at the call
+ * site without that paper trail.
+ *
+ * Validation is warn-only by design — a connector that emits an unknown
+ * value still works, but the warning shows up in logs and unit tests so
+ * vocabulary drift gets caught before it spreads.
+ */
+import type { Edge, Resource } from "../types.js";
+export declare const KINDS: readonly ["pod", "node", "deployment", "replicaset", "namespace", "service", "container", "vm", "host", "hypervisor", "cluster"];
+export type Kind = (typeof KINDS)[number];
+export declare const RELATIONS: readonly ["RUNS_ON", "OWNED_BY", "IN_NAMESPACE", "CALLS", "CONTAINS", "DEPENDS_ON"];
+export type Relation = (typeof RELATIONS)[number];
+export declare function isKnownKind(k: string): k is Kind;
+export declare function isKnownRelation(r: string): r is Relation;
+export interface VocabularyWarning {
+    kind: "unknown_resource_kind" | "unknown_relation" | "case_mismatch";
+    message: string;
+    value: string;
+}
+/**
+ * Lint a single resource. Returns warnings for unknown or miscased `kind`
+ * values; an empty array means the resource passes the vocabulary.
+ */
+export declare function validateResource(r: Pick<Resource, "kind">): VocabularyWarning[];
+/**
+ * Lint a single edge. Returns warnings for unknown or miscased `relation`
+ * values; an empty array means the edge passes the vocabulary.
+ */
+export declare function validateEdge(e: Pick<Edge, "relation">): VocabularyWarning[];
+/**
+ * Convenience: lint a full snapshot. Returns the de-duplicated set of
+ * warnings (one per distinct value) so a noisy connector does not flood
+ * the log on each tick.
+ */
+export declare function validateSnapshot(resources: Pick<Resource, "kind">[], edges: Pick<Edge, "relation">[]): VocabularyWarning[];

package/dist/connectors/topology-vocabulary.js

@@ -0,0 +1,120 @@
+/**
+ * Canonical vocabulary for the connector-agnostic topology graph.
+ *
+ * The set is intentionally small: only values that are emitted by a shipped
+ * connector OR are reserved as the agreed name for a near-term connector.
+ * Adding a value is a documentation change in docs/topology-vocabulary.md
+ * plus an entry in the const arrays below; never invent a value at the call
+ * site without that paper trail.
+ *
+ * Validation is warn-only by design — a connector that emits an unknown
+ * value still works, but the warning shows up in logs and unit tests so
+ * vocabulary drift gets caught before it spreads.
+ */
+export const KINDS = [
+    "pod",
+    "node",
+    "deployment",
+    "replicaset",
+    "namespace",
+    "service",
+    "container",
+    "vm",
+    "host",
+    "hypervisor",
+    "cluster",
+];
+export const RELATIONS = [
+    "RUNS_ON",
+    "OWNED_BY",
+    "IN_NAMESPACE",
+    "CALLS",
+    "CONTAINS",
+    "DEPENDS_ON",
+];
+const KIND_SET = new Set(KINDS);
+const RELATION_SET = new Set(RELATIONS);
+export function isKnownKind(k) {
+    return KIND_SET.has(k);
+}
+export function isKnownRelation(r) {
+    return RELATION_SET.has(r);
+}
+/**
+ * Lint a single resource. Returns warnings for unknown or miscased `kind`
+ * values; an empty array means the resource passes the vocabulary.
+ */
+export function validateResource(r) {
+    const out = [];
+    if (!isKnownKind(r.kind)) {
+        const lower = r.kind.toLowerCase();
+        if (isKnownKind(lower)) {
+            out.push({
+                kind: "case_mismatch",
+                value: r.kind,
+                message: `resource kind "${r.kind}" should be lowercase "${lower}" — see docs/topology-vocabulary.md`,
+            });
+        }
+        else {
+            out.push({
+                kind: "unknown_resource_kind",
+                value: r.kind,
+                message: `resource kind "${r.kind}" is not in the canonical vocabulary; either rename or extend docs/topology-vocabulary.md + KINDS`,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Lint a single edge. Returns warnings for unknown or miscased `relation`
+ * values; an empty array means the edge passes the vocabulary.
+ */
+export function validateEdge(e) {
+    const out = [];
+    if (!isKnownRelation(e.relation)) {
+        const upper = e.relation.toUpperCase();
+        if (isKnownRelation(upper)) {
+            out.push({
+                kind: "case_mismatch",
+                value: e.relation,
+                message: `relation "${e.relation}" should be UPPER_SNAKE "${upper}" — see docs/topology-vocabulary.md`,
+            });
+        }
+        else {
+            out.push({
+                kind: "unknown_relation",
+                value: e.relation,
+                message: `relation "${e.relation}" is not in the canonical vocabulary; either rename or extend docs/topology-vocabulary.md + RELATIONS`,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Convenience: lint a full snapshot. Returns the de-duplicated set of
+ * warnings (one per distinct value) so a noisy connector does not flood
+ * the log on each tick.
+ */
+export function validateSnapshot(resources, edges) {
+    const seen = new Set();
+    const out = [];
+    for (const r of resources) {
+        for (const w of validateResource(r)) {
+            const key = `r:${w.kind}:${w.value}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                out.push(w);
+            }
+        }
+    }
+    for (const e of edges) {
+        for (const w of validateEdge(e)) {
+            const key = `e:${w.kind}:${w.value}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                out.push(w);
+            }
+        }
+    }
+    return out;
+}

package/dist/connectors/topology-vocabulary.test.d.ts

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

package/dist/connectors/topology-vocabulary.test.js

@@ -0,0 +1,63 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { KINDS, RELATIONS, isKnownKind, isKnownRelation, validateResource, validateEdge, validateSnapshot, } from "./topology-vocabulary.js";
+test("vocabulary — KINDS and RELATIONS contain what the kubernetes connector emits today", () => {
+    for (const k of ["pod", "node", "deployment", "replicaset", "namespace"]) {
+        assert.equal(isKnownKind(k), true, `kind "${k}" must be in the canonical vocabulary`);
+    }
+    for (const r of ["RUNS_ON", "OWNED_BY", "IN_NAMESPACE"]) {
+        assert.equal(isKnownRelation(r), true, `relation "${r}" must be in the canonical vocabulary`);
+    }
+});
+test("vocabulary — CALLS is reserved for the upcoming trace connector", () => {
+    assert.equal(isKnownRelation("CALLS"), true);
+});
+test("validateResource — canonical kinds produce no warnings", () => {
+    for (const k of KINDS) {
+        assert.deepEqual(validateResource({ kind: k }), []);
+    }
+});
+test("validateResource — unknown kind warns", () => {
+    const w = validateResource({ kind: "frobnicator" });
+    assert.equal(w.length, 1);
+    assert.equal(w[0].kind, "unknown_resource_kind");
+    assert.equal(w[0].value, "frobnicator");
+});
+test("validateResource — uppercase kind triggers a case-mismatch hint", () => {
+    const w = validateResource({ kind: "Pod" });
+    assert.equal(w.length, 1);
+    assert.equal(w[0].kind, "case_mismatch");
+    assert.match(w[0].message, /lowercase "pod"/);
+});
+test("validateEdge — canonical relations produce no warnings", () => {
+    for (const r of RELATIONS) {
+        assert.deepEqual(validateEdge({ relation: r }), []);
+    }
+});
+test("validateEdge — unknown relation warns", () => {
+    const w = validateEdge({ relation: "FROBNICATES" });
+    assert.equal(w.length, 1);
+    assert.equal(w[0].kind, "unknown_relation");
+});
+test("validateEdge — lowercase relation triggers a case-mismatch hint", () => {
+    const w = validateEdge({ relation: "runs_on" });
+    assert.equal(w.length, 1);
+    assert.equal(w[0].kind, "case_mismatch");
+    assert.match(w[0].message, /UPPER_SNAKE "RUNS_ON"/);
+});
+test("validateSnapshot — de-duplicates repeated offenders", () => {
+    const warnings = validateSnapshot([
+        { kind: "frobnicator" },
+        { kind: "frobnicator" },
+        { kind: "pod" },
+    ], [
+        { relation: "FROBNICATES" },
+        { relation: "FROBNICATES" },
+        { relation: "RUNS_ON" },
+    ]);
+    assert.equal(warnings.length, 2, `expected one warning per distinct offender, got ${warnings.length}`);
+});
+test("validateSnapshot — a fully canonical snapshot is silent", () => {
+    const warnings = validateSnapshot([{ kind: "pod" }, { kind: "node" }, { kind: "deployment" }], [{ relation: "RUNS_ON" }, { relation: "OWNED_BY" }, { relation: "IN_NAMESPACE" }]);
+    assert.deepEqual(warnings, []);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thotischner/observability-mcp",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "Unified observability gateway for AI agents — one MCP server for Prometheus, Loki, and any backend",
   "type": "module",
   "license": "Apache-2.0",