@thotischner/observability-mcp 1.8.1 → 3.0.0

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 {};

package/dist/federation/registry.test.js

@@ -0,0 +1,130 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { FederationRegistry, parseFederationEnv } from "./registry.js";
+// Minimal fake UpstreamClient. The real Client requires a live HTTP
+// upstream; this fake satisfies the shape FederationRegistry actually
+// touches.
+class FakeUpstream {
+    name;
+    url = "https://fake/mcp";
+    namespacePrefix;
+    tools;
+    callLog = [];
+    closed = false;
+    constructor(name, prefix, toolNames) {
+        this.name = name;
+        this.namespacePrefix = prefix;
+        this.tools = toolNames.map((n) => ({
+            namespacedName: `${prefix}.${n}`,
+            upstreamName: n,
+            sourceName: name,
+            description: `upstream tool ${n}`,
+            inputSchema: {},
+        }));
+    }
+    getTools() {
+        return [...this.tools];
+    }
+    async callTool(upstreamName, args) {
+        this.callLog.push({ tool: upstreamName, args });
+        return { result: { echo: upstreamName, args } };
+    }
+    async close() {
+        this.closed = true;
+    }
+    getStatus() {
+        return { status: "ready", toolCount: this.tools.length };
+    }
+    async connect() {
+        /* no-op for tests */
+    }
+    async refresh() {
+        /* no-op */
+    }
+    log() {
+        return this.callLog;
+    }
+}
+function fakeAsClient(f) {
+    return f;
+}
+test("FederationRegistry: add + list + get", () => {
+    const reg = new FederationRegistry();
+    const u = new FakeUpstream("a", "a", ["x"]);
+    reg.add(fakeAsClient(u));
+    assert.equal(reg.list().length, 1);
+    assert.equal(reg.get("a")?.name, "a");
+});
+test("FederationRegistry: add of duplicate name throws", () => {
+    const reg = new FederationRegistry();
+    reg.add(fakeAsClient(new FakeUpstream("a", "a", [])));
+    assert.throws(() => reg.add(fakeAsClient(new FakeUpstream("a", "a", []))), /already registered/);
+});
+test("FederationRegistry: getNamespacedTools flattens across upstreams with stable order", () => {
+    const reg = new FederationRegistry();
+    reg.add(fakeAsClient(new FakeUpstream("a", "a", ["x", "y"])));
+    reg.add(fakeAsClient(new FakeUpstream("b", "b", ["z"])));
+    const names = reg.getNamespacedTools().map((t) => t.namespacedName);
+    assert.deepEqual(names, ["a.x", "a.y", "b.z"]);
+});
+test("FederationRegistry: callNamespacedTool routes to the owning upstream", async () => {
+    const a = new FakeUpstream("a", "a", ["x"]);
+    const b = new FakeUpstream("b", "b", ["z"]);
+    const reg = new FederationRegistry();
+    reg.add(fakeAsClient(a));
+    reg.add(fakeAsClient(b));
+    await reg.callNamespacedTool("b.z", { foo: 1 });
+    assert.equal(a.log().length, 0);
+    assert.deepEqual(b.log(), [{ tool: "z", args: { foo: 1 } }]);
+});
+test("FederationRegistry: callNamespacedTool throws on unknown tool", async () => {
+    const reg = new FederationRegistry();
+    reg.add(fakeAsClient(new FakeUpstream("a", "a", ["x"])));
+    await assert.rejects(() => reg.callNamespacedTool("a.nope", {}), /not found/);
+});
+test("FederationRegistry: remove + closeAll", async () => {
+    const a = new FakeUpstream("a", "a", []);
+    const reg = new FederationRegistry();
+    reg.add(fakeAsClient(a));
+    reg.remove("a");
+    assert.equal(reg.list().length, 0);
+    const b = new FakeUpstream("b", "b", []);
+    reg.add(fakeAsClient(b));
+    await reg.closeAll();
+    assert.equal(b.closed, true);
+    assert.equal(reg.list().length, 0);
+});
+test("parseFederationEnv: returns [] for missing / empty", () => {
+    assert.deepEqual(parseFederationEnv({}), []);
+    assert.deepEqual(parseFederationEnv({ OMCP_FEDERATION_UPSTREAMS: "" }), []);
+    assert.deepEqual(parseFederationEnv({ OMCP_FEDERATION_UPSTREAMS: "   " }), []);
+});
+test("parseFederationEnv: parses name=url comma-separated entries", () => {
+    const parsed = parseFederationEnv({
+        OMCP_FEDERATION_UPSTREAMS: "a=https://gw.a/mcp,b=https://gw.b/mcp",
+    });
+    assert.deepEqual(parsed, [
+        { name: "a", url: "https://gw.a/mcp", bearerToken: undefined },
+        { name: "b", url: "https://gw.b/mcp", bearerToken: undefined },
+    ]);
+});
+test("parseFederationEnv: picks up bearer token per OMCP_FEDERATION_TOKEN_<NAME>", () => {
+    const parsed = parseFederationEnv({
+        OMCP_FEDERATION_UPSTREAMS: "prod=https://gw.prod/mcp",
+        OMCP_FEDERATION_TOKEN_PROD: "secret-token-xyz",
+    });
+    assert.equal(parsed[0]?.bearerToken, "secret-token-xyz");
+});
+test("parseFederationEnv: skips malformed entries with a warning, keeps the rest", () => {
+    const parsed = parseFederationEnv({
+        OMCP_FEDERATION_UPSTREAMS: "good=https://gw/mcp,no-equals,bad-url=ftp://x,a=https://b/mcp",
+    });
+    // Only `good=` and `a=` survive
+    assert.deepEqual(parsed.map((p) => p.name), ["good", "a"]);
+});
+test("parseFederationEnv: rejects invalid names (must start with letter)", () => {
+    const parsed = parseFederationEnv({
+        OMCP_FEDERATION_UPSTREAMS: "1bad=https://x/mcp,_also=https://y/mcp,ok=https://z/mcp",
+    });
+    assert.deepEqual(parsed.map((p) => p.name), ["ok"]);
+});

package/dist/federation/upstream.d.ts

@@ -0,0 +1,60 @@
+export interface UpstreamConfig {
+    /** Stable source name (used in the namespace prefix + audit entries). */
+    name: string;
+    /** Upstream Streamable HTTP URL (must end at /mcp). */
+    url: string;
+    /** Static bearer token sent on every outbound call. */
+    bearerToken?: string;
+    /** Tool-name prefix; default = source name. Resulting registered
+     *  tool name is `<prefix>.<upstream-tool-name>`. */
+    namespacePrefix?: string;
+    /** ms between automatic catalog refreshes. Default 5 minutes;
+     *  0 disables auto-refresh (manual refresh() only). */
+    refreshIntervalMs?: number;
+}
+export interface UpstreamToolInfo {
+    /** Local namespaced name: `<prefix>.<upstreamName>`. */
+    namespacedName: string;
+    /** Original name on the upstream. */
+    upstreamName: string;
+    /** Upstream source name (audit attribution + diagnostics). */
+    sourceName: string;
+    /** Tool description as the upstream advertises it. */
+    description: string;
+    /** Upstream's inputSchema, forwarded verbatim. */
+    inputSchema: unknown;
+}
+export type UpstreamStatus = "connecting" | "ready" | "degraded" | "disconnected";
+export declare class UpstreamClient {
+    readonly name: string;
+    readonly url: string;
+    readonly namespacePrefix: string;
+    private bearerToken?;
+    private client?;
+    private transport?;
+    private toolsCache;
+    private status;
+    private lastError?;
+    private refreshTimer?;
+    private refreshIntervalMs;
+    constructor(cfg: UpstreamConfig);
+    getStatus(): {
+        status: UpstreamStatus;
+        lastError?: string;
+        toolCount: number;
+    };
+    /** Cached catalog (read-only). */
+    getTools(): UpstreamToolInfo[];
+    /** Connect + initial catalog fetch. Logs failures and leaves the
+     *  client in `degraded` so the catalog stays empty rather than
+     *  blocking startup. Re-runnable. */
+    connect(): Promise<void>;
+    /** Re-fetch the upstream tool catalog. Throws on failure so the
+     *  caller can choose to degrade or retry. */
+    refresh(): Promise<void>;
+    /** Forward a callTool request to the upstream by upstream-tool name
+     *  (NOT the namespaced name — the registry strips the prefix before
+     *  calling here). */
+    callTool(upstreamName: string, args: unknown): Promise<unknown>;
+    close(): Promise<void>;
+}

package/dist/federation/upstream.js

@@ -0,0 +1,114 @@
+// Upstream MCP federation client.
+//
+// One UpstreamClient per remote MCP gateway. On connect() it runs the
+// MCP initialize handshake, fetches tools/list, and caches the catalog
+// locally. callTool() forwards a request to the upstream and returns
+// its CallToolResult verbatim.
+//
+// Transport: Streamable HTTP only in this slice. Stdio + WebSocket
+// upstreams are deferred (the SDK already provides client transports
+// for both; wiring them is mechanical once the routing logic settles).
+//
+// Auth forwarding modes:
+//   - "none" — no auth header on outbound calls
+//   - "bearer" — static OMCP_FEDERATION_TOKEN_<NAME> sent as Bearer
+//
+// OIDC + UAID passthrough are deferred — they require a per-request
+// identity hand-off the federation manager doesn't carry today.
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+export class UpstreamClient {
+    name;
+    url;
+    namespacePrefix;
+    bearerToken;
+    client;
+    transport;
+    toolsCache = [];
+    status = "disconnected";
+    lastError;
+    refreshTimer;
+    refreshIntervalMs;
+    constructor(cfg) {
+        this.name = cfg.name;
+        this.url = cfg.url;
+        this.namespacePrefix = cfg.namespacePrefix ?? cfg.name;
+        this.bearerToken = cfg.bearerToken;
+        this.refreshIntervalMs = cfg.refreshIntervalMs ?? 5 * 60 * 1000;
+    }
+    getStatus() {
+        return { status: this.status, lastError: this.lastError, toolCount: this.toolsCache.length };
+    }
+    /** Cached catalog (read-only). */
+    getTools() {
+        return [...this.toolsCache];
+    }
+    /** Connect + initial catalog fetch. Logs failures and leaves the
+     *  client in `degraded` so the catalog stays empty rather than
+     *  blocking startup. Re-runnable. */
+    async connect() {
+        this.status = "connecting";
+        try {
+            const url = new URL(this.url);
+            const init = { headers: {} };
+            if (this.bearerToken) {
+                init.headers["Authorization"] = `Bearer ${this.bearerToken}`;
+            }
+            this.transport = new StreamableHTTPClientTransport(url, { requestInit: init });
+            this.client = new Client({ name: "observability-mcp-federation", version: "1" }, { capabilities: {} });
+            await this.client.connect(this.transport);
+            await this.refresh();
+            this.status = "ready";
+            this.lastError = undefined;
+            if (this.refreshIntervalMs > 0) {
+                this.refreshTimer = setInterval(() => {
+                    this.refresh().catch((err) => {
+                        console.warn("UpstreamClient %s: background refresh failed: %s", this.name, err instanceof Error ? err.message : String(err));
+                    });
+                }, this.refreshIntervalMs).unref?.();
+            }
+        }
+        catch (err) {
+            this.status = "degraded";
+            this.lastError = err instanceof Error ? err.message : String(err);
+            console.warn("UpstreamClient %s: connect failed (%s). Federation continues without this upstream.", this.name, this.lastError);
+        }
+    }
+    /** Re-fetch the upstream tool catalog. Throws on failure so the
+     *  caller can choose to degrade or retry. */
+    async refresh() {
+        if (!this.client)
+            throw new Error(`upstream ${this.name} not connected`);
+        const result = await this.client.listTools({});
+        this.toolsCache = (result.tools ?? []).map((t) => ({
+            namespacedName: `${this.namespacePrefix}.${t.name}`,
+            upstreamName: t.name,
+            sourceName: this.name,
+            description: t.description ?? "",
+            inputSchema: t.inputSchema,
+        }));
+    }
+    /** Forward a callTool request to the upstream by upstream-tool name
+     *  (NOT the namespaced name — the registry strips the prefix before
+     *  calling here). */
+    async callTool(upstreamName, args) {
+        if (!this.client) {
+            throw new Error(`upstream ${this.name} is ${this.status}`);
+        }
+        return this.client.callTool({
+            name: upstreamName,
+            arguments: (args ?? {}),
+        });
+    }
+    async close() {
+        if (this.refreshTimer)
+            clearInterval(this.refreshTimer);
+        try {
+            await this.client?.close();
+        }
+        catch {
+            /* socket may already be down */
+        }
+        this.status = "disconnected";
+    }
+}