@cyanmycelium/mcp-broker 0.1.0

package/dist/ws.tunnel.js

@@ -0,0 +1,971 @@
+import * as fs from "fs";
+import * as http from "http";
+import * as https from "https";
+import * as nodePath from "path";
+import { randomUUID } from "crypto";
+import { WebSocket, WebSocketServer } from "ws";
+import { StdioUpstream } from "./stdio.upstream.js";
+import { startBrokerServer, BROKER_PROVIDER_NAME } from "./broker/index.js";
+import { VERSION, PACKAGE_NAME } from "./version.js";
+// ---------------------------------------------------------------------------
+// Static-file helpers
+// ---------------------------------------------------------------------------
+/** Maps file extensions to their HTTP Content-Type values. */
+const MIME = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "application/javascript; charset=utf-8",
+    ".mjs": "application/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".map": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".ico": "image/x-icon",
+    ".woff2": "font/woff2",
+    ".woff": "font/woff",
+};
+// ---------------------------------------------------------------------------
+// WsTunnel
+// ---------------------------------------------------------------------------
+/**
+ * A multi-provider relay that bridges any number of MCP server instances
+ * (the **providers**) with their respective MCP clients.
+ *
+ * ## Transport overview
+ * ```
+ * Provider "<name>"
+ *   ws://host/provider/<name>           ← WebSocket registration
+ *
+ * MCP Inspector (Streamable HTTP, 2025-03-26)
+ *   GET  http://host/<name>/mcp         ← persistent SSE notification stream
+ *   POST http://host/<name>/mcp         → JSON-RPC requests
+ *
+ * Claude (legacy SSE transport)
+ *   GET  http://host/<name>/sse              ← SSE notification stream
+ *   POST http://host/<name>/messages         → JSON-RPC requests
+ * ```
+ *
+ * Each provider gets its own isolated set of sessions, pending requests, and
+ * notification streams. Multiple providers can be connected simultaneously.
+ */
+export class WsTunnel {
+    _options;
+    _httpServer = null;
+    _wss = null;
+    /**
+     * Per-provider state, keyed by provider name.
+     * Created lazily: a slot is allocated the first time any client references
+     * a provider name, even before the provider WebSocket connects.
+     */
+    _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();
+    /**
+     * In-process loopback transports registered as provider slots.
+     * Used by the embedded broker server (`_broker`) and any other component
+     * that wants to expose itself as a provider without going through a network.
+     */
+    _loopbackProviders = new Map();
+    /** The embedded broker MCP server, when {@link WsTunnelOptions.enableBrokerProvider} is on. */
+    _brokerServer = 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). */
+    _stdioClientBuffer = "";
+    /** Timestamp of the most recent successful `start()`. */
+    _startedAt = null;
+    constructor(options) {
+        this._options = options;
+    }
+    // -------------------------------------------------------------------------
+    // BrokerContext implementation
+    // -------------------------------------------------------------------------
+    get version() {
+        return VERSION;
+    }
+    get name() {
+        return this._options.brokerName ?? PACKAGE_NAME;
+    }
+    get startedAt() {
+        return this._startedAt;
+    }
+    get uptimeSeconds() {
+        if (!this._startedAt)
+            return 0;
+        return Math.floor((Date.now() - this._startedAt.getTime()) / 1000);
+    }
+    get host() {
+        return this._options.host;
+    }
+    get port() {
+        return this._options.port;
+    }
+    get tls() {
+        return !!this._options.tls;
+    }
+    get paths() {
+        const o = this._options;
+        return {
+            provider: o.providerPath ?? "/provider",
+            providers: o.providersPath ?? "/providers",
+            client: o.clientPath ?? "/",
+            mcp: o.mcpPath ?? "/mcp",
+            sse: o.ssePath ?? "/sse",
+            messages: o.messagesPath ?? "/messages",
+        };
+    }
+    getProvidersInfo() {
+        const out = [];
+        for (const [name, state] of this._providers) {
+            out.push(this._buildProviderInfo(name, state));
+        }
+        return out;
+    }
+    getProviderInfo(name) {
+        const state = this._providers.get(name);
+        if (!state)
+            return undefined;
+        return this._buildProviderInfo(name, state);
+    }
+    _buildProviderInfo(name, state) {
+        let transport;
+        let connected;
+        if (this._loopbackProviders.get(name)?.isOpen) {
+            transport = "loopback";
+            connected = true;
+        }
+        else if (this._stdioUpstreams.get(name)?.isOpen) {
+            transport = "stdio";
+            connected = true;
+        }
+        else if (state.ws?.readyState === WebSocket.OPEN) {
+            transport = this._multiplexSockets.has(state.ws) ? "ws-multiplex" : "ws";
+            connected = true;
+        }
+        else {
+            transport = "none";
+            connected = false;
+        }
+        return {
+            name,
+            transport,
+            connected,
+            clientCount: state.wsClients.size,
+            sessionCount: state.sseSessions.size + state.mcpGetSessions.size,
+            pendingCount: state.pending.size,
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Loopback provider registration (in-process transports)
+    // -------------------------------------------------------------------------
+    /**
+     * Registers an in-process transport as a provider slot. Used by the embedded
+     * broker server and may be used by application code that wants to host an
+     * MCP server inside the same process without opening a real WebSocket.
+     *
+     * @throws if the name is already used by a stdio upstream or another loopback.
+     */
+    registerLoopbackProvider(name, transport) {
+        if (this._loopbackProviders.has(name)) {
+            throw new Error(`Loopback provider "${name}" is already registered.`);
+        }
+        if (this._stdioUpstreams.has(name)) {
+            throw new Error(`Cannot register loopback "${name}": a stdio upstream with the same name already exists.`);
+        }
+        const state = this._getOrCreateProviderState(name);
+        this._loopbackProviders.set(name, transport);
+        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);
+                }
+                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();
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Public state
+    // -------------------------------------------------------------------------
+    get isListening() {
+        return this._httpServer?.listening ?? false;
+    }
+    /** Total number of connected MCP clients across all providers. */
+    get clientCount() {
+        let n = 0;
+        for (const s of this._providers.values()) {
+            n += s.wsClients.size + s.sseSessions.size + s.mcpGetSessions.size;
+        }
+        return n;
+    }
+    /** Names of all providers that currently have an active connection. */
+    get providerNames() {
+        return [...this._providers.entries()].filter(([name, s]) => this._isProviderConnected(name, s)).map(([name]) => name);
+    }
+    /** @deprecated Check `providerNames.length > 0` instead. */
+    get hasProvider() {
+        return this.providerNames.length > 0;
+    }
+    // -------------------------------------------------------------------------
+    // Lifecycle
+    // -------------------------------------------------------------------------
+    /**
+     * Starts the broker. Resolves once the HTTP server is listening.
+     */
+    start() {
+        return new Promise((resolve) => {
+            const handler = (req, res) => this._handleHttp(req, res);
+            this._httpServer = this._options.tls ? https.createServer({ cert: this._options.tls.cert, key: this._options.tls.key }, handler) : http.createServer(handler);
+            // Disable perMessageDeflate: payloads may be large base64-encoded blobs
+            // (snapshots, images) that are already compressed. Deflating them wastes
+            // CPU without reducing size, and caused multi-second stalls in practice.
+            this._wss = new WebSocketServer({ server: this._httpServer, perMessageDeflate: false });
+            this._wss.on("connection", (ws, req) => {
+                const url = req.url ?? "/";
+                const providerPath = this._options.providerPath ?? "/provider";
+                const providersPath = this._options.providersPath ?? "/providers";
+                if (url === providersPath || url.startsWith(providersPath + "?")) {
+                    // Multiplexed provider: one WebSocket carries N providers via envelopes.
+                    this._onMultiplexProviderConnect(ws);
+                }
+                else if (url.startsWith(providerPath + "/") || url === providerPath) {
+                    // Extract name: everything after "<providerPath>/"
+                    const raw = url.slice(providerPath.length).replace(/^\//, "");
+                    const name = decodeURIComponent(raw.split("?")[0]) || "(unnamed)";
+                    this._onProviderConnect(ws, name);
+                }
+                else {
+                    // Raw WS MCP client: URL is "/<providerName>" or "/"
+                    const raw = url.replace(/^\//, "").split("?")[0];
+                    const name = decodeURIComponent(raw) || "";
+                    this._onClientConnect(ws, name);
+                }
+            });
+            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);
+                    upstream.onMessage = (data) => {
+                        const state = this._getOrCreateProviderState(cfg.name);
+                        this._routeFromProvider(state, data);
+                    };
+                    upstream.onError = (err) => {
+                        console.error(`[broker] ${err.message}`);
+                    };
+                    this._stdioUpstreams.set(cfg.name, upstream);
+                    upstream.connect();
+                }
+                // Attach stdio client transport if configured.
+                // stdin carries Claude Desktop's JSON-RPC requests; stdout carries responses.
+                if (this._options.stdioClient) {
+                    this._stdioClientProvider = this._options.stdioClient.providerName;
+                    process.stdin.setEncoding("utf8");
+                    process.stdin.on("data", (chunk) => {
+                        this._stdioClientBuffer += chunk;
+                        let nl;
+                        while ((nl = this._stdioClientBuffer.indexOf("\n")) !== -1) {
+                            const line = this._stdioClientBuffer.slice(0, nl).trim();
+                            this._stdioClientBuffer = this._stdioClientBuffer.slice(nl + 1);
+                            if (line) {
+                                const state = this._getOrCreateProviderState(this._stdioClientProvider);
+                                this._routeFromStdioClient(state, line);
+                            }
+                        }
+                    });
+                    process.stdin.on("end", () => {
+                        // Client disconnected — nothing to clean up; pending sinks will time out.
+                    });
+                }
+                this._startedAt = new Date();
+                // Spawn the embedded broker server last so it can already report
+                // accurate state in its first `broker_info` call.
+                void this._maybeStartBrokerServer().then(() => resolve(), (err) => {
+                    console.error("[broker] embedded broker server failed to start:", err);
+                    // Keep the tunnel up even if the introspection server fails.
+                    resolve();
+                });
+            });
+        });
+    }
+    /**
+     * Starts the in-process MCP server that exposes the broker's own behaviors
+     * (`broker_info`, `providers_list`, `provider_status`) under the reserved
+     * provider slot `_broker`. No-op when {@link WsTunnelOptions.enableBrokerProvider}
+     * is `false`.
+     */
+    async _maybeStartBrokerServer() {
+        if (this._options.enableBrokerProvider === false)
+            return;
+        const { server, clientTransport } = await startBrokerServer(this, {
+            localeResolver: this._options.brokerLocaleResolver,
+            userAgentResolver: this._options.brokerUserAgentResolver,
+            localeSource: this._options.brokerLocaleSource,
+            localGrammarsDir: this._options.brokerLocalGrammarsDir,
+        });
+        this._brokerServer = server;
+        this.registerLoopbackProvider(BROKER_PROVIDER_NAME, clientTransport);
+    }
+    /**
+     * Gracefully closes all connections and stops the HTTP server.
+     */
+    async stop() {
+        // Stop the embedded broker first so it does not see its loopback close
+        // as an unexpected disconnect (and to flush any pending broker responses).
+        const brokerServer = this._brokerServer;
+        this._brokerServer = null;
+        if (brokerServer) {
+            try {
+                await brokerServer.stop();
+            }
+            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())
+                    res.end();
+                state.sseSessions.clear();
+                for (const res of state.mcpGetSessions.values())
+                    res.end();
+                state.mcpGetSessions.clear();
+                for (const client of state.wsClients)
+                    client.close();
+                state.wsClients.clear();
+                state.ws?.close();
+            }
+            this._providers.clear();
+            this._multiplexSockets.clear();
+            for (const upstream of this._stdioUpstreams.values())
+                upstream.close();
+            this._stdioUpstreams.clear();
+            for (const loopback of this._loopbackProviders.values())
+                loopback.close();
+            this._loopbackProviders.clear();
+            this._startedAt = null;
+            this._wss?.close();
+            this._httpServer?.close((err) => (err ? reject(err) : resolve()));
+        });
+    }
+    // -------------------------------------------------------------------------
+    // HTTP dispatcher
+    // -------------------------------------------------------------------------
+    _handleHttp(req, res) {
+        const method = req.method ?? "GET";
+        const rawUrl = (req.url ?? "/").split("?")[0];
+        // CORS
+        res.setHeader("Access-Control-Allow-Origin", "*");
+        res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+        res.setHeader("Access-Control-Allow-Headers", req.headers["access-control-request-headers"] ?? "Content-Type, Accept, Mcp-Session-Id");
+        res.setHeader("Access-Control-Expose-Headers", "Mcp-Session-Id");
+        if (method === "OPTIONS") {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        // Samples index (no provider prefix)
+        const samplesIndexPath = this._options.samplesIndexPath ?? "/__samples_index__";
+        if (method === "GET" && rawUrl === samplesIndexPath) {
+            this._handleSamplesIndex(res);
+            return;
+        }
+        // Route /<providerName>/<endpoint>
+        const route = this._parseProviderRoute(rawUrl);
+        if (route) {
+            const { providerName, endpoint } = route;
+            const mcpSuffix = (this._options.mcpPath ?? "/mcp").replace(/^\//, "");
+            const sseSuffix = (this._options.ssePath ?? "/sse").replace(/^\//, "");
+            const messagesSuffix = (this._options.messagesPath ?? "/messages").replace(/^\//, "");
+            if (endpoint === mcpSuffix) {
+                if (method === "GET") {
+                    this._handleMcpGetStream(req, res, providerName);
+                    return;
+                }
+                if (method === "POST") {
+                    this._handleMcpPost(req, res, providerName);
+                    return;
+                }
+            }
+            if (endpoint === sseSuffix && method === "GET") {
+                this._handleSseConnect(req, res, providerName);
+                return;
+            }
+            if (endpoint === messagesSuffix && method === "POST") {
+                this._handleSseMessage(req, res, providerName);
+                return;
+            }
+        }
+        // Static files
+        if (this._options.staticMounts?.length) {
+            this._serveStatic(req, res);
+        }
+        else {
+            res.writeHead(404);
+            res.end();
+        }
+    }
+    /**
+     * Parses `/<providerName>/<endpoint>` from a URL path.
+     * Returns `null` if the URL does not match this two-segment pattern.
+     */
+    _parseProviderRoute(rawUrl) {
+        const parts = rawUrl.split("/").filter(Boolean);
+        if (parts.length !== 2)
+            return null;
+        const providerName = decodeURIComponent(parts[0]);
+        const endpoint = decodeURIComponent(parts[1]);
+        if (!providerName || !endpoint)
+            return null;
+        return { providerName, endpoint };
+    }
+    // -------------------------------------------------------------------------
+    // MCP / SSE transport (per provider)
+    // -------------------------------------------------------------------------
+    /**
+     * Handles `GET /<providerName>/sse` — opens a long-lived SSE stream for Claude.
+     * Sends an `endpoint` event so Claude knows where to POST its requests.
+     */
+    _handleSseConnect(req, res, providerName) {
+        const sessionId = randomUUID();
+        const messagesSuffix = (this._options.messagesPath ?? "/messages").replace(/^\//, "");
+        const messagesUrl = `/${encodeURIComponent(providerName)}/${messagesSuffix}`;
+        res.writeHead(200, {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache, no-transform",
+            Connection: "keep-alive",
+        });
+        res.write(`event: endpoint\ndata: ${messagesUrl}?sessionId=${sessionId}\n\n`);
+        const state = this._getOrCreateProviderState(providerName);
+        state.sseSessions.set(sessionId, res);
+        req.on("close", () => {
+            state.sseSessions.delete(sessionId);
+            for (const [id, sink] of state.pending) {
+                if (sink.type === "sse" && sink.sessionId === sessionId)
+                    state.pending.delete(id);
+            }
+        });
+    }
+    /**
+     * Handles `POST /<providerName>/messages?sessionId=…` — receives a JSON-RPC
+     * request from Claude and forwards it to the provider.
+     * Always responds 202 Accepted; the real response arrives over SSE.
+     */
+    _handleSseMessage(req, res, providerName) {
+        const params = new URL(req.url ?? "", "http://localhost").searchParams;
+        const sessionId = params.get("sessionId") ?? "";
+        const state = this._getOrCreateProviderState(providerName);
+        if (!state.sseSessions.has(sessionId)) {
+            res.writeHead(400, { "Content-Type": "text/plain" });
+            res.end("Unknown or expired session");
+            return;
+        }
+        let body = "";
+        req.on("data", (chunk) => {
+            body += chunk.toString();
+        });
+        req.on("end", () => {
+            try {
+                const msg = JSON.parse(body);
+                if (msg.id != null)
+                    state.pending.set(msg.id, { type: "sse", sessionId });
+            }
+            catch {
+                /* malformed — forward anyway */
+            }
+            if (this._isProviderConnected(providerName, state)) {
+                this._sendToProvider(state, providerName, body);
+            }
+            else {
+                const sseRes = state.sseSessions.get(sessionId);
+                if (sseRes) {
+                    let errId = null;
+                    try {
+                        errId = JSON.parse(body).id ?? null;
+                    }
+                    catch {
+                        /* */
+                    }
+                    this._sendSseEvent(sseRes, JSON.stringify({
+                        jsonrpc: "2.0",
+                        id: errId,
+                        error: { code: -32000, message: `Provider "${providerName}" not connected` },
+                    }));
+                }
+            }
+            res.writeHead(202);
+            res.end();
+        });
+    }
+    /**
+     * Handles `POST /<providerName>/mcp` — Streamable HTTP transport (MCP 2025-03-26).
+     * Forwards the JSON-RPC request to the provider and holds the HTTP response
+     * open until the reply arrives, then writes it as `application/json`.
+     */
+    _handleMcpPost(req, res, providerName) {
+        let body = "";
+        req.on("data", (chunk) => {
+            body += chunk.toString();
+        });
+        req.on("end", () => {
+            let msg = {};
+            try {
+                msg = JSON.parse(body);
+            }
+            catch {
+                res.writeHead(400, { "Content-Type": "text/plain" });
+                res.end("Invalid JSON");
+                return;
+            }
+            const state = this._getOrCreateProviderState(providerName);
+            if (!this._isProviderConnected(providerName, state)) {
+                res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+                res.end(JSON.stringify({
+                    jsonrpc: "2.0",
+                    id: msg.id ?? null,
+                    error: { code: -32000, message: `Provider "${providerName}" not connected` },
+                }));
+                return;
+            }
+            if (msg.id != null) {
+                // Request: hold the response open; reply arrives in _routeFromProvider.
+                state.pending.set(msg.id, { type: "http", res });
+            }
+            else {
+                // Notification: forward and acknowledge immediately.
+                res.writeHead(202);
+                res.end();
+            }
+            this._sendToProvider(state, providerName, body);
+        });
+    }
+    /**
+     * Handles `GET /<providerName>/mcp` — opens a persistent SSE stream per MCP 2025-03-26.
+     * Streamable HTTP clients (e.g. MCP Inspector) use this to receive
+     * server-initiated notifications without re-polling.
+     */
+    _handleMcpGetStream(req, res, providerName) {
+        const sessionId = req.headers["mcp-session-id"] ?? randomUUID();
+        res.writeHead(200, {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache, no-transform",
+            Connection: "keep-alive",
+            "Mcp-Session-Id": sessionId,
+        });
+        res.write(": stream open\n\n");
+        const state = this._getOrCreateProviderState(providerName);
+        state.mcpGetSessions.set(sessionId, res);
+        req.on("close", () => {
+            state.mcpGetSessions.delete(sessionId);
+        });
+    }
+    /** Writes one JSON-RPC message as an SSE `message` event. */
+    _sendSseEvent(res, data) {
+        // data is already a compact JSON string — no need to parse+re-serialize.
+        res.write(`event: message\ndata: ${data}\n\n`);
+    }
+    // -------------------------------------------------------------------------
+    // WebSocket connection handlers
+    // -------------------------------------------------------------------------
+    _onProviderConnect(ws, name) {
+        if (this._stdioUpstreams.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`);
+            return;
+        }
+        if (this._loopbackProviders.has(name)) {
+            console.warn(`[broker] WARNING: WebSocket provider "${name}" rejected — the slot is held by an in-process loopback (reserved system slot).`);
+            ws.close(1008, `Provider "${name}" is reserved by the broker`);
+            return;
+        }
+        const existing = this._providers.get(name);
+        if (existing?.ws?.readyState === WebSocket.OPEN) {
+            ws.close(1008, `Provider "${name}" is already connected`);
+            return;
+        }
+        const state = this._getOrCreateProviderState(name);
+        state.ws = ws;
+        ws.on("message", (data) => this._routeFromProvider(state, data.toString()));
+        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();
+        });
+    }
+    _onClientConnect(ws, providerName) {
+        const state = this._getOrCreateProviderState(providerName);
+        state.wsClients.add(ws);
+        ws.on("message", (data) => this._routeFromClient(ws, state, providerName, data.toString()));
+        ws.on("close", () => {
+            state.wsClients.delete(ws);
+            for (const [id, sink] of state.pending) {
+                if (sink.type === "ws" && sink.socket === ws)
+                    state.pending.delete(id);
+            }
+        });
+    }
+    /**
+     * Handles a multiplexed provider WebSocket (`/providers`).
+     * A single socket carries traffic for multiple providers using the
+     * envelope format `{ provider: string, payload: object }`.
+     * Provider names are registered lazily on first message.
+     */
+    _onMultiplexProviderConnect(ws) {
+        const providerNames = new Set();
+        this._multiplexSockets.set(ws, providerNames);
+        ws.on("message", (data) => {
+            let envelope;
+            try {
+                envelope = JSON.parse(data.toString());
+            }
+            catch {
+                return; // malformed — drop
+            }
+            const name = envelope.provider;
+            if (!name || envelope.payload === undefined)
+                return;
+            // Register provider name lazily on first encounter.
+            if (!providerNames.has(name)) {
+                if (this._stdioUpstreams.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({
+                        provider: name,
+                        payload: {
+                            jsonrpc: "2.0",
+                            id: null,
+                            error: { code: -32000, message: `Provider "${name}" is managed by a stdio upstream` },
+                        },
+                    }));
+                    return;
+                }
+                if (this._loopbackProviders.has(name)) {
+                    ws.send(JSON.stringify({
+                        provider: name,
+                        payload: {
+                            jsonrpc: "2.0",
+                            id: null,
+                            error: { code: -32000, message: `Provider "${name}" is reserved by the broker` },
+                        },
+                    }));
+                    return;
+                }
+                const existing = this._providers.get(name);
+                if (existing?.ws?.readyState === WebSocket.OPEN) {
+                    // Provider already connected via another socket — reject this name.
+                    ws.send(JSON.stringify({
+                        provider: name,
+                        payload: {
+                            jsonrpc: "2.0",
+                            id: null,
+                            error: { code: -32000, message: `Provider "${name}" is already connected` },
+                        },
+                    }));
+                    return;
+                }
+                providerNames.add(name);
+                const state = this._getOrCreateProviderState(name);
+                state.ws = ws;
+            }
+            const state = this._providers.get(name);
+            this._routeFromProvider(state, JSON.stringify(envelope.payload));
+        });
+        ws.on("close", () => {
+            for (const name of providerNames) {
+                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._multiplexSockets.delete(ws);
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Message routing
+    // -------------------------------------------------------------------------
+    /**
+     * Sends a raw JSON-RPC message to a provider, wrapping it in a multiplex
+     * 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);
+            return;
+        }
+        // In-process loopback (e.g. the embedded `_broker`) takes the same priority.
+        const loopback = this._loopbackProviders.get(providerName);
+        if (loopback?.isOpen) {
+            loopback.send(data);
+            return;
+        }
+        if (!state.ws || state.ws.readyState !== WebSocket.OPEN)
+            return;
+        if (this._multiplexSockets.has(state.ws)) {
+            // Wrap in envelope for the multiplexed socket.
+            const payload = JSON.parse(data);
+            state.ws.send(JSON.stringify({ provider: providerName, payload }));
+        }
+        else {
+            state.ws.send(data);
+        }
+    }
+    _routeFromStdioClient(state, data) {
+        try {
+            const msg = JSON.parse(data);
+            if (msg?.id != null)
+                state.pending.set(msg.id, { type: "stdio" });
+        }
+        catch {
+            /* forward as-is */
+        }
+        if (this._isProviderConnected(this._stdioClientProvider, state)) {
+            this._sendToProvider(state, this._stdioClientProvider, data);
+        }
+        else {
+            let errId = null;
+            try {
+                errId = JSON.parse(data).id ?? null;
+            }
+            catch {
+                /* */
+            }
+            if (errId != null) {
+                process.stdout.write(JSON.stringify({
+                    jsonrpc: "2.0",
+                    id: errId,
+                    error: { code: -32000, message: `Provider "${this._stdioClientProvider}" not connected` },
+                }) + "\n");
+            }
+        }
+    }
+    _routeFromClient(client, state, providerName, data) {
+        try {
+            const msg = JSON.parse(data);
+            if (msg?.id != null)
+                state.pending.set(msg.id, { type: "ws", socket: client });
+        }
+        catch {
+            /* forward as-is */
+        }
+        if (this._isProviderConnected(providerName, state)) {
+            this._sendToProvider(state, providerName, data);
+        }
+        else {
+            client.send(JSON.stringify({
+                jsonrpc: "2.0",
+                id: null,
+                error: { code: -32000, message: "No provider connected" },
+            }));
+        }
+    }
+    _routeFromProvider(state, data) {
+        try {
+            const msg = JSON.parse(data);
+            if (msg.id != null) {
+                // Response: route to the specific sink that made the request.
+                const sink = state.pending.get(msg.id);
+                if (sink?.type === "ws" && sink.socket.readyState === WebSocket.OPEN) {
+                    sink.socket.send(data);
+                }
+                else if (sink?.type === "sse") {
+                    const sseRes = state.sseSessions.get(sink.sessionId);
+                    if (sseRes)
+                        this._sendSseEvent(sseRes, data);
+                }
+                else if (sink?.type === "http") {
+                    sink.res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+                    sink.res.end(data);
+                }
+                else if (sink?.type === "stdio") {
+                    process.stdout.write(data + "\n");
+                }
+                state.pending.delete(msg.id);
+            }
+            else {
+                // Notification (no id): broadcast to all clients of this provider.
+                this._broadcast(state, data);
+            }
+        }
+        catch {
+            this._broadcast(state, data);
+        }
+    }
+    /** Sends a message to all clients connected to one provider. */
+    _broadcast(state, data) {
+        for (const client of state.wsClients) {
+            if (client.readyState === WebSocket.OPEN)
+                client.send(data);
+        }
+        for (const sseRes of state.sseSessions.values()) {
+            this._sendSseEvent(sseRes, data);
+        }
+        for (const mcpRes of state.mcpGetSessions.values()) {
+            this._sendSseEvent(mcpRes, 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");
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Provider state helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Returns `true` if the provider is reachable — via a WebSocket connection,
+     * a stdio upstream, or an in-process loopback transport.
+     */
+    _isProviderConnected(providerName, state) {
+        if (this._stdioUpstreams.get(providerName)?.isOpen)
+            return true;
+        if (this._loopbackProviders.get(providerName)?.isOpen)
+            return true;
+        if (state.ws?.readyState === WebSocket.OPEN)
+            return true;
+        return false;
+    }
+    /** Returns the state for `name`, creating it lazily if it doesn't exist yet. */
+    _getOrCreateProviderState(name) {
+        let state = this._providers.get(name);
+        if (!state) {
+            state = {
+                ws: null,
+                pending: new Map(),
+                sseSessions: new Map(),
+                mcpGetSessions: new Map(),
+                wsClients: new Set(),
+            };
+            this._providers.set(name, state);
+        }
+        return state;
+    }
+    // -------------------------------------------------------------------------
+    // Samples index
+    // -------------------------------------------------------------------------
+    _handleSamplesIndex(res) {
+        const rootMount = (this._options.staticMounts ?? []).find((m) => m.urlPrefix === "/");
+        let files = [];
+        if (rootMount) {
+            const samplesDir = nodePath.join(rootMount.dir, "samples");
+            try {
+                if (fs.existsSync(samplesDir) && fs.statSync(samplesDir).isDirectory()) {
+                    files = fs.readdirSync(samplesDir).filter((name) => fs.statSync(nodePath.join(samplesDir, name)).isFile());
+                }
+            }
+            catch {
+                /* return empty list on any I/O error */
+            }
+        }
+        res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+        res.end(JSON.stringify({ files }));
+    }
+    // -------------------------------------------------------------------------
+    // Static file serving
+    // -------------------------------------------------------------------------
+    _serveStatic(req, res) {
+        const rawUrl = (req.url ?? "/").split("?")[0].split("#")[0];
+        const mounts = this._options.staticMounts ?? [];
+        const mount = [...mounts]
+            .filter((m) => {
+            const prefix = m.urlPrefix.endsWith("/") ? m.urlPrefix : m.urlPrefix + "/";
+            return rawUrl === m.urlPrefix || rawUrl.startsWith(prefix);
+        })
+            .sort((a, b) => b.urlPrefix.length - a.urlPrefix.length)[0];
+        if (!mount) {
+            res.writeHead(404, { "Content-Type": "text/plain" });
+            res.end("Not found");
+            return;
+        }
+        const relative = rawUrl.slice(mount.urlPrefix.length) || "/";
+        const normalized = nodePath.normalize(relative);
+        if (normalized.startsWith("..")) {
+            res.writeHead(403);
+            res.end("Forbidden");
+            return;
+        }
+        const mountAbs = nodePath.resolve(mount.dir);
+        let filePath = nodePath.join(mountAbs, normalized);
+        if (!filePath.startsWith(mountAbs + nodePath.sep) && filePath !== mountAbs) {
+            res.writeHead(403);
+            res.end("Forbidden");
+            return;
+        }
+        try {
+            if (fs.statSync(filePath).isDirectory())
+                filePath = nodePath.join(filePath, "index.html");
+        }
+        catch {
+            res.writeHead(404);
+            res.end("Not found");
+            return;
+        }
+        if (!fs.existsSync(filePath)) {
+            res.writeHead(404);
+            res.end("Not found");
+            return;
+        }
+        const ext = nodePath.extname(filePath).toLowerCase();
+        res.writeHead(200, { "Content-Type": MIME[ext] ?? "application/octet-stream" });
+        fs.createReadStream(filePath).pipe(res);
+    }
+}
+//# sourceMappingURL=ws.tunnel.js.map