@thotischner/observability-mcp 1.7.1 → 3.0.0

package/dist/connectors/loader.js

@@ -23,9 +23,11 @@ export class PluginLoader {
     pluginsDir;
     disabled;
     // Fail-closed verification for filesystem plugins. Builtins are part
-    // of the trusted image and are never gated. Default off so existing
-    // deployments are unchanged; recommended on in prod/airgapped (the
-    // Helm chart sets it).
+    // of the trusted image and are never gated. Default ON — operators
+    // who want to load unsigned filesystem plugins must opt out with
+    // VERIFY_PLUGINS=false. Without a trust root configured, no
+    // filesystem plugins load (only builtins), so the demo and any
+    // deployment without /app/plugins is unaffected.
     verify;
     trustRootPath;
     trustRoot;
@@ -39,7 +41,7 @@ export class PluginLoader {
             .map((s) => s.trim())
             .filter(Boolean);
         this.disabled = new Set([...(opts.disabled ?? []), ...envDisabled]);
-        this.verify = opts.verify ?? /^(1|true|yes)$/i.test(process.env.VERIFY_PLUGINS ?? "");
+        this.verify = opts.verify ?? !/^(0|false|no|off)$/i.test(process.env.VERIFY_PLUGINS ?? "true");
         this.trustRootPath = opts.trustRoot ?? process.env.PLUGIN_TRUST_ROOT;
     }
     async load() {

package/dist/connectors/loader.test.d.ts

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

package/dist/connectors/loader.test.js

@@ -0,0 +1,78 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { PluginLoader } from "./loader.js";
+function tmp() {
+    return mkdtempSync(join(tmpdir(), "loader-default-"));
+}
+function withEnv(overrides, fn) {
+    const saved = {};
+    for (const k of Object.keys(overrides)) {
+        saved[k] = process.env[k];
+        if (overrides[k] === undefined)
+            delete process.env[k];
+        else
+            process.env[k] = overrides[k];
+    }
+    try {
+        fn();
+    }
+    finally {
+        for (const k of Object.keys(saved)) {
+            if (saved[k] === undefined)
+                delete process.env[k];
+            else
+                process.env[k] = saved[k];
+        }
+    }
+}
+test("PluginLoader: VERIFY_PLUGINS defaults to ON when env var unset", () => {
+    withEnv({ VERIFY_PLUGINS: undefined, PLUGIN_TRUST_ROOT: undefined }, () => {
+        const loader = new PluginLoader({ pluginsDir: tmp() });
+        assert.equal(loader["verify"], true, "verify default should be true (fail-closed)");
+    });
+});
+test("PluginLoader: VERIFY_PLUGINS=false opts out explicitly", () => {
+    withEnv({ VERIFY_PLUGINS: "false" }, () => {
+        const loader = new PluginLoader({ pluginsDir: tmp() });
+        assert.equal(loader["verify"], false);
+    });
+});
+test("PluginLoader: VERIFY_PLUGINS=0 / no / off also opt out", () => {
+    for (const v of ["0", "no", "off", "FALSE", "Off"]) {
+        withEnv({ VERIFY_PLUGINS: v }, () => {
+            const loader = new PluginLoader({ pluginsDir: tmp() });
+            assert.equal(loader["verify"], false, `value ${v} should disable verify`);
+        });
+    }
+});
+test("PluginLoader: VERIFY_PLUGINS=true / 1 / yes keep verify on", () => {
+    for (const v of ["true", "1", "yes", "TRUE", "Yes"]) {
+        withEnv({ VERIFY_PLUGINS: v }, () => {
+            const loader = new PluginLoader({ pluginsDir: tmp() });
+            assert.equal(loader["verify"], true);
+        });
+    }
+});
+test("PluginLoader: opts.verify overrides env var", () => {
+    withEnv({ VERIFY_PLUGINS: "false" }, () => {
+        const onLoader = new PluginLoader({ pluginsDir: tmp(), verify: true });
+        assert.equal(onLoader["verify"], true);
+    });
+    withEnv({ VERIFY_PLUGINS: "true" }, () => {
+        const offLoader = new PluginLoader({ pluginsDir: tmp(), verify: false });
+        assert.equal(offLoader["verify"], false);
+    });
+});
+test("PluginLoader.load(): with verify on + no trust root → builtins still load, filesystem skipped", async () => {
+    withEnv({ VERIFY_PLUGINS: undefined, PLUGIN_TRUST_ROOT: undefined }, async () => {
+        const loader = new PluginLoader({ pluginsDir: tmp() });
+        await loader.load();
+        const names = loader.supportedTypes();
+        assert.ok(names.includes("prometheus"), "prometheus builtin must remain available");
+        assert.ok(names.includes("loki"), "loki builtin must remain available");
+        assert.ok(names.includes("kubernetes"), "kubernetes builtin must remain available");
+    });
+});

package/dist/connectors/prometheus.test.js

@@ -77,27 +77,45 @@ describe("PrometheusConnector", () => {
         });
     });
     describe("buildQuery", () => {
-        it("replaces {{service}} placeholder in known metrics", async () => {
+        // buildQuery is private async and returns `{ promql, label, candidate }`.
+        // To keep these tests off the network, every case uses a user-
+        // override metric — that short-circuits the candidate-probe path
+        // (which would otherwise call Prometheus to pick the best variant
+        // and resolveServiceLabel to discover the right scoping label).
+        // The label / candidate fields are exercised via the public
+        // queryMetrics path elsewhere.
+        const fakeSource = { name: "test", type: "prometheus", url: "http://localhost:9090", enabled: true };
+        it("replaces {{service}} placeholder in user-defined metrics", async () => {
             const connector = new PrometheusConnector();
-            await connector.connect({ name: "test", type: "prometheus", url: "http://localhost:9090", enabled: true });
-            const query = proto.buildQuery.call(connector, "payment-service", "cpu");
-            assert.ok(query.includes("payment-service"));
-            assert.ok(!query.includes("{{service}}"));
-        });
-        it("falls back to generic query for unknown metrics", async () => {
+            await connector.connect({
+                ...fakeSource,
+                metrics: [{ name: "cpu", query: 'cpu_usage{svc="{{service}}"}', unit: "%", description: "CPU" }],
+            });
+            const { promql } = await proto.buildQuery.call(connector, "payment-service", "cpu");
+            assert.ok(promql.includes("payment-service"));
+            assert.ok(!promql.includes("{{service}}"));
+        });
+        it("respects an explicit {{service}} substitution outside the {{selector}} sugar", async () => {
+            // Different from the other two: the override here uses {{service}}
+            // directly inside a hand-written selector (no {{selector}} sugar).
+            // Confirms the substitution applies to the raw template, not only
+            // through the label-resolver path.
             const connector = new PrometheusConnector();
-            await connector.connect({ name: "test", type: "prometheus", url: "http://localhost:9090", enabled: true });
-            const query = proto.buildQuery.call(connector, "my-svc", "unknown_metric");
-            assert.equal(query, 'unknown_metric{job="my-svc"}');
+            await connector.connect({
+                ...fakeSource,
+                metrics: [{ name: "explicit_selector", query: 'explicit_metric{job="{{service}}"}', unit: "", description: "" }],
+            });
+            const { promql } = await proto.buildQuery.call(connector, "my-svc", "explicit_selector");
+            assert.equal(promql, 'explicit_metric{job="my-svc"}');
         });
         it("uses custom metrics from source config", async () => {
             const connector = new PrometheusConnector();
             await connector.connect({
-                name: "test", type: "prometheus", url: "http://localhost:9090", enabled: true,
+                ...fakeSource,
                 metrics: [{ name: "custom", query: 'my_custom_metric{svc="{{service}}"}', unit: "ops", description: "Custom" }],
             });
-            const query = proto.buildQuery.call(connector, "api", "custom");
-            assert.equal(query, 'my_custom_metric{svc="api"}');
+            const { promql } = await proto.buildQuery.call(connector, "api", "custom");
+            assert.equal(promql, 'my_custom_metric{svc="api"}');
         });
     });
 });

package/dist/connectors/registry.d.ts

@@ -17,5 +17,18 @@ export declare class ConnectorRegistry {
     getAll(): ObservabilityConnector[];
     getByName(name: string): ObservabilityConnector | undefined;
     getBySignal(signal: SignalType): ObservabilityConnector[];
+    /** Connectors visible to the named tenant: every source whose
+     *  config.tenant matches OR is unset (global). Unset = available
+     *  everywhere — keeps single-tenant deployments untouched.
+     *  Anonymous traffic / the agent / internal callers can pass
+     *  the DEFAULT_TENANT sentinel and see exactly what the default-
+     *  tenant operator sees. */
+    getByTenant(tenant: string): ObservabilityConnector[];
+    /** Same as `getByName`, but enforces the tenant gate: a source
+     *  whose config.tenant is set and differs from the calling tenant
+     *  returns undefined — indistinguishable from "no such source",
+     *  per the rest of the tenancy layer (no cross-tenant existence
+     *  leak). Unset source tenant = global, always resolves. */
+    getByNameForTenant(name: string, tenant: string): ObservabilityConnector | undefined;
     healthCheckAll(): Promise<Record<string, ConnectorHealth>>;
 }

package/dist/connectors/registry.js

@@ -80,6 +80,36 @@ export class ConnectorRegistry {
     getBySignal(signal) {
         return this.getAll().filter((c) => c.signalType === signal);
     }
+    /** Connectors visible to the named tenant: every source whose
+     *  config.tenant matches OR is unset (global). Unset = available
+     *  everywhere — keeps single-tenant deployments untouched.
+     *  Anonymous traffic / the agent / internal callers can pass
+     *  the DEFAULT_TENANT sentinel and see exactly what the default-
+     *  tenant operator sees. */
+    getByTenant(tenant) {
+        const out = [];
+        for (const [name, c] of this.connectors) {
+            const cfg = this.sourceConfigs.get(name);
+            const srcTenant = cfg?.tenant;
+            if (!srcTenant || srcTenant === tenant)
+                out.push(c);
+        }
+        return out;
+    }
+    /** Same as `getByName`, but enforces the tenant gate: a source
+     *  whose config.tenant is set and differs from the calling tenant
+     *  returns undefined — indistinguishable from "no such source",
+     *  per the rest of the tenancy layer (no cross-tenant existence
+     *  leak). Unset source tenant = global, always resolves. */
+    getByNameForTenant(name, tenant) {
+        const c = this.connectors.get(name);
+        if (!c)
+            return undefined;
+        const cfg = this.sourceConfigs.get(name);
+        if (cfg?.tenant && cfg.tenant !== tenant)
+            return undefined;
+        return c;
+    }
     async healthCheckAll() {
         const results = {};
         for (const [name, connector] of this.connectors) {

package/dist/connectors/registry.test.js

@@ -2,15 +2,21 @@ import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 import { getSupportedTypes, ConnectorRegistry } from "./registry.js";
 import { DEFAULT_SETTINGS, DEFAULT_HEALTH_THRESHOLDS } from "../config/loader.js";
+import { getPluginLoader } from "./loader.js";
 function makeConfig(sources = []) {
     return { sources, settings: DEFAULT_SETTINGS, healthThresholds: DEFAULT_HEALTH_THRESHOLDS };
 }
 describe("getSupportedTypes", () => {
-    it("returns prometheus and loki", () => {
+    it("returns the builtins (prometheus, loki, kubernetes) after loader.load()", async () => {
+        // The PluginLoader registers builtins inside load(), not the
+        // constructor — at server boot index.ts awaits load() before any
+        // tool registration code runs. Mirror that here so the test
+        // reflects the real wiring rather than a transient empty state.
+        await getPluginLoader().load();
         const types = getSupportedTypes();
         assert.ok(types.includes("prometheus"));
         assert.ok(types.includes("loki"));
-        assert.equal(types.length, 2);
+        assert.ok(types.includes("kubernetes"));
     });
 });
 describe("ConnectorRegistry", () => {
@@ -90,4 +96,52 @@ describe("ConnectorRegistry", () => {
             assert.deepEqual(results, {});
         });
     });
+    describe("getByTenant / getByNameForTenant", () => {
+        it("untagged sources are visible to every tenant (pre-E7 single-tenant default)", async () => {
+            await getPluginLoader().load();
+            const reg = new ConnectorRegistry();
+            await reg.initialize(makeConfig([
+                // No tenant on either source — both are "global".
+                { name: "prom-global", type: "prometheus", url: "http://p:9090", enabled: true },
+                { name: "loki-global", type: "loki", url: "http://l:3100", enabled: true },
+            ]));
+            const acmeVisible = reg.getByTenant("acme").map((c) => c.name).sort();
+            const bigcoVisible = reg.getByTenant("bigco").map((c) => c.name).sort();
+            assert.deepEqual(acmeVisible, ["loki-global", "prom-global"]);
+            assert.deepEqual(bigcoVisible, ["loki-global", "prom-global"]);
+        });
+        it("tenant-tagged source is invisible to other tenants", async () => {
+            await getPluginLoader().load();
+            const reg = new ConnectorRegistry();
+            await reg.initialize(makeConfig([
+                { name: "shared", type: "prometheus", url: "http://p:9090", enabled: true },
+                { name: "acme-only", type: "loki", url: "http://l:3100", enabled: true, tenant: "acme" },
+            ]));
+            assert.deepEqual(reg.getByTenant("acme").map((c) => c.name).sort(), ["acme-only", "shared"]);
+            // bigco sees only the shared source — the acme-only one is hidden.
+            assert.deepEqual(reg.getByTenant("bigco").map((c) => c.name).sort(), ["shared"]);
+        });
+        it("getByNameForTenant returns undefined on cross-tenant probe (no existence leak)", async () => {
+            await getPluginLoader().load();
+            const reg = new ConnectorRegistry();
+            await reg.initialize(makeConfig([
+                { name: "acme-loki", type: "loki", url: "http://l:3100", enabled: true, tenant: "acme" },
+            ]));
+            // Within tenant: resolves.
+            assert.ok(reg.getByNameForTenant("acme-loki", "acme"));
+            // Cross-tenant: undefined — indistinguishable from "no such source".
+            assert.equal(reg.getByNameForTenant("acme-loki", "bigco"), undefined);
+            // Unknown name in own tenant: also undefined.
+            assert.equal(reg.getByNameForTenant("nope", "acme"), undefined);
+        });
+        it("a source whose tenant is unset resolves for every tenant via getByNameForTenant", async () => {
+            await getPluginLoader().load();
+            const reg = new ConnectorRegistry();
+            await reg.initialize(makeConfig([
+                { name: "global", type: "prometheus", url: "http://p:9090", enabled: true },
+            ]));
+            assert.ok(reg.getByNameForTenant("global", "acme"));
+            assert.ok(reg.getByNameForTenant("global", "bigco"));
+        });
+    });
 });

package/dist/context.d.ts

@@ -18,10 +18,54 @@ export interface RequestContext {
      * scoping (tools/services/lookback/read-only) is a separate concern.
      */
     allowedSources?: string[];
+    /** When true, the credential is allowed to opt out of redaction on a
+     *  per-tool-call basis. The actual bypass is engaged only when the
+     *  tool call ALSO sets `bypass_redaction: true` in its args. Default
+     *  false. Configured via OMCP_KEY_BYPASS_REDACTION. */
+    allowBypassRedaction?: boolean;
+    /** Tenant the request operates in. ALWAYS set — defaults to
+     *  "default" for anonymous principals + missing-tenant credentials,
+     *  preserving the single-namespace behaviour of pre-E7 deployments. */
+    tenant: string;
+    /** When set, the /mcp tools/list response is filtered to this
+     *  allow-list. Resolved from the active credential's bound Product
+     *  (OMCP_KEY_PRODUCTS) against the catalogue at request entry.
+     *  Anonymous + Product-less credentials leave this unset and see
+     *  every registered tool. */
+    allowedTools?: string[];
     /** Correlates all tool calls within one transport request/session. */
     correlationId: string;
 }
 /** Default all-access anonymous context — preserves current behaviour. */
 export declare function defaultContext(): RequestContext;
 /** Context for an authenticated API-key principal. */
-export declare function principalContext(principalId: string, allowedSources?: string[]): RequestContext;
+export declare function principalContext(principalId: string, allowedSources?: string[], opts?: {
+    allowBypassRedaction?: boolean;
+    tenant?: string;
+    allowedTools?: string[];
+}): RequestContext;
+/** Context for an authenticated management-plane (browser / OIDC /
+ *  basic-auth) request. The session-derived tenant flows into tool
+ *  handlers exactly like the MCP-credential path, so a viewer in
+ *  tenant Acme reading /api/services through the dashboard sees the
+ *  same service set as an /mcp client bound to Acme. Anonymous mode
+ *  (no session) → behaves like defaultContext(). */
+export declare function sessionContext(session: {
+    sub?: string;
+    name?: string;
+    tenant?: string;
+} | undefined): RequestContext;
+/** Decide whether a given tool name is accessible under the active
+ *  Product binding. Pure helper so the registration site stays
+ *  declarative and the filtering policy is unit-testable in isolation.
+ *
+ *  Semantics:
+ *    - undefined allow-list → no Product binding, every tool allowed
+ *      (anonymous + Product-less credentials — back-compat).
+ *    - empty allow-list → a Product with no `tools` field. The schema
+ *      treats this as "all tools allowed", matching the YAML loader's
+ *      view that an absent / empty list means no restriction.
+ *    - non-empty → the named tool must appear verbatim.
+ *  Tool names are compared case-sensitively; the MCP spec is
+ *  case-sensitive on `name`. */
+export declare function allowsTool(allowedTools: string[] | undefined, toolName: string): boolean;

package/dist/context.js

@@ -1,18 +1,57 @@
 import { randomUUID } from "node:crypto";
+import { DEFAULT_TENANT, normaliseTenant } from "./tenancy/context.js";
 /** Default all-access anonymous context — preserves current behaviour. */
 export function defaultContext() {
     return {
         principalId: "anonymous",
         auth: "anonymous",
+        tenant: DEFAULT_TENANT,
         correlationId: randomUUID(),
     };
 }
 /** Context for an authenticated API-key principal. */
-export function principalContext(principalId, allowedSources) {
+export function principalContext(principalId, allowedSources, opts = {}) {
     return {
         principalId,
         auth: "apikey",
         allowedSources: allowedSources && allowedSources.length > 0 ? allowedSources : undefined,
+        allowBypassRedaction: opts.allowBypassRedaction || undefined,
+        tenant: normaliseTenant(opts.tenant),
+        allowedTools: opts.allowedTools && opts.allowedTools.length > 0 ? opts.allowedTools : undefined,
         correlationId: randomUUID(),
     };
 }
+/** Context for an authenticated management-plane (browser / OIDC /
+ *  basic-auth) request. The session-derived tenant flows into tool
+ *  handlers exactly like the MCP-credential path, so a viewer in
+ *  tenant Acme reading /api/services through the dashboard sees the
+ *  same service set as an /mcp client bound to Acme. Anonymous mode
+ *  (no session) → behaves like defaultContext(). */
+export function sessionContext(session) {
+    if (!session)
+        return defaultContext();
+    return {
+        principalId: session.sub || session.name || "anonymous",
+        auth: "apikey",
+        tenant: normaliseTenant(session.tenant),
+        correlationId: randomUUID(),
+    };
+}
+/** Decide whether a given tool name is accessible under the active
+ *  Product binding. Pure helper so the registration site stays
+ *  declarative and the filtering policy is unit-testable in isolation.
+ *
+ *  Semantics:
+ *    - undefined allow-list → no Product binding, every tool allowed
+ *      (anonymous + Product-less credentials — back-compat).
+ *    - empty allow-list → a Product with no `tools` field. The schema
+ *      treats this as "all tools allowed", matching the YAML loader's
+ *      view that an absent / empty list means no restriction.
+ *    - non-empty → the named tool must appear verbatim.
+ *  Tool names are compared case-sensitively; the MCP spec is
+ *  case-sensitive on `name`. */
+export function allowsTool(allowedTools, toolName) {
+    if (!allowedTools || allowedTools.length === 0)
+        return true;
+    return allowedTools.includes(toolName);
+}

package/dist/context.test.d.ts

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

package/dist/context.test.js

@@ -0,0 +1,58 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { allowsTool, defaultContext, principalContext } from "./context.js";
+test("allowsTool — undefined allow-list = no Product binding = every tool allowed", () => {
+    assert.equal(allowsTool(undefined, "list_sources"), true);
+    assert.equal(allowsTool(undefined, "query_logs"), true);
+});
+test("allowsTool — empty allow-list = Product with no tools field = every tool allowed", () => {
+    assert.equal(allowsTool([], "list_sources"), true);
+});
+test("allowsTool — non-empty allow-list gates by exact match", () => {
+    const allow = ["list_sources", "query_metrics"];
+    assert.equal(allowsTool(allow, "list_sources"), true);
+    assert.equal(allowsTool(allow, "query_metrics"), true);
+    assert.equal(allowsTool(allow, "query_logs"), false);
+    assert.equal(allowsTool(allow, "get_topology"), false);
+});
+test("allowsTool — case-sensitive (matches MCP spec)", () => {
+    const allow = ["list_sources"];
+    assert.equal(allowsTool(allow, "List_Sources"), false);
+});
+test("principalContext — passes allowedTools through; empty array → undefined", () => {
+    const ctx1 = principalContext("agent", undefined, { allowedTools: ["query_logs"] });
+    assert.deepEqual(ctx1.allowedTools, ["query_logs"]);
+    // Empty array carries the "no restriction" semantic — we normalise
+    // to undefined so allowsTool() takes the back-compat short path.
+    const ctx2 = principalContext("agent", undefined, { allowedTools: [] });
+    assert.equal(ctx2.allowedTools, undefined);
+    const ctx3 = principalContext("agent");
+    assert.equal(ctx3.allowedTools, undefined);
+});
+test("defaultContext — no allowedTools (anonymous sees every tool, back-compat)", () => {
+    const ctx = defaultContext();
+    assert.equal(ctx.allowedTools, undefined);
+    assert.equal(allowsTool(ctx.allowedTools, "any_tool"), true);
+});
+import { sessionContext } from "./context.js";
+test("sessionContext — undefined session → defaultContext shape (anonymous, default tenant)", () => {
+    const ctx = sessionContext(undefined);
+    assert.equal(ctx.auth, "anonymous");
+    assert.equal(ctx.tenant, "default");
+    assert.equal(ctx.principalId, "anonymous");
+});
+test("sessionContext — session.tenant flows into ctx.tenant (the load-bearing property for /api/services + /api/health)", () => {
+    const ctx = sessionContext({ sub: "alice", name: "Alice", tenant: "acme" });
+    assert.equal(ctx.tenant, "acme");
+    assert.equal(ctx.principalId, "alice");
+    assert.equal(ctx.auth, "apikey");
+});
+test("sessionContext — falls back to session.name when sub absent", () => {
+    const ctx = sessionContext({ name: "operator-bot", tenant: "bigco" });
+    assert.equal(ctx.principalId, "operator-bot");
+});
+test("sessionContext — sessionless tenant inherits DEFAULT (no leak from a previous tenant'd request)", () => {
+    // Belt-and-suspenders: explicit empty tenant string normalises to default.
+    const ctx = sessionContext({ sub: "u", tenant: "" });
+    assert.equal(ctx.tenant, "default");
+});

package/dist/federation/registry.d.ts

@@ -0,0 +1,32 @@
+import type { UpstreamClient, UpstreamToolInfo } from "./upstream.js";
+export declare class FederationRegistry {
+    private upstreams;
+    add(client: UpstreamClient): void;
+    remove(name: string): void;
+    get(name: string): UpstreamClient | undefined;
+    list(): UpstreamClient[];
+    /** Flat, namespaced tool view across every connected upstream. */
+    getNamespacedTools(): UpstreamToolInfo[];
+    /** Dispatch a namespaced tool call to the right upstream. The
+     *  namespaced name MUST exist in the catalog; the caller (the
+     *  registerTool wrapper in createMcpServer) is responsible for not
+     *  routing tools that aren't there. */
+    callNamespacedTool(namespacedName: string, args: unknown): Promise<unknown>;
+    closeAll(): Promise<void>;
+}
+/**
+ * Parse the OMCP_FEDERATION_UPSTREAMS env into a list of upstream
+ * configs. Shape:
+ *
+ *   "name1=https://gw.a/mcp,name2=https://gw.b/mcp"
+ *
+ * Each upstream's bearer token is read from
+ * OMCP_FEDERATION_TOKEN_<UPPERCASE-NAME> (dots → underscores), so
+ * tokens stay out of the URL list itself.
+ */
+export interface ParsedUpstream {
+    name: string;
+    url: string;
+    bearerToken?: string;
+}
+export declare function parseFederationEnv(env?: NodeJS.ProcessEnv): ParsedUpstream[];

package/dist/federation/registry.js

@@ -0,0 +1,77 @@
+// FederationRegistry — collects every UpstreamClient + exposes a
+// flat view of namespaced tools across them. createMcpServer reads
+// `getNamespacedTools()` on each per-session instantiation and
+// registers a proxy handler for each one that calls
+// `callNamespacedTool()`.
+export class FederationRegistry {
+    upstreams = new Map();
+    add(client) {
+        if (this.upstreams.has(client.name)) {
+            throw new Error(`federation upstream ${client.name} already registered`);
+        }
+        this.upstreams.set(client.name, client);
+    }
+    remove(name) {
+        this.upstreams.delete(name);
+    }
+    get(name) {
+        return this.upstreams.get(name);
+    }
+    list() {
+        return [...this.upstreams.values()];
+    }
+    /** Flat, namespaced tool view across every connected upstream. */
+    getNamespacedTools() {
+        const out = [];
+        for (const client of this.upstreams.values()) {
+            out.push(...client.getTools());
+        }
+        return out;
+    }
+    /** Dispatch a namespaced tool call to the right upstream. The
+     *  namespaced name MUST exist in the catalog; the caller (the
+     *  registerTool wrapper in createMcpServer) is responsible for not
+     *  routing tools that aren't there. */
+    async callNamespacedTool(namespacedName, args) {
+        for (const client of this.upstreams.values()) {
+            const match = client.getTools().find((t) => t.namespacedName === namespacedName);
+            if (match)
+                return client.callTool(match.upstreamName, args);
+        }
+        throw new Error(`federated tool not found: ${namespacedName}`);
+    }
+    async closeAll() {
+        await Promise.all([...this.upstreams.values()].map((c) => c.close()));
+        this.upstreams.clear();
+    }
+}
+export function parseFederationEnv(env = process.env) {
+    const raw = env.OMCP_FEDERATION_UPSTREAMS?.trim();
+    if (!raw)
+        return [];
+    const entries = [];
+    for (const part of raw.split(",")) {
+        const trimmed = part.trim();
+        if (!trimmed)
+            continue;
+        const eq = trimmed.indexOf("=");
+        if (eq < 0) {
+            console.warn(`OMCP_FEDERATION_UPSTREAMS entry "${trimmed}" missing "=" — skipping`);
+            continue;
+        }
+        const name = trimmed.slice(0, eq).trim();
+        const url = trimmed.slice(eq + 1).trim();
+        if (!/^[a-z][a-z0-9_-]*$/i.test(name)) {
+            console.warn(`OMCP_FEDERATION_UPSTREAMS entry name "${name}" is invalid — skipping`);
+            continue;
+        }
+        if (!/^https?:\/\//.test(url)) {
+            console.warn(`OMCP_FEDERATION_UPSTREAMS entry "${name}" url "${url}" must start with http:// or https:// — skipping`);
+            continue;
+        }
+        const tokenEnv = `OMCP_FEDERATION_TOKEN_${name.toUpperCase().replace(/[-.]/g, "_")}`;
+        const bearerToken = env[tokenEnv]?.trim() || undefined;
+        entries.push({ name, url, bearerToken });
+    }
+    return entries;
+}

package/dist/federation/registry.test.d.ts

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