@thotischner/observability-mcp 1.8.1 → 3.0.1

package/dist/context.d.ts

@@ -27,6 +27,12 @@ export interface RequestContext {
      *  "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;
 }
@@ -36,4 +42,30 @@ export declare function defaultContext(): 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

@@ -17,6 +17,41 @@ export function principalContext(principalId, allowedSources, opts = {}) {
         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,54 @@
+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:
+ *
+ *   "a=https://gw.a/mcp,b=stdio:/usr/bin/mcp arg1,c=wss://gw.c/mcp/ws"
+ *
+ * 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 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

@@ -0,0 +1,122 @@
+// 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();
+    }
+}
+/** 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)
+        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 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 (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({ kind: "http", name, url: spec, bearerToken });
+    }
+    return entries;
+}

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

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

package/dist/federation/registry.test.js

@@ -0,0 +1,206 @@
+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, [
+        { 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>", () => {
+    const parsed = parseFederationEnv({
+        OMCP_FEDERATION_UPSTREAMS: "prod=https://gw.prod/mcp",
+        OMCP_FEDERATION_TOKEN_PROD: "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({
+        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,86 @@
+interface UpstreamCommonConfig {
+    /** Stable source name (used in the namespace prefix + audit entries). */
+    name: 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;
+    /** 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;
+    /** 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;
+    readonly transportKind: "http" | "stdio" | "ws";
+    private cfg;
+    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>;
+    private buildTransport;
+}
+export {};