@orkestrel/mcp 0.0.14 → 0.0.16

package/README.md

@@ -81,9 +81,8 @@ package's source and runs
 `@modelcontextprotocol/conformance@0.2.0-alpha.10` against MCP revision
 `2026-07-28`. The recorded result is **23 passed / 0 failed**. That is a
 genuine foreign MCP client driving this server end to end, and it is
-evidence about the wire. It fetches the runner from the npm registry, so it
-is a live-service project of its own and stays outside the hermetic
-`npm test`.
+evidence about the wire. It resolves the runner from `node_modules` and
+drives a loopback socket, so the run is offline and `npm test` gates it.
 
 **IDE integration is not claimed.** No IDE, editor, or agent host has driven
 this server. A claim about an external client stays unproven here until one

package/dist/src/browser/index.js

@@ -42,220 +42,6 @@ var DEFAULT_MCP_SERVER_VERSION = "1.0.0";
 */
 var MCP_WEBSOCKET_SUBPROTOCOL = "mcp";
 //#endregion
-//#region src/browser/transports/MessagePortTransport.ts
-/**
-* The browser-face `MessagePort` transport for the Model Context Protocol — a
-* {@link MCPTransportInterface} over a native `MessagePort`, the genuinely new
-* capability this face adds: MCP over `postMessage`.
-*
-* @remarks
-* - **Symmetric.** Unlike {@link import('./WebSocketClientTransport.js').WebSocketClientTransport}
-*   / {@link import('./HTTPClientTransport.js').HTTPClientTransport} (CLIENT-only
-*   carriers of `@src/core`'s `MCPClientTransportInterface`), a `MessagePort` is a
-*   plain duplex channel — the SAME class implements `@src/core`'s
-*   `MCPTransportInterface` and is handed to EITHER `bindServer` or
-*   `bindClient`/`createDuplexClientTransport`; which role it plays comes entirely
-*   from the binder it is given to, not from anything this class decides.
-* - **`start()` at construction — bind synchronously.** `MessagePort.start()` is only
-*   REQUIRED when listening via `addEventListener` (as opposed to the `onmessage`
-*   setter, which implies it) — this transport uses `addEventListener`, and
-*   `MCPTransportInterface` has no separate open/connect step for the caller to hook
-*   a start into, so the constructor calls `port.start()` immediately: the port
-*   begins dispatching QUEUED messages the moment the transport exists. This is safe
-*   inside `serveMCP`'s flow (the transport is synchronously handed to `bindServer`
-*   before control returns to the event loop), but is a **footgun for direct use**:
-*   if you construct `new MessagePortTransport({ port })` and then `await` anything
-*   before calling `listen`, messages that arrived in the gap are DROPPED. **Bind
-*   synchronously after construction** — do not interleave an `await` between
-*   `new MessagePortTransport(…)` and `bindServer` / `listen`.
-* - **String payloads only.** `send` posts the message string as-is (`postMessage`
-*   structured-clones it — a string clones to an identical string, so the wire stays
-*   plain JSON-RPC text like every other transport in this package). Inbound: a
-*   non-string `event.data` (a host or a misbehaving peer posting a structured
-*   object) is IGNORED — dropped silently, never forwarded, never thrown (§14) —
-*   because `MCPTransportInterface` carries no `error` channel for this port to
-*   surface a non-string frame on (unlike `MCPClientTransportInterface`'s `emitter`);
-*   silently ignoring is the total, contract-shaped choice.
-* - **`messageerror` is IGNORED, not routed to `closed`.** A `messageerror` event
-*   (the structured-clone deserialization of an inbound message threw) reports one
-*   BAD FRAME, not a dead channel — the port itself keeps working and later, well-
-*   formed messages still arrive. Routing it to `closed` would tear down the
-*   `bindServer`/`bindClient` wiring (and, transitively, every session it carries)
-*   over a single malformed frame, which is far more destructive than dropping that
-*   one frame — so this transport registers a `messageerror` listener that does
-*   nothing, deliberately.
-* - **`close()`** is idempotent: it closes the underlying `port` (`MessagePort.close()`
-*   disconnects it — further `postMessage` calls on EITHER end are silently
-*   undelivered, per the platform contract) and fires the registered `closed`
-*   handler exactly once, whether the caller closes it once or twice. There is no
-*   native "peer closed" signal for a `MessagePort` (unlike a WebSocket's `close`
-*   event) — `closed` fires ONLY from this transport's own `close()`.
-* - **Single-handler-replace (the port contract, `@src/core`'s `MCPTransportInterface`
-*   doc).** `listen`/`closed` each hold the ONE currently registered handler; a
-*   second call REPLACES the first rather than adding a second subscriber.
-*
-* @example
-* ```ts
-* const { port1, port2 } = new MessageChannel()
-* const serverTransport = new MessagePortTransport({ port: port1 })
-* bindServer(server, serverTransport) // port1 side dispatches inbound requests
-*
-* const clientTransport = new MessagePortTransport({ port: port2 })
-* const client = createMCPClient({ transport: createDuplexClientTransport(clientTransport) })
-* bindClient(client, clientTransport) // port2 side is the client's carrier
-* ```
-*/
-var MessagePortTransport = class {
-	#port;
-	#onMessage = void 0;
-	#onClosed = void 0;
-	#closed = false;
-	constructor(options) {
-		this.#port = options.port;
-		this.#port.addEventListener("message", (event) => this.#receive(event.data));
-		this.#port.addEventListener("messageerror", () => {});
-		this.#port.start();
-	}
-	send(message) {
-		if (this.#closed) return;
-		this.#port.postMessage(message);
-	}
-	listen(handler) {
-		this.#onMessage = handler;
-	}
-	closed(handler) {
-		this.#onClosed = handler;
-	}
-	close() {
-		if (this.#closed) return;
-		this.#closed = true;
-		this.#port.close();
-		this.#onClosed?.();
-	}
-	#receive(data) {
-		if (!isString(data)) return;
-		this.#onMessage?.(data);
-	}
-};
-//#endregion
-//#region src/browser/helpers.ts
-/**
-* Decode one SSE event's `data` string into a {@link JSONRPCMessage}, or `undefined`
-* when it is not one — the per-event step {@link readEventStream} folds over.
-*
-* @remarks
-* `JSON.parse`s the `data` (the server serializes the JSON-RPC envelope as the
-* event's `data`) inside a try/catch and narrows the parsed value with
-* `parseJSONRPCMessage`. Total (§14): malformed JSON or a non-message value yields
-* `undefined`, never throws.
-*
-* @param data - One SSE event's `data` payload
-* @returns The decoded {@link JSONRPCMessage}, or `undefined`
-*/
-function decodeEvent(data) {
-	try {
-		return parseJSONRPCMessage(JSON.parse(data));
-	} catch {
-		return;
-	}
-}
-/**
-* Decode a `fetch` Response's Server-Sent-Events body into the JSON-RPC messages it
-* carried — the CLIENT-side inverse of the server's Streamable-HTTP SSE response.
-*
-* @remarks
-* Reads the whole `response.body` stream chunk-by-chunk through a `TextDecoder({
-* stream: true })` (handling a multi-byte char split across reads) and
-* `@orkestrel/sse`'s {@link SSEParserInterface} (handling a partial line / in-progress
-* event split across reads), then narrows each dispatched event's `data` to a
-* {@link JSONRPCMessage} via {@link decodeEvent} (so a non-message / non-JSON `data:`
-* event is DROPPED, never thrown — total, §14). A `null` body (no stream) yields no
-* messages; {@link import('./transports/HTTPClientTransport.js').HTTPClientTransport}
-* reads a request/response SSE reply (the server sends one `data:` event then ends),
-* so this drains to completion.
-*
-* @param response - The SSE `fetch` Response to decode (its `body` is read to completion)
-* @returns Every {@link JSONRPCMessage} the stream carried, in order
-*/
-async function readEventStream(response) {
-	const body = response.body;
-	if (body === null) return [];
-	const reader = body.getReader();
-	const decoder = new TextDecoder();
-	const parser = createSSEParser();
-	const messages = [];
-	try {
-		for (;;) {
-			const { done, value } = await reader.read();
-			if (done) break;
-			for (const event of parser.parse(decoder.decode(value, { stream: true }))) {
-				const message = decodeEvent(event.data);
-				if (message !== void 0) messages.push(message);
-			}
-		}
-	} finally {
-		reader.releaseLock();
-	}
-	return messages;
-}
-/**
-* Build `serveMCPScope`'s `message`-event listener — the unified
-* dispatcher that routes EVERY inbound event on a hostable scope, portless or
-* port-bearing, to the right binding.
-*
-* @remarks
-* Port-bearing events (`event.ports.length > 0`) are gated by `options.accept` FIRST
-* — when the gate returns `false` the event is dropped entirely (no binding, no reply).
-* Accepted events spawn a fresh `MessagePortTransport` over `event.ports[0]`,
-* `bindServer` `server` onto it, and record a teardown (`unbind` then `transport.close()`)
-* into `teardowns`. A port that was already seen is IGNORED — repeated delivery of the
-* same `MessagePort` would create duplicate bindings over one port (→ duplicated replies),
-* so the listener tracks seen ports and silently drops repeats.
-*
-* This branch fires on EITHER a Service-Worker-shaped scope (its normal per-client
-* channel) or a dedicated-worker-shaped one that happens to receive a port-bearing event
-* (the unified design's deliberate cross-case, needing no upfront shape flag). An event
-* with NO ports and a STRING `data` is pushed onto `scopeTransport.deliver` (the
-* implicit, already-bound scope channel); any other event (no ports, non-string data)
-* is silently dropped — total (§14), never throws.
-*
-* @param server - The `MCPServerInterface` every spawned/implicit binding dispatches over
-* @param scopeTransport - The implicit scope channel (already `bindServer`-bound) portless events deliver onto
-* @param teardowns - The shared teardown set `serveMCPScope`'s dispose drains; each port-bearing event adds one entry
-* @param options - The `ServeMCPOptions` (for `options.accept`)
-* @returns The `message`-event listener to register (and later remove) on the scope
-*
-* @example
-* ```ts
-* const teardowns = new Set<() => void>()
-* const scopeTransport = createScopeTransport(scope)
-* bindServer(server, scopeTransport)
-* const onMessage = createScopeMessageListener(server, scopeTransport, teardowns, options)
-* scope.addEventListener('message', onMessage)
-* ```
-*/
-function createScopeMessageListener(server, scopeTransport, teardowns, options) {
-	const seen = /* @__PURE__ */ new Set();
-	return (event) => {
-		const ports = event.ports;
-		if (ports.length > 0) {
-			if (options.accept !== void 0 && !options.accept(event)) return;
-			const port = ports[0];
-			if (port === void 0) return;
-			if (seen.has(port)) return;
-			seen.add(port);
-			const transport = new MessagePortTransport({ port });
-			const unbind = bindServer(server, transport);
-			teardowns.add(() => {
-				unbind();
-				transport.close();
-			});
-			return;
-		}
-		if (isString(event.data)) scopeTransport.deliver(event.data);
-	};
-}
-//#endregion
 //#region src/browser/transports/HTTPClientTransport.ts
 /**
 * The browser-face HTTP CLIENT transport for the Model Context Protocol — a
@@ -391,6 +177,102 @@ var HTTPClientTransport = class {
 	}
 };
 //#endregion
+//#region src/browser/transports/MessagePortTransport.ts
+/**
+* The browser-face `MessagePort` transport for the Model Context Protocol — a
+* {@link MCPTransportInterface} over a native `MessagePort`, the genuinely new
+* capability this face adds: MCP over `postMessage`.
+*
+* @remarks
+* - **Symmetric.** Unlike {@link import('./WebSocketClientTransport.js').WebSocketClientTransport}
+*   / {@link import('./HTTPClientTransport.js').HTTPClientTransport} (CLIENT-only
+*   carriers of `@src/core`'s `MCPClientTransportInterface`), a `MessagePort` is a
+*   plain duplex channel — the SAME class implements `@src/core`'s
+*   `MCPTransportInterface` and is handed to EITHER `bindServer` or
+*   `bindClient`/`createDuplexClientTransport`; which role it plays comes entirely
+*   from the binder it is given to, not from anything this class decides.
+* - **`start()` at construction — bind synchronously.** `MessagePort.start()` is only
+*   REQUIRED when listening via `addEventListener` (as opposed to the `onmessage`
+*   setter, which implies it) — this transport uses `addEventListener`, and
+*   `MCPTransportInterface` has no separate open/connect step for the caller to hook
+*   a start into, so the constructor calls `port.start()` immediately: the port
+*   begins dispatching QUEUED messages the moment the transport exists. This is safe
+*   inside `serveMCP`'s flow (the transport is synchronously handed to `bindServer`
+*   before control returns to the event loop), but is a **footgun for direct use**:
+*   if you construct `new MessagePortTransport({ port })` and then `await` anything
+*   before calling `listen`, messages that arrived in the gap are DROPPED. **Bind
+*   synchronously after construction** — do not interleave an `await` between
+*   `new MessagePortTransport(…)` and `bindServer` / `listen`.
+* - **String payloads only.** `send` posts the message string as-is (`postMessage`
+*   structured-clones it — a string clones to an identical string, so the wire stays
+*   plain JSON-RPC text like every other transport in this package). Inbound: a
+*   non-string `event.data` (a host or a misbehaving peer posting a structured
+*   object) is IGNORED — dropped silently, never forwarded, never thrown (§14) —
+*   because `MCPTransportInterface` carries no `error` channel for this port to
+*   surface a non-string frame on (unlike `MCPClientTransportInterface`'s `emitter`);
+*   silently ignoring is the total, contract-shaped choice.
+* - **`messageerror` is IGNORED, not routed to `closed`.** A `messageerror` event
+*   (the structured-clone deserialization of an inbound message threw) reports one
+*   BAD FRAME, not a dead channel — the port itself keeps working and later, well-
+*   formed messages still arrive. Routing it to `closed` would tear down the
+*   `bindServer`/`bindClient` wiring (and, transitively, every session it carries)
+*   over a single malformed frame, which is far more destructive than dropping that
+*   one frame — so this transport registers a `messageerror` listener that does
+*   nothing, deliberately.
+* - **`close()`** is idempotent: it closes the underlying `port` (`MessagePort.close()`
+*   disconnects it — further `postMessage` calls on EITHER end are silently
+*   undelivered, per the platform contract) and fires the registered `closed`
+*   handler exactly once, whether the caller closes it once or twice. There is no
+*   native "peer closed" signal for a `MessagePort` (unlike a WebSocket's `close`
+*   event) — `closed` fires ONLY from this transport's own `close()`.
+* - **Single-handler-replace (the port contract, `@src/core`'s `MCPTransportInterface`
+*   doc).** `listen`/`closed` each hold the ONE currently registered handler; a
+*   second call REPLACES the first rather than adding a second subscriber.
+*
+* @example
+* ```ts
+* const { port1, port2 } = new MessageChannel()
+* const serverTransport = new MessagePortTransport({ port: port1 })
+* bindServer(server, serverTransport) // port1 side dispatches inbound requests
+*
+* const clientTransport = new MessagePortTransport({ port: port2 })
+* const client = createMCPClient({ transport: createDuplexClientTransport(clientTransport) })
+* bindClient(client, clientTransport) // port2 side is the client's carrier
+* ```
+*/
+var MessagePortTransport = class {
+	#port;
+	#onMessage = void 0;
+	#onClosed = void 0;
+	#closed = false;
+	constructor(options) {
+		this.#port = options.port;
+		this.#port.addEventListener("message", (event) => this.#receive(event.data));
+		this.#port.addEventListener("messageerror", () => {});
+		this.#port.start();
+	}
+	send(message) {
+		if (this.#closed) return;
+		this.#port.postMessage(message);
+	}
+	listen(handler) {
+		this.#onMessage = handler;
+	}
+	closed(handler) {
+		this.#onClosed = handler;
+	}
+	close() {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.#port.close();
+		this.#onClosed?.();
+	}
+	#receive(data) {
+		if (!isString(data)) return;
+		this.#onMessage?.(data);
+	}
+};
+//#endregion
 //#region src/browser/transports/WebSocketClientTransport.ts
 /**
 * The browser-face WebSocket CLIENT transport for the Model Context Protocol — a
@@ -671,6 +553,124 @@ function createScopeTransport(scope) {
 		}
 	};
 }
+//#endregion
+//#region src/browser/helpers.ts
+/**
+* Decode one SSE event's `data` string into a {@link JSONRPCMessage}, or `undefined`
+* when it is not one — the per-event step {@link readEventStream} folds over.
+*
+* @remarks
+* `JSON.parse`s the `data` (the server serializes the JSON-RPC envelope as the
+* event's `data`) inside a try/catch and narrows the parsed value with
+* `parseJSONRPCMessage`. Total (§14): malformed JSON or a non-message value yields
+* `undefined`, never throws.
+*
+* @param data - One SSE event's `data` payload
+* @returns The decoded {@link JSONRPCMessage}, or `undefined`
+*/
+function decodeEvent(data) {
+	try {
+		return parseJSONRPCMessage(JSON.parse(data));
+	} catch {
+		return;
+	}
+}
+/**
+* Decode a `fetch` Response's Server-Sent-Events body into the JSON-RPC messages it
+* carried — the CLIENT-side inverse of the server's Streamable-HTTP SSE response.
+*
+* @remarks
+* Reads the whole `response.body` stream chunk-by-chunk through a `TextDecoder({
+* stream: true })` (handling a multi-byte char split across reads) and
+* `@orkestrel/sse`'s {@link SSEParserInterface} (handling a partial line / in-progress
+* event split across reads), then narrows each dispatched event's `data` to a
+* {@link JSONRPCMessage} via {@link decodeEvent} (so a non-message / non-JSON `data:`
+* event is DROPPED, never thrown — total, §14). A `null` body (no stream) yields no
+* messages; {@link import('./transports/HTTPClientTransport.js').HTTPClientTransport}
+* reads a request/response SSE reply (the server sends one `data:` event then ends),
+* so this drains to completion.
+*
+* @param response - The SSE `fetch` Response to decode (its `body` is read to completion)
+* @returns Every {@link JSONRPCMessage} the stream carried, in order
+*/
+async function readEventStream(response) {
+	const body = response.body;
+	if (body === null) return [];
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	const parser = createSSEParser();
+	const messages = [];
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			for (const event of parser.parse(decoder.decode(value, { stream: true }))) {
+				const message = decodeEvent(event.data);
+				if (message !== void 0) messages.push(message);
+			}
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	return messages;
+}
+/**
+* Build `serveMCPScope`'s `message`-event listener — the unified
+* dispatcher that routes EVERY inbound event on a hostable scope, portless or
+* port-bearing, to the right binding.
+*
+* @remarks
+* Port-bearing events (`event.ports.length > 0`) are gated by `options.accept` FIRST
+* — when the gate returns `false` the event is dropped entirely (no binding, no reply).
+* Accepted events spawn a fresh `MessagePortTransport` over `event.ports[0]`,
+* `bindServer` `server` onto it, and record a teardown (`unbind` then `transport.close()`)
+* into `teardowns`. A port that was already seen is IGNORED — repeated delivery of the
+* same `MessagePort` would create duplicate bindings over one port (→ duplicated replies),
+* so the listener tracks seen ports and silently drops repeats.
+*
+* This branch fires on EITHER a Service-Worker-shaped scope (its normal per-client
+* channel) or a dedicated-worker-shaped one that happens to receive a port-bearing event
+* (the unified design's deliberate cross-case, needing no upfront shape flag). An event
+* with NO ports and a STRING `data` is pushed onto `scopeTransport.deliver` (the
+* implicit, already-bound scope channel); any other event (no ports, non-string data)
+* is silently dropped — total (§14), never throws.
+*
+* @param server - The `MCPServerInterface` every spawned/implicit binding dispatches over
+* @param scopeTransport - The implicit scope channel (already `bindServer`-bound) portless events deliver onto
+* @param teardowns - The shared teardown set `serveMCPScope`'s dispose drains; each port-bearing event adds one entry
+* @param options - The `ServeMCPOptions` (for `options.accept`)
+* @returns The `message`-event listener to register (and later remove) on the scope
+*
+* @example
+* ```ts
+* const teardowns = new Set<() => void>()
+* const scopeTransport = createScopeTransport(scope)
+* bindServer(server, scopeTransport)
+* const onMessage = createScopeMessageListener(server, scopeTransport, teardowns, options)
+* scope.addEventListener('message', onMessage)
+* ```
+*/
+function createScopeMessageListener(server, scopeTransport, teardowns, options) {
+	const seen = /* @__PURE__ */ new Set();
+	return (event) => {
+		const ports = event.ports;
+		if (ports.length > 0) {
+			if (options.accept !== void 0 && !options.accept(event)) return;
+			const port = ports[0];
+			if (port === void 0) return;
+			if (seen.has(port)) return;
+			seen.add(port);
+			const transport = new MessagePortTransport({ port });
+			const unbind = bindServer(server, transport);
+			teardowns.add(() => {
+				unbind();
+				transport.close();
+			});
+			return;
+		}
+		if (isString(event.data)) scopeTransport.deliver(event.data);
+	};
+}
 /**
 * Boot an `MCPServer` inside a hostable worker scope and wire its message events to it.
 *

package/dist/src/server/index.cjs

@@ -1602,13 +1602,21 @@ function createHTTPClientTransport(options) {
 *   as a frame — a NOTIFICATION sends nothing, and a non-request message (a stray response) is
 *   ignored. A `dispatch` / `send` fault surfaces on `mcp.emitter`'s `error` event rather than
 *   escaping the (async) message pump.
+* - **Closes on the spine's `stop`.** It holds every socket it claimed and, on `options.emitter`'s
+*   `stop` event, closes each one with the RFC 6455 close handshake, so the spine's drain settles
+*   at once and each client reads a clean goodbye. Node detaches an upgraded socket from the
+*   connection set the spine's own close walks, so the claimant is the only thing that can end
+*   it: an ingress that held its sockets open would cost `stop()` the whole `drain` budget and
+*   then have the connection cut mid-protocol. A socket the peer already dropped is gone from
+*   the set (its transport's `close` removes it), and closing a dead one is a no-op either way.
 *
 * It is MECHANISM, not policy: compose an auth guard IN FRONT by registering an upgrade
 * handler BEFORE this one — that handler can claim (decline + destroy) an unauthenticated
 * upgrade so it never reaches this pump.
 *
 * @param mcp - The transport-agnostic {@link MCPDispatcherInterface} to expose over WebSocket
-* @param options - Optional `path` (default {@link DEFAULT_MCP_PATH}) and `subprotocol`
+* @param options - The spine's `emitter` (REQUIRED — the `stop` event this ingress closes its
+*   sockets on), plus optional `path` (default {@link DEFAULT_MCP_PATH}) and `subprotocol`
 *   (default {@link MCP_WEBSOCKET_SUBPROTOCOL}); see {@link WebSocketServerOptions}
 * @returns An {@link UpgradeHandler} to register with the spine's `upgrade` seam
 *
@@ -1618,12 +1626,16 @@ function createHTTPClientTransport(options) {
 * import { createWebSocketServer } from '@src/server'
 *
 * const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
-* server.upgrade(createWebSocketServer(mcp)) // an MCP client now connects over ws://…/mcp
+* server.upgrade(createWebSocketServer(mcp, { emitter: server.emitter })) // ws://…/mcp
 * ```
 */
 function createWebSocketServer(mcp, options) {
-	const path = options?.path ?? "/mcp";
-	const subprotocol = options?.subprotocol ?? "mcp";
+	const path = options.path ?? "/mcp";
+	const subprotocol = options.subprotocol ?? "mcp";
+	const live = /* @__PURE__ */ new Set();
+	options.emitter.on("stop", () => {
+		for (const transport of live) transport.close();
+	});
 	return (request, socket, head) => {
 		const upgrade = request.headers["upgrade"];
 		if (!(0, _orkestrel_contract.isString)(upgrade) || upgrade.toLowerCase() !== "websocket") return false;
@@ -1638,6 +1650,8 @@ function createWebSocketServer(mcp, options) {
 			head,
 			protocol: subprotocol
 		}));
+		live.add(transport);
+		transport.emitter.on("close", () => live.delete(transport));
 		(0, _src_core.bindServer)(mcp, bridgeMessageTransport(transport));
 		transport.start();
 		return true;

package/dist/src/server/index.d.cts

@@ -18,6 +18,7 @@ import { MiddlewareHandler } from '@orkestrel/server';
 import { NodeWebSocketInterface } from '@orkestrel/websocket';
 import { RouteContext } from '@orkestrel/router';
 import { RouteInput } from '@orkestrel/router';
+import { ServerEventMap } from '@orkestrel/server';
 import { StreamInterface } from '@orkestrel/server';
 import { TokenSecret } from '@orkestrel/server';
 import { UpgradeHandler } from '@orkestrel/server';
@@ -445,13 +446,21 @@ export declare function createWebSocketClientTransport(options: WebSocketClientT
  *   as a frame — a NOTIFICATION sends nothing, and a non-request message (a stray response) is
  *   ignored. A `dispatch` / `send` fault surfaces on `mcp.emitter`'s `error` event rather than
  *   escaping the (async) message pump.
+ * - **Closes on the spine's `stop`.** It holds every socket it claimed and, on `options.emitter`'s
+ *   `stop` event, closes each one with the RFC 6455 close handshake, so the spine's drain settles
+ *   at once and each client reads a clean goodbye. Node detaches an upgraded socket from the
+ *   connection set the spine's own close walks, so the claimant is the only thing that can end
+ *   it: an ingress that held its sockets open would cost `stop()` the whole `drain` budget and
+ *   then have the connection cut mid-protocol. A socket the peer already dropped is gone from
+ *   the set (its transport's `close` removes it), and closing a dead one is a no-op either way.
  *
  * It is MECHANISM, not policy: compose an auth guard IN FRONT by registering an upgrade
  * handler BEFORE this one — that handler can claim (decline + destroy) an unauthenticated
  * upgrade so it never reaches this pump.
  *
  * @param mcp - The transport-agnostic {@link MCPDispatcherInterface} to expose over WebSocket
- * @param options - Optional `path` (default {@link DEFAULT_MCP_PATH}) and `subprotocol`
+ * @param options - The spine's `emitter` (REQUIRED — the `stop` event this ingress closes its
+ *   sockets on), plus optional `path` (default {@link DEFAULT_MCP_PATH}) and `subprotocol`
  *   (default {@link MCP_WEBSOCKET_SUBPROTOCOL}); see {@link WebSocketServerOptions}
  * @returns An {@link UpgradeHandler} to register with the spine's `upgrade` seam
  *
@@ -461,10 +470,10 @@ export declare function createWebSocketClientTransport(options: WebSocketClientT
  * import { createWebSocketServer } from '@src/server'
  *
  * const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
- * server.upgrade(createWebSocketServer(mcp)) // an MCP client now connects over ws://…/mcp
+ * server.upgrade(createWebSocketServer(mcp, { emitter: server.emitter })) // ws://…/mcp
  * ```
  */
-export declare function createWebSocketServer(mcp: MCPDispatcherInterface, options?: WebSocketServerOptions): UpgradeHandler;
+export declare function createWebSocketServer(mcp: MCPDispatcherInterface, options: WebSocketServerOptions): UpgradeHandler;
 
 /**
  * Decode one SSE event's `data` string into a {@link JSONRPCMessage}, or `undefined`
@@ -1427,10 +1436,16 @@ export declare interface WebSocketClientTransportOptions {
 }
 
 /**
- * Options for `createWebSocketServer` — where the WebSocket upgrade is accepted and the
- * subprotocol negotiated.
+ * Options for `createWebSocketServer` — the spine lifecycle the ingress follows, plus where
+ * the WebSocket upgrade is accepted and the subprotocol negotiated.
  *
  * @remarks
+ * - `emitter` — the emitter of the `@orkestrel/server` spine this handler is registered on
+ *   (`server.emitter`). REQUIRED: on its `stop` event the handler closes every socket it
+ *   still owns with the RFC 6455 close handshake, so the spine's drain settles at once. An
+ *   upgraded socket is detached from the connection set the spine's own close walks, so
+ *   nothing but the claimant can end it — leave it open and `stop()` spends its whole
+ *   `drain` budget and then cuts the connection mid-protocol.
  * - `path` — the request path the upgrade handler CLAIMS; defaults to
  *   {@link import('./constants.js').DEFAULT_MCP_PATH} (`'/mcp'`, the same path the HTTP
  *   transport mounts at). A protocol-upgrade request to any OTHER path is DECLINED
@@ -1445,6 +1460,7 @@ export declare interface WebSocketClientTransportOptions {
  * before this one can decline an unauthenticated upgrade).
  */
 export declare interface WebSocketServerOptions {
+    readonly emitter: EmitterInterface<ServerEventMap>;
     readonly path?: string;
     readonly subprotocol?: string;
 }

package/dist/src/server/index.d.ts

@@ -18,6 +18,7 @@ import { MiddlewareHandler } from '@orkestrel/server';
 import { NodeWebSocketInterface } from '@orkestrel/websocket';
 import { RouteContext } from '@orkestrel/router';
 import { RouteInput } from '@orkestrel/router';
+import { ServerEventMap } from '@orkestrel/server';
 import { StreamInterface } from '@orkestrel/server';
 import { TokenSecret } from '@orkestrel/server';
 import { UpgradeHandler } from '@orkestrel/server';
@@ -445,13 +446,21 @@ export declare function createWebSocketClientTransport(options: WebSocketClientT
  *   as a frame — a NOTIFICATION sends nothing, and a non-request message (a stray response) is
  *   ignored. A `dispatch` / `send` fault surfaces on `mcp.emitter`'s `error` event rather than
  *   escaping the (async) message pump.
+ * - **Closes on the spine's `stop`.** It holds every socket it claimed and, on `options.emitter`'s
+ *   `stop` event, closes each one with the RFC 6455 close handshake, so the spine's drain settles
+ *   at once and each client reads a clean goodbye. Node detaches an upgraded socket from the
+ *   connection set the spine's own close walks, so the claimant is the only thing that can end
+ *   it: an ingress that held its sockets open would cost `stop()` the whole `drain` budget and
+ *   then have the connection cut mid-protocol. A socket the peer already dropped is gone from
+ *   the set (its transport's `close` removes it), and closing a dead one is a no-op either way.
  *
  * It is MECHANISM, not policy: compose an auth guard IN FRONT by registering an upgrade
  * handler BEFORE this one — that handler can claim (decline + destroy) an unauthenticated
  * upgrade so it never reaches this pump.
  *
  * @param mcp - The transport-agnostic {@link MCPDispatcherInterface} to expose over WebSocket
- * @param options - Optional `path` (default {@link DEFAULT_MCP_PATH}) and `subprotocol`
+ * @param options - The spine's `emitter` (REQUIRED — the `stop` event this ingress closes its
+ *   sockets on), plus optional `path` (default {@link DEFAULT_MCP_PATH}) and `subprotocol`
  *   (default {@link MCP_WEBSOCKET_SUBPROTOCOL}); see {@link WebSocketServerOptions}
  * @returns An {@link UpgradeHandler} to register with the spine's `upgrade` seam
  *
@@ -461,10 +470,10 @@ export declare function createWebSocketClientTransport(options: WebSocketClientT
  * import { createWebSocketServer } from '@src/server'
  *
  * const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
- * server.upgrade(createWebSocketServer(mcp)) // an MCP client now connects over ws://…/mcp
+ * server.upgrade(createWebSocketServer(mcp, { emitter: server.emitter })) // ws://…/mcp
  * ```
  */
-export declare function createWebSocketServer(mcp: MCPDispatcherInterface, options?: WebSocketServerOptions): UpgradeHandler;
+export declare function createWebSocketServer(mcp: MCPDispatcherInterface, options: WebSocketServerOptions): UpgradeHandler;
 
 /**
  * Decode one SSE event's `data` string into a {@link JSONRPCMessage}, or `undefined`
@@ -1427,10 +1436,16 @@ export declare interface WebSocketClientTransportOptions {
 }
 
 /**
- * Options for `createWebSocketServer` — where the WebSocket upgrade is accepted and the
- * subprotocol negotiated.
+ * Options for `createWebSocketServer` — the spine lifecycle the ingress follows, plus where
+ * the WebSocket upgrade is accepted and the subprotocol negotiated.
  *
  * @remarks
+ * - `emitter` — the emitter of the `@orkestrel/server` spine this handler is registered on
+ *   (`server.emitter`). REQUIRED: on its `stop` event the handler closes every socket it
+ *   still owns with the RFC 6455 close handshake, so the spine's drain settles at once. An
+ *   upgraded socket is detached from the connection set the spine's own close walks, so
+ *   nothing but the claimant can end it — leave it open and `stop()` spends its whole
+ *   `drain` budget and then cuts the connection mid-protocol.
  * - `path` — the request path the upgrade handler CLAIMS; defaults to
  *   {@link import('./constants.js').DEFAULT_MCP_PATH} (`'/mcp'`, the same path the HTTP
  *   transport mounts at). A protocol-upgrade request to any OTHER path is DECLINED
@@ -1445,6 +1460,7 @@ export declare interface WebSocketClientTransportOptions {
  * before this one can decline an unauthenticated upgrade).
  */
 export declare interface WebSocketServerOptions {
+    readonly emitter: EmitterInterface<ServerEventMap>;
     readonly path?: string;
     readonly subprotocol?: string;
 }