@thotischner/observability-mcp 3.0.0 → 3.0.1

package/dist/connectors/manifest-hooks.test.js

@@ -0,0 +1,206 @@
+// Manifest-driven hook auto-registration (Q10).
+//
+// Stages a synthetic plugin directory with:
+//   - package.json + manifest.json declaring hooks[]
+//   - index.js exporting a no-op connector factory
+//   - hooks/<kind>.js modules exporting handler defaults
+// Runs PluginLoader (with VERIFY_PLUGINS off — we test the
+// hook wiring, not the trust-root path) and asserts the
+// HookRegistry now has the entries the manifest declared.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { PluginLoader } from "./loader.js";
+import { HookRegistry } from "../sdk/hooks.js";
+function stagePlugin(opts) {
+    const stage = mkdtempSync(join(tmpdir(), "omcp-plugin-hooks-"));
+    const root = join(stage, opts.name);
+    mkdirSync(root, { recursive: true });
+    writeFileSync(join(root, "package.json"), JSON.stringify({
+        name: `@observability-mcp/connector-${opts.name}`,
+        observabilityMcp: { kind: "connector", name: opts.name, manifest: "./manifest.json" },
+        main: "./index.js",
+    }));
+    writeFileSync(join(root, "manifest.json"), JSON.stringify({
+        schemaVersion: 1,
+        name: opts.name,
+        displayName: opts.name,
+        version: "1.0.0",
+        description: "test plugin",
+        signalTypes: ["topology"],
+        capabilities: { listServices: true },
+        compat: { serverVersion: ">=3.0.0" },
+        hooks: opts.hooks?.map((h) => ({
+            kind: h.kind,
+            module: h.module,
+            priority: h.priority,
+            mode: h.mode,
+        })),
+    }));
+    // Tiny no-op connector factory.
+    writeFileSync(join(root, "index.js"), opts.indexJs ??
+        `export default function create() {
+        return {
+          type: "${opts.name}",
+          signalType: "topology",
+          name: "${opts.name}",
+          async connect() {},
+          async healthCheck() { return { status: "down", latencyMs: 0 }; },
+          async disconnect() {},
+          getDefaultMetrics() { return []; },
+          getMetrics() { return []; },
+          async listServices() { return []; },
+        };
+      }`);
+    // Hook modules — each writes a marker into the global for assertions.
+    for (const h of opts.hooks ?? []) {
+        const hookPath = join(root, h.module);
+        mkdirSync(join(hookPath, ".."), { recursive: true });
+        writeFileSync(hookPath, h.body ??
+            `export default async function handler(ctx, payload) {
+          globalThis.__omcp_test_hook_calls = (globalThis.__omcp_test_hook_calls ?? []);
+          globalThis.__omcp_test_hook_calls.push({ plugin: ctx.principal, kind: ctx.kind, target: ctx.target });
+          return { allow: true, payload };
+        }`);
+    }
+    return stage;
+}
+test("PluginLoader: manifest hooks auto-register on plugin load", async () => {
+    const stage = stagePlugin({
+        name: "alpha",
+        hooks: [
+            { kind: "tool_pre_invoke", module: "hooks/pre.mjs", priority: 50 },
+            { kind: "tool_post_invoke", module: "hooks/post.mjs" },
+        ],
+    });
+    const registry = new HookRegistry();
+    const loader = new PluginLoader({
+        pluginsDir: stage,
+        verify: false,
+        hookRegistry: registry,
+    });
+    await loader.load();
+    const pre = registry.list("tool_pre_invoke");
+    const post = registry.list("tool_post_invoke");
+    assert.equal(pre.length, 1);
+    assert.equal(pre[0].pluginName, "alpha");
+    assert.equal(pre[0].priority, 50);
+    assert.equal(post.length, 1);
+    assert.equal(post[0].pluginName, "alpha");
+    assert.equal(post[0].priority, 100); // default
+});
+test("PluginLoader: hook handlers fire end-to-end through HookRegistry", async () => {
+    delete globalThis.__omcp_test_hook_calls;
+    const stage = stagePlugin({
+        name: "beta",
+        hooks: [{ kind: "tool_pre_invoke", module: "hooks/pre.mjs" }],
+    });
+    const registry = new HookRegistry();
+    const loader = new PluginLoader({ pluginsDir: stage, verify: false, hookRegistry: registry });
+    await loader.load();
+    const result = await registry.fire("tool_pre_invoke", { principal: "alice", tenant: "default", kind: "tool_pre_invoke", target: "tool.x" }, { args: { foo: 1 } });
+    assert.equal(result.allow, true);
+    const calls = globalThis.__omcp_test_hook_calls;
+    assert.ok(calls && calls.length === 1, "hook should have fired once");
+});
+test("PluginLoader: missing hook module is skipped with a warning, others still register", async () => {
+    // Stage one good hook normally, then rewrite the manifest to ALSO
+    // reference a sibling module path that doesn't exist on disk. The
+    // loader must skip the missing one (existsSync branch) and still
+    // register the good one.
+    const stage = stagePlugin({
+        name: "gamma",
+        hooks: [{ kind: "tool_post_invoke", module: "hooks/post.mjs" }],
+    });
+    const manifestPath = join(stage, "gamma", "manifest.json");
+    const raw = JSON.parse(readFileSync(manifestPath, "utf8"));
+    raw.hooks = [
+        { kind: "tool_pre_invoke", module: "hooks/genuinely-missing.mjs" },
+        { kind: "tool_post_invoke", module: "hooks/post.mjs" },
+    ];
+    writeFileSync(manifestPath, JSON.stringify(raw));
+    const registry = new HookRegistry();
+    await new PluginLoader({ pluginsDir: stage, verify: false, hookRegistry: registry }).load();
+    // The missing pre hook was skipped; the good post hook registered.
+    assert.equal(registry.list("tool_pre_invoke").length, 0);
+    assert.equal(registry.list("tool_post_invoke").length, 1);
+});
+test("PluginLoader: hook module path that escapes the plugin root is rejected", async () => {
+    // Stage a plugin whose manifest tries to reference a path with `..`
+    // — the loader must refuse to import it.
+    const stage = mkdtempSync(join(tmpdir(), "omcp-plugin-escape-"));
+    const root = join(stage, "evil");
+    mkdirSync(root, { recursive: true });
+    writeFileSync(join(root, "package.json"), JSON.stringify({
+        name: "@observability-mcp/connector-evil",
+        observabilityMcp: { kind: "connector", name: "evil", manifest: "./manifest.json" },
+        main: "./index.js",
+    }));
+    writeFileSync(join(root, "manifest.json"), JSON.stringify({
+        schemaVersion: 1,
+        name: "evil",
+        displayName: "evil",
+        version: "1.0.0",
+        description: "x",
+        signalTypes: ["topology"],
+        capabilities: { listServices: true },
+        hooks: [{ kind: "tool_pre_invoke", module: "../escape.mjs" }],
+    }));
+    writeFileSync(join(root, "index.js"), `export default function create() {
+      return {
+        type: "evil", signalType: "topology", name: "evil",
+        async connect() {},
+        async healthCheck() { return { status: "down", latencyMs: 0 }; },
+        async disconnect() {},
+        getDefaultMetrics() { return []; },
+        getMetrics() { return []; },
+        async listServices() { return []; },
+      };
+    }`);
+    // Stage a file outside the plugin root the manifest references.
+    writeFileSync(join(stage, "escape.mjs"), `export default async () => ({ allow: false, reason: "should never run" });`);
+    const registry = new HookRegistry();
+    const loader = new PluginLoader({ pluginsDir: stage, verify: false, hookRegistry: registry });
+    await loader.load();
+    // The escape hook was refused; nothing in the registry.
+    assert.equal(registry.list("tool_pre_invoke").length, 0);
+});
+test("PluginLoader: hot-reload — re-loading replaces prior hook registrations", async () => {
+    const stage = stagePlugin({
+        name: "delta",
+        hooks: [{ kind: "tool_pre_invoke", module: "hooks/pre.mjs", priority: 10 }],
+    });
+    const registry = new HookRegistry();
+    await new PluginLoader({ pluginsDir: stage, verify: false, hookRegistry: registry }).load();
+    assert.equal(registry.list("tool_pre_invoke").length, 1);
+    // Re-load (same stage, same plugin) — registry should still hold
+    // exactly one entry for tool_pre_invoke owned by delta. The loader
+    // calls unregisterPlugin first, then re-registers.
+    await new PluginLoader({ pluginsDir: stage, verify: false, hookRegistry: registry }).load();
+    const after = registry.list("tool_pre_invoke");
+    assert.equal(after.length, 1);
+    assert.equal(after[0].pluginName, "delta");
+});
+test("PluginLoader: no hookRegistry passed → hooks are silently ignored (back-compat)", async () => {
+    const stage = stagePlugin({
+        name: "epsilon",
+        hooks: [{ kind: "tool_pre_invoke", module: "hooks/pre.mjs" }],
+    });
+    // No hookRegistry — load() must not throw.
+    const loader = new PluginLoader({ pluginsDir: stage, verify: false });
+    await loader.load();
+    assert.ok(loader.has("epsilon"));
+});
+test("PluginLoader: hook with no default export is skipped", async () => {
+    const stage = stagePlugin({
+        name: "zeta",
+        hooks: [{ kind: "tool_pre_invoke", module: "hooks/noexport.mjs" }],
+    });
+    // Overwrite the noexport.mjs file to remove default export.
+    writeFileSync(join(stage, "zeta", "hooks", "noexport.mjs"), "export const meta = 'no handler here';");
+    const registry = new HookRegistry();
+    await new PluginLoader({ pluginsDir: stage, verify: false, hookRegistry: registry }).load();
+    assert.equal(registry.list("tool_pre_invoke").length, 0);
+});

package/dist/federation/registry.d.ts

@@ -18,15 +18,37 @@ export declare class FederationRegistry {
  * Parse the OMCP_FEDERATION_UPSTREAMS env into a list of upstream
  * configs. Shape:
  *
- *   "name1=https://gw.a/mcp,name2=https://gw.b/mcp"
+ *   "a=https://gw.a/mcp,b=stdio:/usr/bin/mcp arg1,c=wss://gw.c/mcp/ws"
  *
- * Each upstream's bearer token is read from
- * OMCP_FEDERATION_TOKEN_<UPPERCASE-NAME> (dots → underscores), so
- * tokens stay out of the URL list itself.
+ * Transport selection:
+ *   - `https?://`   → HTTP (Streamable). Bearer token from
+ *                     OMCP_FEDERATION_TOKEN_<UPPERCASE-NAME>.
+ *   - `ws://`/`wss://` → WebSocket. No bearer header (the SDK
+ *                     transport only accepts a URL); embed auth
+ *                     in the URL or front the gateway with a
+ *                     proxy.
+ *   - `stdio:<cmd>` → spawn a child process; `\` escapes spaces
+ *                     in the command/argv list.
+ *
+ * Tokens never appear in the URL list itself for HTTP — kept
+ * separate so they don't leak into logs / audit entries.
  */
-export interface ParsedUpstream {
+export interface ParsedUpstreamHttp {
+    kind: "http";
     name: string;
     url: string;
     bearerToken?: string;
 }
+export interface ParsedUpstreamStdio {
+    kind: "stdio";
+    name: string;
+    command: string;
+    args: string[];
+}
+export interface ParsedUpstreamWebsocket {
+    kind: "ws";
+    name: string;
+    url: string;
+}
+export type ParsedUpstream = ParsedUpstreamHttp | ParsedUpstreamStdio | ParsedUpstreamWebsocket;
 export declare function parseFederationEnv(env?: NodeJS.ProcessEnv): ParsedUpstream[];

package/dist/federation/registry.js

@@ -45,6 +45,38 @@ export class FederationRegistry {
         this.upstreams.clear();
     }
 }
+/** Split a "command arg1 arg2" string honouring backslash escapes
+ *  so an operator can embed a literal space with `\ `. Nothing
+ *  fancier — we explicitly don't run a shell, so quoting wouldn't
+ *  apply uniformly. */
+function splitCommand(spec) {
+    const tokens = [];
+    let cur = "";
+    let esc = false;
+    for (const ch of spec) {
+        if (esc) {
+            cur += ch;
+            esc = false;
+            continue;
+        }
+        if (ch === "\\") {
+            esc = true;
+            continue;
+        }
+        if (ch === " " || ch === "\t") {
+            if (cur) {
+                tokens.push(cur);
+                cur = "";
+            }
+            continue;
+        }
+        cur += ch;
+    }
+    if (cur)
+        tokens.push(cur);
+    const [command = "", ...args] = tokens;
+    return { command, args };
+}
 export function parseFederationEnv(env = process.env) {
     const raw = env.OMCP_FEDERATION_UPSTREAMS?.trim();
     if (!raw)
@@ -60,18 +92,31 @@ export function parseFederationEnv(env = process.env) {
             continue;
         }
         const name = trimmed.slice(0, eq).trim();
-        const url = trimmed.slice(eq + 1).trim();
+        const spec = 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`);
+        if (spec.startsWith("stdio:")) {
+            const { command, args } = splitCommand(spec.slice("stdio:".length).trim());
+            if (!command) {
+                console.warn(`OMCP_FEDERATION_UPSTREAMS entry "${name}" stdio: missing command — skipping`);
+                continue;
+            }
+            entries.push({ kind: "stdio", name, command, args });
+            continue;
+        }
+        if (/^wss?:\/\//.test(spec)) {
+            entries.push({ kind: "ws", name, url: spec });
+            continue;
+        }
+        if (!/^https?:\/\//.test(spec)) {
+            console.warn(`OMCP_FEDERATION_UPSTREAMS entry "${name}" url "${spec}" must start with http://, https://, ws://, wss:// (or stdio:) — skipping`);
             continue;
         }
         const tokenEnv = `OMCP_FEDERATION_TOKEN_${name.toUpperCase().replace(/[-.]/g, "_")}`;
         const bearerToken = env[tokenEnv]?.trim() || undefined;
-        entries.push({ name, url, bearerToken });
+        entries.push({ kind: "http", name, url: spec, bearerToken });
     }
     return entries;
 }

package/dist/federation/registry.test.js

@@ -104,8 +104,8 @@ test("parseFederationEnv: parses name=url comma-separated entries", () => {
         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 },
+        { kind: "http", name: "a", url: "https://gw.a/mcp", bearerToken: undefined },
+        { kind: "http", name: "b", url: "https://gw.b/mcp", bearerToken: undefined },
     ]);
 });
 test("parseFederationEnv: picks up bearer token per OMCP_FEDERATION_TOKEN_<NAME>", () => {
@@ -113,7 +113,83 @@ test("parseFederationEnv: picks up bearer token per OMCP_FEDERATION_TOKEN_<NAME>
         OMCP_FEDERATION_UPSTREAMS: "prod=https://gw.prod/mcp",
         OMCP_FEDERATION_TOKEN_PROD: "secret-token-xyz",
     });
-    assert.equal(parsed[0]?.bearerToken, "secret-token-xyz");
+    assert.equal(parsed[0]?.kind, "http");
+    if (parsed[0]?.kind === "http") {
+        assert.equal(parsed[0].bearerToken, "secret-token-xyz");
+    }
+});
+test("parseFederationEnv: stdio:<command> entries parse with kind=stdio", () => {
+    const parsed = parseFederationEnv({
+        OMCP_FEDERATION_UPSTREAMS: "local=stdio:/usr/local/bin/mcp",
+    });
+    assert.equal(parsed.length, 1);
+    assert.deepEqual(parsed[0], {
+        kind: "stdio",
+        name: "local",
+        command: "/usr/local/bin/mcp",
+        args: [],
+    });
+});
+test("parseFederationEnv: stdio command args split on whitespace", () => {
+    const parsed = parseFederationEnv({
+        OMCP_FEDERATION_UPSTREAMS: "weather=stdio:node weather-mcp.js --port 0",
+    });
+    assert.equal(parsed[0]?.kind, "stdio");
+    if (parsed[0]?.kind === "stdio") {
+        assert.equal(parsed[0].command, "node");
+        assert.deepEqual(parsed[0].args, ["weather-mcp.js", "--port", "0"]);
+    }
+});
+test("parseFederationEnv: backslash-escapes preserve spaces in stdio commands", () => {
+    const parsed = parseFederationEnv({
+        OMCP_FEDERATION_UPSTREAMS: "x=stdio:/opt/path\\ with\\ spaces/mcp arg1",
+    });
+    assert.equal(parsed[0]?.kind, "stdio");
+    if (parsed[0]?.kind === "stdio") {
+        assert.equal(parsed[0].command, "/opt/path with spaces/mcp");
+        assert.deepEqual(parsed[0].args, ["arg1"]);
+    }
+});
+test("parseFederationEnv: stdio with no command after stdio: is skipped", () => {
+    const parsed = parseFederationEnv({
+        OMCP_FEDERATION_UPSTREAMS: "broken=stdio:",
+    });
+    assert.equal(parsed.length, 0);
+});
+test("parseFederationEnv: http + stdio entries co-exist", () => {
+    const parsed = parseFederationEnv({
+        OMCP_FEDERATION_UPSTREAMS: "remote=https://gw/mcp,local=stdio:mcp",
+    });
+    assert.equal(parsed.length, 2);
+    assert.equal(parsed[0]?.kind, "http");
+    assert.equal(parsed[1]?.kind, "stdio");
+});
+test("parseFederationEnv: ws:// + wss:// entries parse with kind=ws", () => {
+    const parsed = parseFederationEnv({
+        OMCP_FEDERATION_UPSTREAMS: "plain=ws://gw/mcp/ws,secure=wss://gw/mcp/ws",
+    });
+    assert.equal(parsed.length, 2);
+    assert.deepEqual(parsed[0], { kind: "ws", name: "plain", url: "ws://gw/mcp/ws" });
+    assert.deepEqual(parsed[1], { kind: "ws", name: "secure", url: "wss://gw/mcp/ws" });
+});
+test("parseFederationEnv: ws upstreams do NOT carry bearer tokens (URL-only)", () => {
+    // Even when a matching OMCP_FEDERATION_TOKEN_X is set, the ws entry
+    // shouldn't grow a bearerToken field — the SDK transport only
+    // accepts the URL.
+    const parsed = parseFederationEnv({
+        OMCP_FEDERATION_UPSTREAMS: "x=wss://gw/mcp/ws",
+        OMCP_FEDERATION_TOKEN_X: "would-be-ignored",
+    });
+    assert.equal(parsed[0]?.kind, "ws");
+    // The ws branch has no `bearerToken` property at all.
+    assert.equal(parsed[0].bearerToken, undefined);
+});
+test("parseFederationEnv: all four transport variants co-exist", () => {
+    const parsed = parseFederationEnv({
+        OMCP_FEDERATION_UPSTREAMS: "a=https://gw/mcp,b=http://gw/mcp,c=ws://gw/mcp/ws,d=stdio:/bin/mcp",
+    });
+    assert.equal(parsed.length, 4);
+    assert.deepEqual(parsed.map((p) => p.kind), ["http", "http", "ws", "stdio"]);
 });
 test("parseFederationEnv: skips malformed entries with a warning, keeps the rest", () => {
     const parsed = parseFederationEnv({

package/dist/federation/upstream.d.ts

@@ -1,17 +1,38 @@
-export interface UpstreamConfig {
+interface UpstreamCommonConfig {
     /** 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;
+    /** Test-only: inject a pre-built MCP Transport instance.
+     *  Skips the spawn / fetch path entirely. */
+    _transport?: unknown;
+}
+export interface UpstreamHttpConfig extends UpstreamCommonConfig {
+    transport?: "http";
+    /** Upstream Streamable HTTP URL (must end at /mcp). */
+    url: string;
+    /** Static bearer token sent on every outbound call. */
+    bearerToken?: string;
+}
+export interface UpstreamStdioConfig extends UpstreamCommonConfig {
+    transport: "stdio";
+    /** Executable to spawn (e.g. "npx", "node", "/usr/local/bin/mcp"). */
+    command: string;
+    /** Argv for the executable. */
+    args?: string[];
+    /** Extra env merged into the child process's environment. */
+    env?: Record<string, string>;
+}
+export interface UpstreamWebsocketConfig extends UpstreamCommonConfig {
+    transport: "ws";
+    /** Upstream WebSocket URL — `ws://` or `wss://`. */
+    url: string;
 }
+export type UpstreamConfig = UpstreamHttpConfig | UpstreamStdioConfig | UpstreamWebsocketConfig;
 export interface UpstreamToolInfo {
     /** Local namespaced name: `<prefix>.<upstreamName>`. */
     namespacedName: string;
@@ -27,9 +48,12 @@ export interface UpstreamToolInfo {
 export type UpstreamStatus = "connecting" | "ready" | "degraded" | "disconnected";
 export declare class UpstreamClient {
     readonly name: string;
+    /** Empty-string for stdio (no remote URL); kept on the public surface
+     *  so the UI doesn't have to special-case the transport kind. */
     readonly url: string;
     readonly namespacePrefix: string;
-    private bearerToken?;
+    readonly transportKind: "http" | "stdio" | "ws";
+    private cfg;
     private client?;
     private transport?;
     private toolsCache;
@@ -57,4 +81,6 @@ export declare class UpstreamClient {
      *  calling here). */
     callTool(upstreamName: string, args: unknown): Promise<unknown>;
     close(): Promise<void>;
+    private buildTransport;
 }
+export {};

package/dist/federation/upstream.js

@@ -5,24 +5,42 @@
 // 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).
+// 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;
-    bearerToken;
+    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";
@@ -30,10 +48,17 @@ export class UpstreamClient {
     refreshTimer;
     refreshIntervalMs;
     constructor(cfg) {
+        this.cfg = cfg;
         this.name = cfg.name;
-        this.url = cfg.url;
+        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.bearerToken = cfg.bearerToken;
         this.refreshIntervalMs = cfg.refreshIntervalMs ?? 5 * 60 * 1000;
     }
     getStatus() {
@@ -49,13 +74,11 @@ export class UpstreamClient {
     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.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";
@@ -111,4 +134,29 @@ export class UpstreamClient {
         }
         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 {};