@thotischner/observability-mcp 1.8.1 → 3.0.1

package/dist/federation/upstream.js

@@ -0,0 +1,162 @@
+// 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.
+//
+// Transports:
+//   - "http"  — Streamable HTTP to an upstream gateway URL (default).
+//   - "stdio" — spawn a child process that speaks MCP over its stdio
+//               channels. The classic MCP transport, useful when the
+//               upstream is a CLI-style server (omcp inspector-config,
+//               a local-only MCP, an in-cluster sidecar).
+//   - "ws"    — WebSocket to a ws:// or wss:// URL. Useful when the
+//               upstream gateway exposes MCP via the WS subprotocol
+//               rather than streamable HTTP. No bearer-auth header
+//               (the SDK transport only accepts a URL); operators
+//               that need auth append it as a query string or run
+//               the gateway behind an authenticating reverse proxy.
+//
+// Auth forwarding modes:
+//   - "none" — no auth header on outbound calls
+//   - "bearer" — static OMCP_FEDERATION_TOKEN_<NAME> sent as Bearer
+//                (HTTP transport only — stdio doesn't have HTTP headers)
+//
+// 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";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { WebSocketClientTransport } from "@modelcontextprotocol/sdk/client/websocket.js";
+export class UpstreamClient {
+    name;
+    /** Empty-string for stdio (no remote URL); kept on the public surface
+     *  so the UI doesn't have to special-case the transport kind. */
+    url;
+    namespacePrefix;
+    transportKind;
+    cfg;
+    client;
+    // `unknown` because the SDK exposes a different concrete type per
+    // transport. Federation only talks to the transport via the SDK
+    // Client object, so the concrete type isn't needed here.
+    transport;
+    toolsCache = [];
+    status = "disconnected";
+    lastError;
+    refreshTimer;
+    refreshIntervalMs;
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.name = cfg.name;
+        this.transportKind =
+            cfg.transport === "stdio" ? "stdio" :
+                cfg.transport === "ws" ? "ws" :
+                    "http";
+        this.url =
+            this.transportKind === "stdio" ? `stdio:${cfg.command}` :
+                this.transportKind === "ws" ? cfg.url :
+                    cfg.url;
+        this.namespacePrefix = cfg.namespacePrefix ?? cfg.name;
+        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 {
+            this.transport = this.buildTransport();
+            this.client = new Client({ name: "observability-mcp-federation", version: "1" }, { capabilities: {} });
+            // SDK Client.connect accepts any Transport implementation; the
+            // injected test transport just needs the start()/send()/close()
+            // contract — the type assertion sidesteps each concrete class.
+            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";
+    }
+    // --- internals ----------------------------------------------------
+    buildTransport() {
+        // Test path: a pre-built transport short-circuits the spawn / fetch.
+        if (this.cfg._transport)
+            return this.cfg._transport;
+        if (this.transportKind === "stdio") {
+            const cfg = this.cfg;
+            return new StdioClientTransport({
+                command: cfg.command,
+                args: cfg.args ?? [],
+                env: cfg.env,
+            });
+        }
+        if (this.transportKind === "ws") {
+            const cfg = this.cfg;
+            return new WebSocketClientTransport(new URL(cfg.url));
+        }
+        const cfg = this.cfg;
+        const url = new URL(cfg.url);
+        const init = { headers: {} };
+        if (cfg.bearerToken) {
+            init.headers["Authorization"] = `Bearer ${cfg.bearerToken}`;
+        }
+        return new StreamableHTTPClientTransport(url, { requestInit: init });
+    }
+}

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

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

package/dist/federation/upstream.test.js

@@ -0,0 +1,118 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { UpstreamClient } from "./upstream.js";
+test("UpstreamClient: HTTP config — transportKind='http', url surfaced", () => {
+    const cfg = {
+        name: "remote",
+        url: "https://gw.example.com/mcp",
+        bearerToken: "t0k",
+    };
+    const c = new UpstreamClient(cfg);
+    assert.equal(c.transportKind, "http");
+    assert.equal(c.url, "https://gw.example.com/mcp");
+    assert.equal(c.namespacePrefix, "remote");
+    assert.deepEqual(c.getTools(), []);
+});
+test("UpstreamClient: stdio config — transportKind='stdio', url shows command", () => {
+    const cfg = {
+        transport: "stdio",
+        name: "local-mcp",
+        command: "/usr/local/bin/mcp",
+        args: ["--config", "/etc/mcp.yaml"],
+    };
+    const c = new UpstreamClient(cfg);
+    assert.equal(c.transportKind, "stdio");
+    assert.equal(c.url, "stdio:/usr/local/bin/mcp");
+    assert.equal(c.namespacePrefix, "local-mcp");
+});
+test("UpstreamClient: stdio config respects custom namespacePrefix", () => {
+    const cfg = {
+        transport: "stdio",
+        name: "weather",
+        command: "weather-mcp",
+        namespacePrefix: "weather.local",
+    };
+    const c = new UpstreamClient(cfg);
+    assert.equal(c.namespacePrefix, "weather.local");
+});
+test("UpstreamClient: explicit transport='http' is also accepted", () => {
+    const cfg = {
+        transport: "http",
+        name: "gw",
+        url: "https://gw.example.com/mcp",
+    };
+    const c = new UpstreamClient(cfg);
+    assert.equal(c.transportKind, "http");
+});
+test("UpstreamClient: ws transport surfaces the ws:// URL", () => {
+    const cfg = {
+        transport: "ws",
+        name: "gw",
+        url: "wss://gw.example.com/mcp/ws",
+    };
+    const c = new UpstreamClient(cfg);
+    assert.equal(c.transportKind, "ws");
+    assert.equal(c.url, "wss://gw.example.com/mcp/ws");
+});
+test("UpstreamClient: empty args defaults to [] on stdio", () => {
+    const cfg = {
+        transport: "stdio",
+        name: "x",
+        command: "x",
+    };
+    const c = new UpstreamClient(cfg);
+    // Just verifies construction doesn't throw on a minimal stdio config.
+    assert.equal(c.transportKind, "stdio");
+});
+test("UpstreamClient: getStatus initial state", () => {
+    const c = new UpstreamClient({ name: "x", url: "https://x/mcp" });
+    const s = c.getStatus();
+    assert.equal(s.status, "disconnected");
+    assert.equal(s.toolCount, 0);
+    assert.equal(s.lastError, undefined);
+});
+test("UpstreamClient: connect uses injected _transport instead of spawning / fetching", async () => {
+    // Build a minimal MCP Transport stub that also COMPLETES the
+    // initialize handshake — when the SDK Client sends a JSON-RPC
+    // request, we synthesise a matching response on onmessage so the
+    // initialize promise resolves quickly (no 60s SDK timeout).
+    let started = false;
+    let sentMessages = 0;
+    const fakeTransport = {
+        start: async () => { started = true; },
+        send: async (msg) => {
+            sentMessages += 1;
+            if (msg?.method === "initialize" && msg?.id !== undefined) {
+                queueMicrotask(() => {
+                    fakeTransport.onmessage?.({
+                        jsonrpc: "2.0",
+                        id: msg.id,
+                        result: { protocolVersion: "2024-11-05", capabilities: {}, serverInfo: { name: "fake", version: "1" } },
+                    });
+                });
+            }
+            else if (msg?.method === "tools/list" && msg?.id !== undefined) {
+                queueMicrotask(() => {
+                    fakeTransport.onmessage?.({ jsonrpc: "2.0", id: msg.id, result: { tools: [] } });
+                });
+            }
+        },
+        close: async () => { },
+        onclose: undefined,
+        onerror: undefined,
+        onmessage: undefined,
+    };
+    const c = new UpstreamClient({
+        name: "injected",
+        url: "https://ignored.example/mcp",
+        refreshIntervalMs: 0,
+        _transport: fakeTransport,
+    });
+    await c.connect();
+    await c.close();
+    assert.equal(started, true, "fake transport.start() should have been called");
+    assert.ok(sentMessages >= 1, "fake transport.send() should have received initialize");
+    // Status reaches "ready" only when initialize + tools/list both succeed
+    // — confirms our injected transport drove the whole handshake.
+    // (connect-time errors leave it in "degraded".)
+});