@thotischner/observability-mcp 1.7.1 → 3.0.0

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";
+    }
+}