@cyanmycelium/mcp-broker-provider 0.1.0 → 0.2.0

package/README.md

@@ -32,21 +32,25 @@ A multiplexed tunnel socket carries traffic for several providers at once, so ev
 { "provider": "scene-1", "payload": { "jsonrpc": "2.0", "id": 1, "method": "tools/list" } }
 ```
 
-`./protocol` is the single definition of that format. The broker imports it rather than re-declaring the shape inline, so the two ends cannot drift.
+`./protocol` is the single definition of that format, and the broker imports it from here rather than re-declaring the shape inline, so the two ends cannot drift. The broker depends on this package because it is itself a provider: it publishes its own `_broker` introspection slot and its `_all` aggregate slot.
 
 Beyond the envelope it also covers:
 
-- `notifications/register`, sent as soon as the tunnel opens to claim a provider slot. Without it the broker only learns a provider name on its first real message, and an MCP client connecting in between is told the provider is not connected.
-- The tunnel error codes: `-32001` when the provider's credentials do not allow publishing on the requested slot, `-32000` when the slot is unavailable. `tunnelErrorOf()` lets a provider recognise them instead of handing an `id: null` error frame to an MCP server, which would classify it as an unknown notification and drop it silently.
+- `notifications/register`, sent as soon as the tunnel opens to claim a provider slot. Without it the broker only learns a provider name on its first real message, and an MCP client connecting in between is told the provider is not connected. It optionally carries `params: { aggregate: true }`, which also joins the broker's `_all` slot, see [Joining the `_all` aggregate slot](#joining-the-_all-aggregate-slot).
+- The tunnel error codes: `-32001` when the provider's credentials do not allow publishing on the requested slot, `-32000` when the slot is unavailable.
+
+When the broker refuses a slot, the transport surfaces it through `onError` rather than forwarding it. An id-less error frame handed to an MCP server would be classified as an unknown notification and dropped without a word, so the publisher would never learn it was refused.
 
 Malformed frames decode to `undefined` rather than throwing: a tunnel socket is a public surface, and a peer sending garbage must not take the receiver down.
 
 ## Transports
 
-| Transport | Use case |
-|---|---|
-| `MultiplexTransport` | Several servers published by one application. A single socket carries them all, keyed by slot name |
-| `DirectTransport` | One server, one socket, on `ws://<broker>/provider/<name>` |
+| Transport | Endpoint it speaks to | Framing | Reconnects | Use case |
+|---|---|---|---|---|
+| `MultiplexTransport` | the shared multiplex base, `ws://<broker>/providers` | envelopes `{ provider, payload }` | yes, on the shared socket | Several servers published by one application. A single socket carries them all, keyed by slot name |
+| `DirectTransport` | a slot-scoped path, `ws://<broker>/provider/<name>` | plain JSON-RPC frames | **no** | One server, one socket |
+
+**The transport and the path are a pair, not a preference.** The broker decides framing from the endpoint the socket landed on, so a mismatch does not fail the handshake: the socket opens, looks healthy, and every frame is dropped on one side or the other with nothing logged by the broker. Both transports warn on the console when they spot the mismatch at connect time. And `ws://<broker>/providers/<name>`, the natural-looking blend of the two, is neither: the broker accepts it as a *client* connection on a slot of that name.
 
 ```ts
 import { McpServerBuilder } from "@cyanmycelium/mcp-core/server";
@@ -61,15 +65,59 @@ const server = new McpServerBuilder()
 await server.start();
 ```
 
-Transports created for the same tunnel URL share one WebSocket, whichever order they are opened in. Reconnection is handled by that shared socket, with exponential back-off and jitter; individual transports never reconnect on their own.
+Transports created for the same tunnel URL share one WebSocket, whichever order they are opened in. Reconnection is handled by that shared socket, with exponential back-off and jitter, and individual transports never reconnect on their own. `DirectTransport` does not reconnect at all: when its socket closes it stays closed, and the application decides whether to call `connect()` again.
+
+`server.start()` resolving means the transport reported itself open, not that the broker accepted the slot. A refusal arrives afterwards, and reaches you as an `onError` on the transport and a line on the console.
 
 `@cyanmycelium/mcp-core` is a peer dependency: the transports import its `IMessageTransport` type and nothing else at runtime, so your application keeps a single copy of it.
 
+## Joining the `_all` aggregate slot
+
+The broker publishes an aggregate slot, `_all`, which exposes every opted-in provider's tools and prompts through one MCP connection. Membership is opt-in, because `_all` is a confidentiality boundary: a provider that does not ask for it stays reachable only on its own slot.
+
+```ts
+import { DirectTransport, MultiplexTransport } from "@cyanmycelium/mcp-broker-provider";
+
+// One socket per server
+const direct = new DirectTransport("ws://localhost:3000/provider/scene-1", { aggregate: true });
+
+// Or on the shared tunnel
+const shared = MultiplexTransport.create("scene-1", "ws://localhost:3000/providers", { aggregate: true });
+```
+
+Either form sends the registration notification with `params: { aggregate: true }` as its first frame:
+
+```json
+{ "jsonrpc": "2.0", "method": "notifications/register", "params": { "aggregate": true } }
+```
+
+`DirectTransport` sends it verbatim, since the slot-scoped path carries plain JSON-RPC and the broker already knows the slot name from the URL. `MultiplexTransport` sends it inside the usual envelope, as `{ "provider": "scene-1", "payload": { ... } }`.
+
+**Wire the message handler before you connect.** The broker runs `initialize` against a newly aggregated provider immediately, and a provider that does not answer is dropped from `_all` silently. Handing the transport to an MCP server does this for you, since the server assigns `onMessage` before calling `connect()`. Assigning it yourself, after connecting, loses the handshake and the provider never appears in the aggregate.
+
+## Diagnostics
+
+This stack used to fail quietly. The transports now name what went wrong, on the console, because a browser-hosted provider has nowhere else to report:
+
+- A frame written before the socket is open is queued (64 frames, oldest dropped first with a warning) and flushed on open, rather than discarded. That window covers the whole reconnect back-off, up to 30 seconds.
+- A close with a code other than `1000` is reported through `onError` with the code and the broker's own reason, before `onClose`. A `1008` is a policy refusal: the slot is already connected, is reserved, or provider authentication rejected it.
+- An incoming frame that is not an envelope, or one for a slot this socket does not publish, is logged with the likely cause and the fix. Repeats are sampled (the first in full, then one in fifty) so a mismatched tunnel cannot flood the console.
+
+## In a browser
+
+The transports are written for the browser, but the npm path needs a bundler: neither this package nor `@cyanmycelium/mcp-core` ships a UMD build or declares a `browser` field, so a bare `<script>` tag will not load them. Any bundler works; there is nothing to configure beyond resolving the two packages.
+
+Import only the isomorphic entry points. `@cyanmycelium/mcp-core/server` and `@cyanmycelium/mcp-core/client` run in a browser; `@cyanmycelium/mcp-core/node` does not, and pulling it in is the usual cause of a build that fails on Node built-ins.
+
+If you would rather not add a build step, the broker ships a dependency-free ES module that speaks the same tunnel, `web/js/lib/broker-tunnel.js` (inside the `@cyanmycelium/mcp-broker` package, at `node/packages/broker/web` in the repository). It is the zero-build alternative, not a replacement: it carries no MCP server implementation.
+
+One limitation worth knowing before you deploy: if the broker is configured with provider authentication, a browser-hosted provider cannot connect. The broker reads its credential from the `X-Provider-Token` or `Authorization` header of the upgrade request, and the browser `WebSocket` constructor cannot set headers, so the handshake is refused with a 401 the page sees only as a generic error. A browser provider needs provider auth off, or an authenticating reverse proxy in front of the broker.
+
 ## Status
 
-`0.1.0` ships the protocol module and both transports. They still exist in `@cyanmycelium/mcp-core@0.4.x` as well, and are removed there in `0.5.0` — migrate your imports before upgrading.
+This package is the only home of the tunnel transports. They also shipped in `@cyanmycelium/mcp-core@0.4.x`, were removed there in `0.5.0`, and are absent from `0.7.x` and `1.x`, so migrate those imports here before upgrading `mcp-core`.
 
-The protocol is shared with the broker and, later, with the consumer side, so it is expected to graduate into its own `@cyanmycelium/mcp-broker-core` package. Import it through the `./protocol` subpath rather than the package root and that move will cost you one line.
+The protocol is shared with the broker, and later with the consumer side. Import it through the `./protocol` subpath rather than the package root, so it can move to a package of its own one day without touching your call sites.
 
 ## License
 

package/dist/index.d.ts

@@ -1,11 +1,214 @@
+export { ITunnelRegisterOptions, TUNNEL_REGISTER_METHOD, TunnelEnvelope, TunnelError, TunnelErrorCode, TunnelErrorCodes, decodeEnvelope, encodeEnvelope, encodeEnvelopeMessage, encodeErrorEnvelope, encodeRegisterEnvelope, encodeRegisterFrame, envelopeFrame, tunnelErrorOf } from './protocol/index.js';
+import { IMessageTransport } from '@cyanmycelium/mcp-core';
+
+/** Options accepted by {@link DirectTransport}. */
+interface IDirectTransportOptions {
+    /**
+     * Join the broker's `_all` aggregate slot as well as this provider's own
+     * slot, by sending the registration notification
+     * `{"jsonrpc":"2.0","method":"notifications/register","params":{"aggregate":true}}`
+     * as the first frame on the socket.
+     *
+     * Opt-in on purpose: `_all` exposes this provider's tools and prompts to
+     * every client of the aggregate slot, so a provider that does not ask for it
+     * stays reachable only on its own slot.
+     *
+     * ORDERING: the broker runs `initialize` against a newly aggregated provider
+     * immediately, and drops it from `_all` without a word if the handshake times
+     * out. The frame therefore goes out on `open`, never from the constructor, so
+     * assign `onMessage` (or hand this transport to an MCP server, which assigns
+     * it for you) *before* calling {@link DirectTransport.connect}. Connecting
+     * first and wiring the handler afterwards loses the broker's `initialize` and
+     * the provider silently never appears in `_all`.
+     */
+    aggregate?: boolean;
+}
 /**
- * Provider side of the CyanMycelium MCP broker tunnel: what an application uses
- * to publish its MCP server to a broker slot.
+ * 1:1 WebSocket transport, wraps a single `WebSocket` connection to a broker
+ * provider slot, typically `ws://<broker>/provider/<name>`.
  *
- * 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.
+ * 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.
+ *
+ * This transport does **not** reconnect: when the socket closes, it stays
+ * closed until the application calls {@link connect} again. Only
+ * {@link MultiplexTransport}'s shared socket reconnects on its own.
+ *
+ * Call {@link connect} after setting the event callbacks to open the socket.
+ */
+declare class DirectTransport implements IMessageTransport {
+    private readonly _wsUrl;
+    private readonly _aggregate;
+    private readonly _pending;
+    /** Throttles the "wrote to a closed transport" line, which repeats per frame. */
+    private readonly _afterCloseNotice;
+    private _ws;
+    private _closed;
+    onMessage: ((data: string) => void) | null;
+    onOpen: (() => void) | null;
+    onClose: (() => void) | null;
+    onError: ((error: Error) => void) | null;
+    constructor(wsUrl: string, options?: IDirectTransportOptions);
+    get isOpen(): boolean;
+    /**
+     * Opens the WebSocket connection and wires its events to the transport
+     * callbacks. Must be called after assigning `onOpen` / `onMessage` / etc.
+     */
+    connect(): void;
+    send(data: string): void;
+    close(): void;
+    /**
+     * Sends the registration notification when the caller asked for a specific
+     * aggregate membership. The slot name is not in the frame: on the
+     * slot-scoped path the broker takes it from the URL at connect time.
+     */
+    private _sendRegistration;
+    /** Writes out everything queued while the socket was connecting. */
+    private _flush;
+    /**
+     * Builds the message for a close worth reporting, or `undefined` when there
+     * is nothing to say.
+     *
+     * A code of 1000 is a normal close and stays silent. An environment that
+     * calls `onclose` with no event at all leaves nothing to distinguish a
+     * refusal from a clean shutdown, so that stays silent too.
+     */
+    private _closeError;
+}
+
+/**
+ * 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.
+ */
+declare class MultiplexSocket {
+    /** Per-URL cache so all transports targeting the same tunnel share one socket. */
+    private static readonly _instances;
+    private readonly _wsUrl;
+    private readonly _transports;
+    /** Aggregate opt-in per slot, absent when the caller did not express one. */
+    private readonly _aggregates;
+    /** Frames written while the socket is connecting, reconnecting or backing off. */
+    private readonly _pending;
+    private _ws;
+    private _reconnectAttempts;
+    private _reconnectTimer;
+    private _stopped;
+    /** Set once the last transport left and this instance gave up its URL. */
+    private _dead;
+    /** The URL guard is about the URL, not the socket, so it is said once. */
+    private _pathWarned;
+    /** Throttles the "wrote to a closed tunnel" line, which repeats per frame. */
+    private readonly _afterStopNotice;
+    private constructor();
+    /** Returns (or creates) the singleton socket for a given tunnel URL. */
+    static getOrCreate(wsUrl: string): MultiplexSocket;
+    get isOpen(): boolean;
+    register(name: string, transport: MultiplexTransport, aggregate?: boolean): void;
+    unregister(name: string): void;
+    /**
+     * Brings a torn-down instance back into service when a transport that
+     * captured it is reactivated.
+     *
+     * Reclaims the URL when nothing else holds it. When another instance already
+     * does, the two would race for the same slot names, so this says exactly that
+     * rather than letting the loser fail with a refusal nobody reads.
+     */
+    private _revive;
+    /**
+     * 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.
+     *
+     * Carries the aggregate opt-in when the caller expressed one, which is why
+     * it must go out before any traffic: the broker runs `initialize` against a
+     * newly aggregated provider straight away.
+     */
+    private _announceProvider;
+    send(provider: string, data: string): void;
+    private _connect;
+    /** Writes out everything queued while the socket was down. */
+    private _flush;
+    private _routeIncoming;
+    private _scheduleReconnect;
+    /** Disarms a pending reconnect, so nothing opens a socket behind our back. */
+    private _cancelReconnect;
+}
+/** Options accepted by {@link MultiplexTransport.create}. */
+interface IMultiplexTransportOptions {
+    /**
+     * Join the broker's `_all` aggregate slot as well as this provider's own
+     * slot, by carrying `params: { aggregate: true }` on the registration
+     * notification the shared socket sends when it claims the slot.
+     *
+     * Opt-in on purpose: `_all` exposes this provider's tools and prompts to
+     * every client of the aggregate slot, so a provider that does not ask for it
+     * stays reachable only on its own slot.
+     *
+     * ORDERING: the broker runs `initialize` against a newly aggregated provider
+     * immediately, and drops it from `_all` without a word if the handshake times
+     * out. The registration goes out from {@link MultiplexTransport.connect}, so
+     * assign `onMessage` (or hand this transport to an MCP server, which assigns
+     * it for you) *before* connecting. Connecting first and wiring the handler
+     * afterwards loses the broker's `initialize`, and the provider silently never
+     * appears in `_all`.
+     */
+    aggregate?: boolean;
+}
+/**
+ * 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 * from "./protocol/index";
-export { DirectTransport } from "./direct.transport";
-export { MultiplexTransport } from "./multiplex.transport";
+declare class MultiplexTransport implements IMessageTransport {
+    private readonly _name;
+    private readonly _socket;
+    private readonly _aggregate;
+    private _registered;
+    onMessage: ((data: string) => void) | null;
+    onOpen: (() => void) | null;
+    onClose: (() => void) | null;
+    onError: ((error: Error) => void) | null;
+    constructor(name: string, socket: MultiplexSocket, options?: IMultiplexTransportOptions);
+    /**
+     * 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.
+     *
+     * @param wsUrl The broker's shared multiplex base, `ws://<broker>/providers`.
+     *              A slot-scoped `/provider/<name>` URL belongs to
+     *              {@link DirectTransport} and is warned about on connect.
+     */
+    static create(name: string, wsUrl: string, options?: IMultiplexTransportOptions): MultiplexTransport;
+    get isOpen(): boolean;
+    /**
+     * Registers this transport with the shared socket.
+     *
+     * Safe to call multiple times, subsequent calls are no-ops.
+     */
+    activate(): void;
+    /**
+     * 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(): void;
+    send(data: string): void;
+    close(): void;
+}
+
+export { DirectTransport, type IDirectTransportOptions, type IMultiplexTransportOptions, MultiplexTransport };