@cyanmycelium/mcp-broker 0.2.0 → 0.3.0

package/dist/ws.tunnel.d.ts

@@ -1,5 +1,6 @@
 import type { IMessageTransport } from "@cyanmycelium/mcp-core";
 import { type StdioUpstreamConfig } from "./stdio.upstream.js";
+import { type RemoteUpstreamConfig } from "./remote.upstream.js";
 import type { BrokerContext, BrokerLocaleResolver, BrokerProviderInfo, BrokerUserAgentResolver } from "./broker/index.js";
 /**
  * A single static-file mount: serves the contents of `dir` under `urlPrefix`.
@@ -14,6 +15,27 @@ export interface StaticMount {
     /** Absolute path to the directory to serve. */
     dir: string;
 }
+/**
+ * In-process client handle for a provider slot — the symmetric counterpart of
+ * {@link WsTunnel.registerLoopbackProvider}. Lets a component inside the broker
+ * process (e.g. the aggregate server) issue MCP requests to a provider slot and
+ * receive both the responses and the provider's broadcast notifications,
+ * without opening a real network connection.
+ */
+export interface InternalClient {
+    /**
+     * Sends a JSON-RPC message to the provider slot. When the message carries an
+     * `id`, the matching response is delivered to {@link onMessage}. When the
+     * provider is not connected, a JSON-RPC error is delivered synchronously.
+     */
+    send(message: string): void;
+    /** Receives responses to this client's requests and the provider's notifications. */
+    onMessage: ((data: string) => void) | null;
+    /** Fires when the provider slot loses its connection. */
+    onClose: (() => void) | null;
+    /** Detaches this internal client; pending requests are dropped. */
+    close(): void;
+}
 /**
  * Configuration options for a {@link WsTunnel} instance.
  */
@@ -83,6 +105,8 @@ export interface WsTunnelOptions {
      * @default undefined — no stdio providers
      */
     stdioUpstreams?: StdioUpstreamConfig[];
+    /** Remote MCP servers reached by URL, exposed as provider slots. */
+    remoteUpstreams?: RemoteUpstreamConfig[];
     /**
      * Stdio client transport. When set, the broker reads JSON-RPC from
      * `process.stdin` and writes responses to `process.stdout`, bridging an
@@ -125,6 +149,16 @@ export interface WsTunnelOptions {
      * @default true
      */
     enableBrokerProvider?: boolean;
+    /**
+     * When `true` (default), the broker exposes the reserved slot `_all` — an
+     * aggregate MCP server that unions the tools and prompts of every provider
+     * that opted in via the registration handshake. Reachable like any other
+     * slot (`<host>/_all/mcp`, etc.).
+     *
+     * Set to `false` to disable aggregation entirely.
+     * @default true
+     */
+    enableAggregateProvider?: boolean;
     /**
      * Logical name reported by `broker_info`. Useful when running multiple
      * broker instances and you want to tell them apart from the agent side
@@ -190,8 +224,8 @@ export declare class WsTunnel implements BrokerContext {
     private readonly _providers;
     /** Maps a multiplexed WebSocket to the set of provider names it feeds. */
     private readonly _multiplexSockets;
-    /** Stdio upstream providers, keyed by provider name. */
-    private readonly _stdioUpstreams;
+    /** Upstream providers (stdio child processes and remote URL servers), keyed by name. */
+    private readonly _upstreams;
     /**
      * In-process loopback transports registered as provider slots.
      * Used by the embedded broker server (`_broker`) and any other component
@@ -200,6 +234,8 @@ export declare class WsTunnel implements BrokerContext {
     private readonly _loopbackProviders;
     /** The embedded broker MCP server, when {@link WsTunnelOptions.enableBrokerProvider} is on. */
     private _brokerServer;
+    /** The aggregate MCP server (`_all` slot), when {@link WsTunnelOptions.enableAggregateProvider} is on. */
+    private _aggregateServer;
     /** Provider name that the stdio client transport is bridged to, or null when disabled. */
     private _stdioClientProvider;
     /** Buffered partial line from stdin (stdio client transport). */
@@ -226,6 +262,16 @@ export declare class WsTunnel implements BrokerContext {
      * @throws if the name is already used by a stdio upstream or another loopback.
      */
     registerLoopbackProvider(name: string, transport: IMessageTransport): void;
+    /**
+     * Opens an in-process client to a provider slot. The returned handle can
+     * issue MCP requests and receives both the responses and the provider's
+     * broadcast notifications. Used by the aggregate server to fan a single
+     * in-process client out to every aggregated provider.
+     *
+     * The slot does not need a provider attached yet — `send` returns a
+     * JSON-RPC error while the provider is disconnected.
+     */
+    openInternalClient(providerName: string): InternalClient;
     get isListening(): boolean;
     /** Total number of connected MCP clients across all providers. */
     get clientCount(): number;
@@ -244,6 +290,11 @@ export declare class WsTunnel implements BrokerContext {
      * is `false`.
      */
     private _maybeStartBrokerServer;
+    /**
+     * Starts the aggregate MCP server and registers it on the reserved `_all`
+     * slot. No-op when {@link WsTunnelOptions.enableAggregateProvider} is `false`.
+     */
+    private _maybeStartAggregateServer;
     /**
      * Gracefully closes all connections and stops the HTTP server.
      */
@@ -280,6 +331,14 @@ export declare class WsTunnel implements BrokerContext {
     /** Writes one JSON-RPC message as an SSE `message` event. */
     private _sendSseEvent;
     private _onProviderConnect;
+    /**
+     * Inspects a provider's first WebSocket message for an optional registration
+     * control frame `{ "type": "register", "aggregate": boolean }`. Returns
+     * `true` when the message was a registration frame — and thus consumed, not
+     * routed as MCP traffic. A normal MCP frame always carries `jsonrpc`, so it
+     * returns `false` and the provider stays non-aggregated.
+     */
+    private _tryHandleRegistration;
     private _onClientConnect;
     /**
      * Handles a multiplexed provider WebSocket (`/providers`).
@@ -298,6 +357,12 @@ export declare class WsTunnel implements BrokerContext {
     private _routeFromProvider;
     /** Sends a message to all clients connected to one provider. */
     private _broadcast;
+    /**
+     * Notifies every pending sink and internal client that the provider slot
+     * has disconnected, then clears the pending map. Shared by all provider
+     * close handlers (dedicated WS, multiplexed WS, loopback).
+     */
+    private _failProviderDisconnected;
     /**
      * Returns `true` if the provider is reachable — via a WebSocket connection,
      * a stdio upstream, or an in-process loopback transport.

package/dist/ws.tunnel.js

@@ -5,7 +5,9 @@ import * as nodePath from "path";
 import { randomUUID } from "crypto";
 import { WebSocket, WebSocketServer } from "ws";
 import { StdioUpstream } from "./stdio.upstream.js";
+import { RemoteUpstream } from "./remote.upstream.js";
 import { startBrokerServer, BROKER_PROVIDER_NAME } from "./broker/index.js";
+import { AggregateServer } from "./broker/aggregate/aggregate.server.js";
 import { VERSION, PACKAGE_NAME } from "./version.js";
 // ---------------------------------------------------------------------------
 // Static-file helpers
@@ -60,8 +62,8 @@ export class WsTunnel {
     _providers = new Map();
     /** Maps a multiplexed WebSocket to the set of provider names it feeds. */
     _multiplexSockets = new Map();
-    /** Stdio upstream providers, keyed by provider name. */
-    _stdioUpstreams = new Map();
+    /** Upstream providers (stdio child processes and remote URL servers), keyed by name. */
+    _upstreams = new Map();
     /**
      * In-process loopback transports registered as provider slots.
      * Used by the embedded broker server (`_broker`) and any other component
@@ -70,6 +72,8 @@ export class WsTunnel {
     _loopbackProviders = new Map();
     /** The embedded broker MCP server, when {@link WsTunnelOptions.enableBrokerProvider} is on. */
     _brokerServer = null;
+    /** The aggregate MCP server (`_all` slot), when {@link WsTunnelOptions.enableAggregateProvider} is on. */
+    _aggregateServer = null;
     /** Provider name that the stdio client transport is bridged to, or null when disabled. */
     _stdioClientProvider = null;
     /** Buffered partial line from stdin (stdio client transport). */
@@ -136,7 +140,7 @@ export class WsTunnel {
             transport = "loopback";
             connected = true;
         }
-        else if (this._stdioUpstreams.get(name)?.isOpen) {
+        else if (this._upstreams.get(name)?.isOpen) {
             transport = "stdio";
             connected = true;
         }
@@ -171,7 +175,7 @@ export class WsTunnel {
         if (this._loopbackProviders.has(name)) {
             throw new Error(`Loopback provider "${name}" is already registered.`);
         }
-        if (this._stdioUpstreams.has(name)) {
+        if (this._upstreams.has(name)) {
             throw new Error(`Cannot register loopback "${name}": a stdio upstream with the same name already exists.`);
         }
         const state = this._getOrCreateProviderState(name);
@@ -179,28 +183,62 @@ export class WsTunnel {
         transport.onMessage = (data) => this._routeFromProvider(state, data);
         transport.onClose = () => {
             this._loopbackProviders.delete(name);
-            // Tell every pending sink that the provider is gone, same as for a WS close.
-            const error = JSON.stringify({
-                jsonrpc: "2.0",
-                id: null,
-                error: { code: -32000, message: `Provider "${name}" disconnected` },
-            });
-            for (const sink of state.pending.values()) {
-                if (sink.type === "ws" && sink.socket.readyState === WebSocket.OPEN) {
-                    sink.socket.send(error);
+            this._failProviderDisconnected(state, name);
+        };
+    }
+    /**
+     * Opens an in-process client to a provider slot. The returned handle can
+     * issue MCP requests and receives both the responses and the provider's
+     * broadcast notifications. Used by the aggregate server to fan a single
+     * in-process client out to every aggregated provider.
+     *
+     * The slot does not need a provider attached yet — `send` returns a
+     * JSON-RPC error while the provider is disconnected.
+     */
+    openInternalClient(providerName) {
+        const state = this._getOrCreateProviderState(providerName);
+        let closed = false;
+        const client = {
+            onMessage: null,
+            onClose: null,
+            send: (message) => {
+                if (closed)
+                    return;
+                let id = null;
+                try {
+                    const parsed = JSON.parse(message);
+                    if (parsed?.id != null)
+                        id = parsed.id;
                 }
-                else if (sink.type === "sse") {
-                    const sseRes = state.sseSessions.get(sink.sessionId);
-                    if (sseRes)
-                        this._sendSseEvent(sseRes, error);
+                catch {
+                    /* forward as-is */
                 }
-                else if (sink.type === "http") {
-                    sink.res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
-                    sink.res.end(error);
+                if (this._isProviderConnected(providerName, state)) {
+                    if (id != null)
+                        state.pending.set(id, { type: "internal", client });
+                    this._sendToProvider(state, providerName, message);
                 }
-            }
-            state.pending.clear();
+                else if (id != null) {
+                    client.onMessage?.(JSON.stringify({
+                        jsonrpc: "2.0",
+                        id,
+                        error: { code: -32000, message: `Provider "${providerName}" not connected` },
+                    }));
+                }
+            },
+            close: () => {
+                if (closed)
+                    return;
+                closed = true;
+                state.internalClients.delete(client);
+                for (const [id, sink] of state.pending) {
+                    if (sink.type === "internal" && sink.client === client)
+                        state.pending.delete(id);
+                }
+            },
         };
+        state.internalClients.add(client);
+        return client;
     }
     // -------------------------------------------------------------------------
     // Public state
@@ -260,9 +298,13 @@ export class WsTunnel {
                 }
             });
             this._httpServer.listen(this._options.port, this._options.host ?? "0.0.0.0", () => {
-                // Spawn configured stdio upstream providers.
-                for (const cfg of this._options.stdioUpstreams ?? []) {
-                    const upstream = new StdioUpstream(cfg);
+                // Bring the aggregate `_all` slot up before any upstream connects
+                // (a Streamable HTTP upstream opens synchronously on connect()).
+                this._maybeStartAggregateServer();
+                // Attach configured upstreams (stdio child processes + remote URL
+                // servers). Both implement the Upstream contract, so the wiring
+                // into a provider slot is identical.
+                const wireUpstream = (cfg, upstream) => {
                     upstream.onMessage = (data) => {
                         const state = this._getOrCreateProviderState(cfg.name);
                         this._routeFromProvider(state, data);
@@ -270,9 +312,21 @@ export class WsTunnel {
                     upstream.onError = (err) => {
                         console.error(`[broker] ${err.message}`);
                     };
-                    this._stdioUpstreams.set(cfg.name, upstream);
+                    upstream.onClose = () => {
+                        const state = this._providers.get(cfg.name);
+                        if (state)
+                            this._failProviderDisconnected(state, cfg.name);
+                    };
+                    if (cfg.aggregate) {
+                        upstream.onOpen = () => void this._aggregateServer?.addProvider(cfg.name);
+                    }
+                    this._upstreams.set(cfg.name, upstream);
                     upstream.connect();
-                }
+                };
+                for (const cfg of this._options.stdioUpstreams ?? [])
+                    wireUpstream(cfg, new StdioUpstream(cfg));
+                for (const cfg of this._options.remoteUpstreams ?? [])
+                    wireUpstream(cfg, new RemoteUpstream(cfg));
                 // Attach stdio client transport if configured.
                 // stdin carries Claude Desktop's JSON-RPC requests; stdout carries responses.
                 if (this._options.stdioClient) {
@@ -322,6 +376,27 @@ export class WsTunnel {
         });
         this._brokerServer = server;
         this.registerLoopbackProvider(BROKER_PROVIDER_NAME, clientTransport);
+        // Aggregate the broker's own introspection tools into `_all`, so a stdio
+        // host pinned to `_all` still reaches broker_info / providers_list /
+        // provider_status alongside the other aggregated providers.
+        void this._aggregateServer?.addProvider(BROKER_PROVIDER_NAME);
+    }
+    /**
+     * Starts the aggregate MCP server and registers it on the reserved `_all`
+     * slot. No-op when {@link WsTunnelOptions.enableAggregateProvider} is `false`.
+     */
+    _maybeStartAggregateServer() {
+        if (this._options.enableAggregateProvider === false)
+            return;
+        try {
+            const server = new AggregateServer((providerName) => this.openInternalClient(providerName));
+            server.start();
+            this.registerLoopbackProvider(AggregateServer.SLOT, server);
+            this._aggregateServer = server;
+        }
+        catch (err) {
+            console.error(`[broker] aggregate server failed to start: ${err.message}`);
+        }
     }
     /**
      * Gracefully closes all connections and stops the HTTP server.
@@ -339,6 +414,18 @@ export class WsTunnel {
                 /* best-effort; continue tearing down */
             }
         }
+        // Close the aggregate server so its provider sessions and internal
+        // clients detach before the provider slots are torn down.
+        const aggregateServer = this._aggregateServer;
+        this._aggregateServer = null;
+        if (aggregateServer) {
+            try {
+                aggregateServer.close();
+            }
+            catch {
+                /* best-effort; continue tearing down */
+            }
+        }
         return new Promise((resolve, reject) => {
             for (const state of this._providers.values()) {
                 for (const res of state.sseSessions.values())
@@ -354,9 +441,9 @@ export class WsTunnel {
             }
             this._providers.clear();
             this._multiplexSockets.clear();
-            for (const upstream of this._stdioUpstreams.values())
+            for (const upstream of this._upstreams.values())
                 upstream.close();
-            this._stdioUpstreams.clear();
+            this._upstreams.clear();
             for (const loopback of this._loopbackProviders.values())
                 loopback.close();
             this._loopbackProviders.clear();
@@ -585,7 +672,7 @@ export class WsTunnel {
     // WebSocket connection handlers
     // -------------------------------------------------------------------------
     _onProviderConnect(ws, name) {
-        if (this._stdioUpstreams.has(name)) {
+        if (this._upstreams.has(name)) {
             console.warn(`[broker] WARNING: WebSocket provider "${name}" rejected — a stdio upstream with the same name is already configured. ` +
                 `Rename one of them to avoid the conflict.`);
             ws.close(1008, `Provider "${name}" is managed by a stdio upstream`);
@@ -603,32 +690,47 @@ export class WsTunnel {
         }
         const state = this._getOrCreateProviderState(name);
         state.ws = ws;
-        ws.on("message", (data) => this._routeFromProvider(state, data.toString()));
+        // A provider MAY send a registration control frame as its very first
+        // message (see _tryHandleRegistration). Any other first message —
+        // including a normal MCP frame — is routed and leaves the provider
+        // non-aggregated, so every pre-existing provider keeps working.
+        let registrationChecked = false;
+        ws.on("message", (data) => {
+            const text = data.toString();
+            if (!registrationChecked) {
+                registrationChecked = true;
+                if (this._tryHandleRegistration(name, text))
+                    return;
+            }
+            this._routeFromProvider(state, text);
+        });
         ws.on("close", () => {
             state.ws = null;
-            // Notify all pending sinks that the provider is gone.
-            const error = JSON.stringify({
-                jsonrpc: "2.0",
-                id: null,
-                error: { code: -32000, message: `Provider "${name}" disconnected` },
-            });
-            for (const sink of state.pending.values()) {
-                if (sink.type === "ws" && sink.socket.readyState === WebSocket.OPEN) {
-                    sink.socket.send(error);
-                }
-                else if (sink.type === "sse") {
-                    const sseRes = state.sseSessions.get(sink.sessionId);
-                    if (sseRes)
-                        this._sendSseEvent(sseRes, error);
-                }
-                else if (sink.type === "http") {
-                    sink.res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
-                    sink.res.end(error);
-                }
-            }
-            state.pending.clear();
+            this._failProviderDisconnected(state, name);
         });
     }
+    /**
+     * Inspects a provider's first WebSocket message for an optional registration
+     * control frame `{ "type": "register", "aggregate": boolean }`. Returns
+     * `true` when the message was a registration frame — and thus consumed, not
+     * routed as MCP traffic. A normal MCP frame always carries `jsonrpc`, so it
+     * returns `false` and the provider stays non-aggregated.
+     */
+    _tryHandleRegistration(name, text) {
+        let frame;
+        try {
+            frame = JSON.parse(text);
+        }
+        catch {
+            return false;
+        }
+        if (frame.jsonrpc !== undefined || frame.type !== "register")
+            return false;
+        if (frame.aggregate === true) {
+            void this._aggregateServer?.addProvider(name);
+        }
+        return true;
+    }
     _onClientConnect(ws, providerName) {
         const state = this._getOrCreateProviderState(providerName);
         state.wsClients.add(ws);
@@ -663,7 +765,7 @@ export class WsTunnel {
                 return;
             // Register provider name lazily on first encounter.
             if (!providerNames.has(name)) {
-                if (this._stdioUpstreams.has(name)) {
+                if (this._upstreams.has(name)) {
                     console.warn(`[broker] WARNING: Multiplexed WebSocket provider "${name}" rejected — a stdio upstream with the same name is already configured. ` +
                         `Rename one of them to avoid the conflict.`);
                     ws.send(JSON.stringify({
@@ -712,27 +814,7 @@ export class WsTunnel {
                 const state = this._providers.get(name);
                 if (state && state.ws === ws) {
                     state.ws = null;
-                    // Notify pending sinks that the provider is gone.
-                    const error = JSON.stringify({
-                        jsonrpc: "2.0",
-                        id: null,
-                        error: { code: -32000, message: `Provider "${name}" disconnected` },
-                    });
-                    for (const sink of state.pending.values()) {
-                        if (sink.type === "ws" && sink.socket.readyState === WebSocket.OPEN) {
-                            sink.socket.send(error);
-                        }
-                        else if (sink.type === "sse") {
-                            const sseRes = state.sseSessions.get(sink.sessionId);
-                            if (sseRes)
-                                this._sendSseEvent(sseRes, error);
-                        }
-                        else if (sink.type === "http") {
-                            sink.res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
-                            sink.res.end(error);
-                        }
-                    }
-                    state.pending.clear();
+                    this._failProviderDisconnected(state, name);
                 }
             }
             this._multiplexSockets.delete(ws);
@@ -746,10 +828,10 @@ export class WsTunnel {
      * envelope when the provider's WebSocket is a multiplexed connection.
      */
     _sendToProvider(state, providerName, data) {
-        // Stdio upstreams take priority for exact name matches.
-        const stdioUpstream = this._stdioUpstreams.get(providerName);
-        if (stdioUpstream?.isOpen) {
-            stdioUpstream.send(data);
+        // Upstreams (stdio child processes and remote URL servers) take priority.
+        const upstream = this._upstreams.get(providerName);
+        if (upstream?.isOpen) {
+            upstream.send(data);
             return;
         }
         // In-process loopback (e.g. the embedded `_broker`) takes the same priority.
@@ -839,6 +921,9 @@ export class WsTunnel {
                 else if (sink?.type === "stdio") {
                     process.stdout.write(data + "\n");
                 }
+                else if (sink?.type === "internal") {
+                    sink.client.onMessage?.(data);
+                }
                 state.pending.delete(msg.id);
             }
             else {
@@ -862,11 +947,46 @@ export class WsTunnel {
         for (const mcpRes of state.mcpGetSessions.values()) {
             this._sendSseEvent(mcpRes, data);
         }
+        for (const ic of state.internalClients) {
+            ic.onMessage?.(data);
+        }
         // Forward notifications to the stdio client if it is watching this provider.
         if (this._stdioClientProvider && this._providers.get(this._stdioClientProvider) === state) {
             process.stdout.write(data + "\n");
         }
     }
+    /**
+     * Notifies every pending sink and internal client that the provider slot
+     * has disconnected, then clears the pending map. Shared by all provider
+     * close handlers (dedicated WS, multiplexed WS, loopback).
+     */
+    _failProviderDisconnected(state, name) {
+        const error = JSON.stringify({
+            jsonrpc: "2.0",
+            id: null,
+            error: { code: -32000, message: `Provider "${name}" disconnected` },
+        });
+        for (const sink of state.pending.values()) {
+            if (sink.type === "ws" && sink.socket.readyState === WebSocket.OPEN) {
+                sink.socket.send(error);
+            }
+            else if (sink.type === "sse") {
+                const sseRes = state.sseSessions.get(sink.sessionId);
+                if (sseRes)
+                    this._sendSseEvent(sseRes, error);
+            }
+            else if (sink.type === "http") {
+                sink.res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+                sink.res.end(error);
+            }
+            else if (sink.type === "internal") {
+                sink.client.onMessage?.(error);
+            }
+        }
+        state.pending.clear();
+        for (const ic of state.internalClients)
+            ic.onClose?.();
+    }
     // -------------------------------------------------------------------------
     // Provider state helpers
     // -------------------------------------------------------------------------
@@ -875,7 +995,7 @@ export class WsTunnel {
      * a stdio upstream, or an in-process loopback transport.
      */
     _isProviderConnected(providerName, state) {
-        if (this._stdioUpstreams.get(providerName)?.isOpen)
+        if (this._upstreams.get(providerName)?.isOpen)
             return true;
         if (this._loopbackProviders.get(providerName)?.isOpen)
             return true;
@@ -893,6 +1013,7 @@ export class WsTunnel {
                 sseSessions: new Map(),
                 mcpGetSessions: new Map(),
                 wsClients: new Set(),
+                internalClients: new Set(),
             };
             this._providers.set(name, state);
         }