@orkestrel/mcp 0.0.13 → 0.0.15

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';
@@ -242,7 +243,7 @@ export declare function createMCPPostHandler<TState = unknown>(mcp: MCPDispatche
  * const routes = createMCPRoutes(createMCPLegacy(mcp)) // both eras; pass `mcp` for modern only
  * ```
  */
-export declare function createMCPRoutes<TState = unknown>(mcp: MCPDispatcherInterface, options?: HTTPTransportOptions<TState>): readonly RouteInput<string, TState>[];
+export declare function createMCPRoutes<TState = unknown>(mcp: MCPDispatcherInterface, options?: HTTPTransportOptions<TState>): ReadonlyArray<RouteInput<string, TState>>;
 
 /**
  * Create the native MCP session {@link MiddlewareHandler} — the plug-and-play stateful layer
@@ -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';
@@ -242,7 +243,7 @@ export declare function createMCPPostHandler<TState = unknown>(mcp: MCPDispatche
  * const routes = createMCPRoutes(createMCPLegacy(mcp)) // both eras; pass `mcp` for modern only
  * ```
  */
-export declare function createMCPRoutes<TState = unknown>(mcp: MCPDispatcherInterface, options?: HTTPTransportOptions<TState>): readonly RouteInput<string, TState>[];
+export declare function createMCPRoutes<TState = unknown>(mcp: MCPDispatcherInterface, options?: HTTPTransportOptions<TState>): ReadonlyArray<RouteInput<string, TState>>;
 
 /**
  * Create the native MCP session {@link MiddlewareHandler} — the plug-and-play stateful layer
@@ -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.js

@@ -1601,13 +1601,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
 *
@@ -1617,12 +1625,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 (!isString(upgrade) || upgrade.toLowerCase() !== "websocket") return false;
@@ -1637,6 +1649,8 @@ function createWebSocketServer(mcp, options) {
 			head,
 			protocol: subprotocol
 		}));
+		live.add(transport);
+		transport.emitter.on("close", () => live.delete(transport));
 		bindServer(mcp, bridgeMessageTransport(transport));
 		transport.start();
 		return true;