@cyanmycelium/mcp-broker-provider 0.1.0

package/dist/multiplex.transport.js

@@ -0,0 +1,217 @@
+import { decodeEnvelope, encodeEnvelope, encodeRegisterEnvelope, envelopeFrame, tunnelErrorOf } from "./protocol/index";
+// ---------------------------------------------------------------------------
+// MultiplexSocket — shared WebSocket singleton (internal)
+// ---------------------------------------------------------------------------
+/**
+ * Manages a single WebSocket connection shared by multiple {@link MultiplexTransport}
+ * instances. All traffic goes through the tunnel envelope protocol, whose
+ * definition lives in `./protocol` and is shared with the broker.
+ *
+ * Reconnection is handled centrally here — individual transports do not reconnect.
+ * Use {@link getOrCreate} to obtain a per-URL singleton.
+ */
+class MultiplexSocket {
+    /** Per-URL cache so all transports targeting the same tunnel share one socket. */
+    static _instances = new Map();
+    _wsUrl;
+    _transports = new Map();
+    _ws = null;
+    _reconnectAttempts = 0;
+    _stopped = false;
+    constructor(wsUrl) {
+        this._wsUrl = wsUrl;
+    }
+    /** Returns (or creates) the singleton socket for a given tunnel URL. */
+    static getOrCreate(wsUrl) {
+        let instance = MultiplexSocket._instances.get(wsUrl);
+        if (!instance) {
+            instance = new MultiplexSocket(wsUrl);
+            MultiplexSocket._instances.set(wsUrl, instance);
+        }
+        return instance;
+    }
+    get isOpen() {
+        return this._ws?.readyState === WebSocket.OPEN;
+    }
+    // ── Registration ────────────────────────────────────────────────────────
+    register(name, transport) {
+        this._transports.set(name, transport);
+        // If the shared socket is already open, announce the new provider and
+        // notify the transport immediately.
+        if (this.isOpen) {
+            this._announceProvider(name);
+            transport.onOpen?.();
+        }
+        else if (!this._ws) {
+            // First registration — open the connection.
+            this._stopped = false;
+            this._connect();
+        }
+    }
+    unregister(name) {
+        this._transports.delete(name);
+        // Tear down the shared socket when no transports remain.
+        if (this._transports.size === 0) {
+            this._stopped = true;
+            this._ws?.close();
+            this._ws = null;
+            MultiplexSocket._instances.delete(this._wsUrl);
+        }
+    }
+    /**
+     * Claims the slot for `name` so the broker eagerly creates its provider
+     * state before any MCP client connects. Without it the broker only learns
+     * about a provider on its first real message, and a client connecting in
+     * between is told the provider is not connected.
+     */
+    _announceProvider(name) {
+        if (this._ws?.readyState !== WebSocket.OPEN)
+            return;
+        this._ws.send(encodeRegisterEnvelope(name));
+    }
+    // ── Sending ─────────────────────────────────────────────────────────────
+    send(provider, data) {
+        if (this._ws?.readyState !== WebSocket.OPEN)
+            return;
+        this._ws.send(encodeEnvelope(provider, data));
+    }
+    // ── Connection lifecycle ────────────────────────────────────────────────
+    _connect() {
+        const ws = new WebSocket(this._wsUrl);
+        // Held from construction, not from `onopen`: a transport registering
+        // while the handshake is still in flight must find this socket rather
+        // than open a second one. Readiness is decided by `readyState`, so a
+        // connecting socket is never mistaken for a usable one.
+        this._ws = ws;
+        ws.onopen = () => {
+            this._reconnectAttempts = 0;
+            // Announce all registered providers to the broker so it eagerly
+            // creates their slots before any MCP client connects.
+            for (const name of this._transports.keys()) {
+                this._announceProvider(name);
+            }
+            for (const transport of this._transports.values()) {
+                transport.onOpen?.();
+            }
+        };
+        ws.onerror = () => {
+            for (const transport of this._transports.values()) {
+                transport.onError?.(new Error(`MultiplexSocket: WebSocket error on ${this._wsUrl}`));
+            }
+        };
+        ws.onclose = () => {
+            this._ws = null;
+            for (const transport of this._transports.values()) {
+                transport.onClose?.();
+            }
+            if (!this._stopped) {
+                this._scheduleReconnect();
+            }
+        };
+        ws.onmessage = (event) => {
+            this._routeIncoming(event.data);
+        };
+    }
+    _routeIncoming(raw) {
+        const envelope = decodeEnvelope(raw);
+        if (!envelope)
+            return; // malformed — drop silently
+        const transport = this._transports.get(envelope.provider);
+        if (!transport)
+            return;
+        // A tunnel-level refusal (a rejected slot, an unavailable provider)
+        // carries no request id. Handing it to an MCP server would get it
+        // classified as an unknown notification and dropped without a word, so
+        // surface it as a transport error instead.
+        const payload = envelope.payload;
+        if (payload !== null && (payload.id === null || payload.id === undefined)) {
+            const error = tunnelErrorOf(envelope.payload);
+            if (error) {
+                transport.onError?.(new Error(`Tunnel error ${error.code} on provider "${envelope.provider}": ${error.message}`));
+                return;
+            }
+        }
+        transport.onMessage?.(envelopeFrame(envelope));
+    }
+    _scheduleReconnect() {
+        const base = 1_000;
+        const max = 30_000;
+        const jitter = 0.5 + Math.random() * 0.5;
+        const delay = Math.min(base * 2 ** this._reconnectAttempts, max) * jitter;
+        this._reconnectAttempts++;
+        setTimeout(() => {
+            if (!this._stopped)
+                this._connect();
+        }, delay);
+    }
+}
+// ---------------------------------------------------------------------------
+// MultiplexTransport — per-server transport (public)
+// ---------------------------------------------------------------------------
+/**
+ * A transport that multiplexes multiple MCP servers over a single shared
+ * WebSocket connection using the envelope protocol `{ provider, payload }`.
+ *
+ * Use the static {@link create} factory to obtain an instance:
+ * ```typescript
+ * const t1 = MultiplexTransport.create("scene-1", "ws://localhost:3000/providers");
+ * const t2 = MultiplexTransport.create("scene-2", "ws://localhost:3000/providers");
+ * // t1 and t2 share a single WebSocket under the hood.
+ * ```
+ */
+export class MultiplexTransport {
+    _name;
+    _socket;
+    _registered = false;
+    onMessage = null;
+    onOpen = null;
+    onClose = null;
+    onError = null;
+    constructor(name, socket) {
+        this._name = name;
+        this._socket = socket;
+    }
+    /**
+     * Convenience factory: creates a {@link MultiplexTransport} backed by a
+     * shared {@link MultiplexSocket} for the given tunnel URL.
+     *
+     * Transports targeting the same `wsUrl` automatically share one WebSocket.
+     */
+    static create(name, wsUrl) {
+        return new MultiplexTransport(name, MultiplexSocket.getOrCreate(wsUrl));
+    }
+    get isOpen() {
+        return this._socket.isOpen;
+    }
+    /**
+     * Registers this transport with the shared socket.
+     *
+     * Safe to call multiple times — subsequent calls are no-ops.
+     */
+    activate() {
+        if (!this._registered) {
+            this._registered = true;
+            this._socket.register(this._name, this);
+        }
+    }
+    /**
+     * Opens the transport, the same way every other transport does.
+     *
+     * An alias of {@link activate} so callers never have to special-case this
+     * class: an MCP server or client just calls `connect()` on whatever
+     * transport it was handed.
+     */
+    connect() {
+        this.activate();
+    }
+    send(data) {
+        this._socket.send(this._name, data);
+    }
+    close() {
+        if (this._registered) {
+            this._registered = false;
+            this._socket.unregister(this._name);
+        }
+    }
+}
+//# sourceMappingURL=multiplex.transport.js.map

package/dist/multiplex.transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multiplex.transport.js","sourceRoot":"","sources":["../src/multiplex.transport.ts"],"names":[],"mappings":"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"}

package/dist/protocol/envelope.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The CyanMycelium tunnel envelope protocol.
+ *
+ * A multiplexed tunnel socket carries traffic for several providers at once, so
+ * every JSON-RPC message is wrapped with the name of the provider slot it
+ * belongs to. Both ends of the tunnel encode and decode with the helpers here:
+ * the client transports that publish a provider, and the broker that routes
+ * between providers and MCP clients.
+ *
+ * This module is the single definition of that wire format. It is deliberately
+ * dependency-free and isomorphic, so the browser side and the Node broker share
+ * exactly one implementation rather than two that drift apart.
+ *
+ * Wire format:
+ * ```json
+ * { "provider": "scene-1", "payload": { "jsonrpc": "2.0", "id": 1, "result": {} } }
+ * ```
+ */
+/** One framed message on a multiplexed tunnel socket. */
+export interface TunnelEnvelope {
+    /** Name of the provider slot this message belongs to. */
+    provider: string;
+    /** The JSON-RPC message itself, already parsed. */
+    payload: unknown;
+}
+/**
+ * Notification a client sends to claim a provider slot as soon as the tunnel
+ * opens, before any MCP client shows up.
+ *
+ * Without it the broker only discovers a provider name on its first real
+ * message, so an MCP client connecting in between is told the provider is not
+ * connected. It is a plain JSON-RPC notification, which any peer that does not
+ * recognize it ignores.
+ */
+export declare const TUNNEL_REGISTER_METHOD = "notifications/register";
+/** JSON-RPC error codes the broker returns on the tunnel itself. */
+export declare const TunnelErrorCodes: {
+    /** The slot is taken by another upstream, or the provider is not connected. */
+    readonly ProviderUnavailable: -32000;
+    /** The provider's credentials do not allow publishing on this slot. */
+    readonly RegistrationForbidden: -32001;
+};
+export type TunnelErrorCode = (typeof TunnelErrorCodes)[keyof typeof TunnelErrorCodes];
+/** A JSON-RPC error as carried inside an envelope payload. */
+export interface TunnelError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+/**
+ * Wraps an already-serialized JSON-RPC frame for `provider`.
+ *
+ * @throws SyntaxError when `frame` is not valid JSON. Callers hold a frame they
+ *         just serialized, so a failure here is a bug rather than bad input.
+ */
+export declare function encodeEnvelope(provider: string, frame: string): string;
+/** Wraps an already-parsed JSON-RPC message for `provider`. */
+export declare function encodeEnvelopeMessage(provider: string, payload: unknown): string;
+/**
+ * Parses a raw tunnel frame.
+ *
+ * Returns `undefined` for anything malformed rather than throwing: a tunnel
+ * socket is a public surface, and a peer sending garbage must not take the
+ * receiver down. Both ends drop such frames silently.
+ */
+export declare function decodeEnvelope(raw: string): TunnelEnvelope | undefined;
+/** Serializes an envelope's payload back into a plain JSON-RPC frame. */
+export declare function envelopeFrame(envelope: TunnelEnvelope): string;
+/** Builds the registration notification that claims `provider`. */
+export declare function encodeRegisterEnvelope(provider: string): string;
+/**
+ * Builds the error envelope the broker returns when it refuses a slot.
+ *
+ * The id is `null` because the refusal answers no particular request: it
+ * reacts to the registration itself.
+ */
+export declare function encodeErrorEnvelope(provider: string, code: TunnelErrorCode | number, message: string): string;
+/**
+ * Reads the JSON-RPC error out of an envelope payload, when there is one.
+ *
+ * Lets the client side notice a refused registration instead of handing an
+ * `id: null` error frame to an MCP server, which would classify it as an
+ * unknown notification and drop it without a word.
+ */
+export declare function tunnelErrorOf(payload: unknown): TunnelError | undefined;

package/dist/protocol/envelope.js

@@ -0,0 +1,107 @@
+/**
+ * The CyanMycelium tunnel envelope protocol.
+ *
+ * A multiplexed tunnel socket carries traffic for several providers at once, so
+ * every JSON-RPC message is wrapped with the name of the provider slot it
+ * belongs to. Both ends of the tunnel encode and decode with the helpers here:
+ * the client transports that publish a provider, and the broker that routes
+ * between providers and MCP clients.
+ *
+ * This module is the single definition of that wire format. It is deliberately
+ * dependency-free and isomorphic, so the browser side and the Node broker share
+ * exactly one implementation rather than two that drift apart.
+ *
+ * Wire format:
+ * ```json
+ * { "provider": "scene-1", "payload": { "jsonrpc": "2.0", "id": 1, "result": {} } }
+ * ```
+ */
+/**
+ * Notification a client sends to claim a provider slot as soon as the tunnel
+ * opens, before any MCP client shows up.
+ *
+ * Without it the broker only discovers a provider name on its first real
+ * message, so an MCP client connecting in between is told the provider is not
+ * connected. It is a plain JSON-RPC notification, which any peer that does not
+ * recognize it ignores.
+ */
+export const TUNNEL_REGISTER_METHOD = "notifications/register";
+/** JSON-RPC error codes the broker returns on the tunnel itself. */
+export const TunnelErrorCodes = {
+    /** The slot is taken by another upstream, or the provider is not connected. */
+    ProviderUnavailable: -32000,
+    /** The provider's credentials do not allow publishing on this slot. */
+    RegistrationForbidden: -32001,
+};
+/**
+ * Wraps an already-serialized JSON-RPC frame for `provider`.
+ *
+ * @throws SyntaxError when `frame` is not valid JSON. Callers hold a frame they
+ *         just serialized, so a failure here is a bug rather than bad input.
+ */
+export function encodeEnvelope(provider, frame) {
+    return encodeEnvelopeMessage(provider, JSON.parse(frame));
+}
+/** Wraps an already-parsed JSON-RPC message for `provider`. */
+export function encodeEnvelopeMessage(provider, payload) {
+    const envelope = { provider, payload };
+    return JSON.stringify(envelope);
+}
+/**
+ * Parses a raw tunnel frame.
+ *
+ * Returns `undefined` for anything malformed rather than throwing: a tunnel
+ * socket is a public surface, and a peer sending garbage must not take the
+ * receiver down. Both ends drop such frames silently.
+ */
+export function decodeEnvelope(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return undefined;
+    const { provider, payload } = parsed;
+    if (typeof provider !== "string" || provider.length === 0 || payload === undefined)
+        return undefined;
+    return { provider, payload };
+}
+/** Serializes an envelope's payload back into a plain JSON-RPC frame. */
+export function envelopeFrame(envelope) {
+    return JSON.stringify(envelope.payload);
+}
+/** Builds the registration notification that claims `provider`. */
+export function encodeRegisterEnvelope(provider) {
+    return encodeEnvelopeMessage(provider, { jsonrpc: "2.0", method: TUNNEL_REGISTER_METHOD });
+}
+/**
+ * Builds the error envelope the broker returns when it refuses a slot.
+ *
+ * The id is `null` because the refusal answers no particular request: it
+ * reacts to the registration itself.
+ */
+export function encodeErrorEnvelope(provider, code, message) {
+    return encodeEnvelopeMessage(provider, { jsonrpc: "2.0", id: null, error: { code, message } });
+}
+/**
+ * Reads the JSON-RPC error out of an envelope payload, when there is one.
+ *
+ * Lets the client side notice a refused registration instead of handing an
+ * `id: null` error frame to an MCP server, which would classify it as an
+ * unknown notification and drop it without a word.
+ */
+export function tunnelErrorOf(payload) {
+    if (typeof payload !== "object" || payload === null)
+        return undefined;
+    const { error } = payload;
+    if (typeof error !== "object" || error === null)
+        return undefined;
+    const { code, message } = error;
+    if (typeof code !== "number" || typeof message !== "string")
+        return undefined;
+    return error;
+}
+//# sourceMappingURL=envelope.js.map

package/dist/protocol/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/protocol/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAWH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,wBAAwB,CAAC;AAE/D,oEAAoE;AACpE,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC5B,+EAA+E;IAC/E,mBAAmB,EAAE,CAAC,KAAK;IAE3B,uEAAuE;IACvE,qBAAqB,EAAE,CAAC,KAAK;CACvB,CAAC;AAWX;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE,KAAa;IAC1D,OAAO,qBAAqB,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,qBAAqB,CAAC,QAAgB,EAAE,OAAgB;IACpE,MAAM,QAAQ,GAAmB,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;IACvD,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACtC,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACD,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,SAAS,CAAC;IACrB,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IAE7F,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAiC,CAAC;IAChE,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAErG,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;AACjC,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,aAAa,CAAC,QAAwB;IAClD,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AAC5C,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,sBAAsB,CAAC,QAAgB;IACnD,OAAO,qBAAqB,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC,CAAC;AAC/F,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAgB,EAAE,IAA8B,EAAE,OAAe;IACjG,OAAO,qBAAqB,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;AACnG,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC1C,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAEtE,MAAM,EAAE,KAAK,EAAE,GAAG,OAA8B,CAAC;IACjD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAElE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,KAA6B,CAAC;IACxD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAE9E,OAAO,KAAoB,CAAC;AAChC,CAAC"}

package/dist/protocol/index.d.ts

@@ -0,0 +1 @@
+export * from "./envelope";

package/dist/protocol/index.js

@@ -0,0 +1,2 @@
+export * from "./envelope";
+//# sourceMappingURL=index.js.map

package/dist/protocol/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/protocol/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC"}

package/package.json

@@ -0,0 +1,82 @@
+{
+    "name": "@cyanmycelium/mcp-broker-provider",
+    "version": "0.1.0",
+    "description": "Provider side of the CyanMycelium MCP broker tunnel: publish an MCP server to a broker slot over the shared envelope protocol.",
+    "type": "module",
+    "license": "Apache-2.0",
+    "author": "Guillaume Pelletier (CyanMycelium)",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/pandaGaume/mcp-broker.git",
+        "directory": "node/packages/provider"
+    },
+    "homepage": "https://github.com/pandaGaume/mcp-broker#readme",
+    "bugs": {
+        "url": "https://github.com/pandaGaume/mcp-broker/issues"
+    },
+    "keywords": [
+        "mcp",
+        "model-context-protocol",
+        "broker",
+        "provider",
+        "tunnel",
+        "websocket",
+        "transport",
+        "cyanmycelium"
+    ],
+    "engines": {
+        "node": ">=20.11.0"
+    },
+    "sideEffects": false,
+    "files": [
+        "dist",
+        "src",
+        "LICENSE",
+        "README.md"
+    ],
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "default": "./dist/index.js"
+        },
+        "./protocol": {
+            "types": "./dist/protocol/index.d.ts",
+            "import": "./dist/protocol/index.js",
+            "default": "./dist/protocol/index.js"
+        }
+    },
+    "scripts": {
+        "build": "npm run clean && npm run compile",
+        "clean": "rimraf dist tsconfig.build.tsbuildinfo",
+        "compile": "tsc -b tsconfig.build.json",
+        "watch": "tsc -b tsconfig.build.json -w",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "lint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\"",
+        "lint:fix": "eslint \"src/**/*.ts\" \"tests/**/*.ts\" --fix",
+        "format": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"",
+        "format:fix": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"",
+        "prepublishOnly": "npm run lint && npm run build && npm test"
+    },
+    "peerDependencies": {
+        "@cyanmycelium/mcp-core": "^0.4.0"
+    },
+    "devDependencies": {
+        "@cyanmycelium/mcp-core": "^0.4.0",
+        "@types/node": "^20.11.0",
+        "@typescript-eslint/eslint-plugin": "^7.0.0",
+        "@typescript-eslint/parser": "^7.0.0",
+        "eslint": "^8.57.0",
+        "eslint-config-prettier": "^9.1.0",
+        "eslint-plugin-prettier": "^5.1.0",
+        "prettier": "^3.2.0",
+        "rimraf": "~6.0.1",
+        "tslib": "^2.8.1",
+        "typescript": "^5.4.0",
+        "vitest": "^4.1.9"
+    }
+}

package/src/direct.transport.ts

@@ -0,0 +1,66 @@
+import type { IMessageTransport } from "@cyanmycelium/mcp-core";
+
+/**
+ * 1:1 WebSocket transport — wraps a single `WebSocket` connection to a broker
+ * provider slot, typically `ws://<broker>/provider/<name>`.
+ *
+ * One server owns one socket. When an application publishes several servers
+ * through the same broker, prefer {@link MultiplexTransport}, which shares a
+ * single socket between them.
+ *
+ * Call {@link connect} after setting the event callbacks to open the socket.
+ */
+export class DirectTransport implements IMessageTransport {
+    private readonly _wsUrl: string;
+    private _ws: WebSocket | null = null;
+
+    onMessage: ((data: string) => void) | null = null;
+    onOpen: (() => void) | null = null;
+    onClose: (() => void) | null = null;
+    onError: ((error: Error) => void) | null = null;
+
+    constructor(wsUrl: string) {
+        this._wsUrl = wsUrl;
+    }
+
+    get isOpen(): boolean {
+        return this._ws?.readyState === WebSocket.OPEN;
+    }
+
+    /**
+     * Opens the WebSocket connection and wires its events to the transport
+     * callbacks. Must be called after assigning `onOpen` / `onMessage` / etc.
+     */
+    connect(): void {
+        const ws = new WebSocket(this._wsUrl);
+
+        ws.onopen = () => {
+            this._ws = ws;
+            this.onOpen?.();
+        };
+
+        ws.onerror = () => {
+            this.onError?.(new Error(`DirectTransport: WebSocket error on ${this._wsUrl}`));
+        };
+
+        ws.onclose = () => {
+            this._ws = null;
+            this.onClose?.();
+        };
+
+        ws.onmessage = (event: MessageEvent<string>) => {
+            this.onMessage?.(event.data);
+        };
+    }
+
+    send(data: string): void {
+        if (this._ws?.readyState === WebSocket.OPEN) {
+            this._ws.send(data);
+        }
+    }
+
+    close(): void {
+        this._ws?.close();
+        this._ws = null;
+    }
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Provider side of the CyanMycelium MCP broker tunnel: what an application uses
+ * to publish its MCP server to a broker slot.
+ *
+ * The tunnel envelope protocol is also published on its own entry point,
+ * `@cyanmycelium/mcp-broker-provider/protocol`, which the broker imports so both
+ * ends of the tunnel share one definition of the wire format.
+ */
+export * from "./protocol/index";
+export { DirectTransport } from "./direct.transport";
+export { MultiplexTransport } from "./multiplex.transport";