Merge branch 'main' into test/spec-type-key-parity-assertions

Author: felixweinberger

.changeset/fix-stdio-windows-hide.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/client': patch
+---
+
+Always set `windowsHide` when spawning stdio server processes on Windows, not just in Electron environments. Prevents unwanted console windows in non-Electron Windows applications.

.changeset/reconnection-scheduler.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/client': minor
+---
+
+Add `reconnectionScheduler` option to `StreamableHTTPClientTransport`. Lets non-persistent environments (serverless, mobile, desktop sleep/wake) override the default `setTimeout`-based SSE reconnection scheduling. The scheduler may return a cancel function that is invoked on `transport.close()`.

packages/client/src/client/stdio.ts

@@ -126,7 +126,7 @@ export class StdioClientTransport implements Transport {
                 },
                 stdio: ['pipe', 'pipe', this._serverParams.stderr ?? 'inherit'],
                 shell: false,
-                windowsHide: process.platform === 'win32' && isElectron(),
+                windowsHide: process.platform === 'win32',
                 cwd: this._serverParams.cwd
             });
 
@@ -258,7 +258,3 @@ export class StdioClientTransport implements Transport {
         });
     }
 }
-
-function isElectron() {
-    return 'type' in process;
-}

packages/client/src/client/streamableHttp.examples.ts

@@ -0,0 +1,31 @@
+/**
+ * Type-checked examples for `streamableHttp.ts`.
+ *
+ * These examples are synced into JSDoc comments via the sync-snippets script.
+ * Each function's region markers define the code snippet that appears in the docs.
+ *
+ * @module
+ */
+
+/* eslint-disable unicorn/consistent-function-scoping -- examples must live inside region blocks */
+
+import type { ReconnectionScheduler } from './streamableHttp.js';
+
+// Stub for a hypothetical platform-specific background scheduling API
+declare const platformBackgroundTask: {
+    schedule(callback: () => void, delay: number): number;
+    cancel(id: number): void;
+};
+
+/**
+ * Example: Using a platform background-task API to schedule reconnections.
+ */
+function ReconnectionScheduler_basicUsage() {
+    //#region ReconnectionScheduler_basicUsage
+    const scheduler: ReconnectionScheduler = (reconnect, delay) => {
+        const id = platformBackgroundTask.schedule(reconnect, delay);
+        return () => platformBackgroundTask.cancel(id);
+    };
+    //#endregion ReconnectionScheduler_basicUsage
+    return scheduler;
+}

packages/client/src/client/streamableHttp.ts

@@ -78,6 +78,31 @@ export interface StreamableHTTPReconnectionOptions {
     maxRetries: number;
 }
 
+/**
+ * Custom scheduler for SSE stream reconnection attempts.
+ *
+ * Called instead of `setTimeout` when the transport needs to schedule a reconnection.
+ * Useful in environments where `setTimeout` is unsuitable (serverless functions that
+ * terminate before the timer fires, mobile apps that need platform background scheduling,
+ * desktop apps handling sleep/wake).
+ *
+ * @param reconnect - Call this to perform the reconnection attempt.
+ * @param delay - Suggested delay in milliseconds (from backoff calculation).
+ * @param attemptCount - Zero-indexed retry attempt number.
+ * @returns An optional cancel function. If returned, it will be called on
+ * {@linkcode StreamableHTTPClientTransport.close | transport.close()} to abort the
+ * pending reconnection.
+ *
+ * @example
+ * ```ts source="./streamableHttp.examples.ts#ReconnectionScheduler_basicUsage"
+ * const scheduler: ReconnectionScheduler = (reconnect, delay) => {
+ *     const id = platformBackgroundTask.schedule(reconnect, delay);
+ *     return () => platformBackgroundTask.cancel(id);
+ * };
+ * ```
+ */
+export type ReconnectionScheduler = (reconnect: () => void, delay: number, attemptCount: number) => (() => void) | void;
+
 /**
  * Configuration options for the {@linkcode StreamableHTTPClientTransport}.
  */
@@ -116,6 +141,12 @@ export type StreamableHTTPClientTransportOptions = {
      */
     reconnectionOptions?: StreamableHTTPReconnectionOptions;
 
+    /**
+     * Custom scheduler for reconnection attempts. If not provided, `setTimeout` is used.
+     * See {@linkcode ReconnectionScheduler}.
+     */
+    reconnectionScheduler?: ReconnectionScheduler;
+
     /**
      * Session ID for the connection. This is used to identify the session on the server.
      * When not provided and connecting to a server that supports session IDs, the server will generate a new session ID.
@@ -150,7 +181,8 @@ export class StreamableHTTPClientTransport implements Transport {
     private _protocolVersion?: string;
     private _lastUpscopingHeader?: string; // Track last upscoping header to prevent infinite upscoping.
     private _serverRetryMs?: number; // Server-provided retry delay from SSE retry field
-    private _reconnectionTimeout?: ReturnType<typeof setTimeout>;
+    private readonly _reconnectionScheduler?: ReconnectionScheduler;
+    private _cancelReconnection?: () => void;
 
     onclose?: () => void;
     onerror?: (error: Error) => void;
@@ -172,6 +204,7 @@ export class StreamableHTTPClientTransport implements Transport {
         this._sessionId = opts?.sessionId;
         this._protocolVersion = opts?.protocolVersion;
         this._reconnectionOptions = opts?.reconnectionOptions ?? DEFAULT_STREAMABLE_HTTP_RECONNECTION_OPTIONS;
+        this._reconnectionScheduler = opts?.reconnectionScheduler;
     }
 
     private async _commonHeaders(): Promise<Headers> {
@@ -305,15 +338,26 @@ export class StreamableHTTPClientTransport implements Transport {
         // Calculate next delay based on current attempt count
         const delay = this._getNextReconnectionDelay(attemptCount);
 
-        // Schedule the reconnection
-        this._reconnectionTimeout = setTimeout(() => {
-            // Use the last event ID to resume where we left off
+        const reconnect = (): void => {
+            this._cancelReconnection = undefined;
+            if (this._abortController?.signal.aborted) return;
             this._startOrAuthSse(options).catch(error => {
                 this.onerror?.(new Error(`Failed to reconnect SSE stream: ${error instanceof Error ? error.message : String(error)}`));
-                // Schedule another attempt if this one failed, incrementing the attempt counter
-                this._scheduleReconnection(options, attemptCount + 1);
+                try {
+                    this._scheduleReconnection(options, attemptCount + 1);
+                } catch (scheduleError) {
+                    this.onerror?.(scheduleError instanceof Error ? scheduleError : new Error(String(scheduleError)));
+                }
             });
-        }, delay);
+        };
+
+        if (this._reconnectionScheduler) {
+            const cancel = this._reconnectionScheduler(reconnect, delay, attemptCount);
+            this._cancelReconnection = typeof cancel === 'function' ? cancel : undefined;
+        } else {
+            const handle = setTimeout(reconnect, delay);
+            this._cancelReconnection = () => clearTimeout(handle);
+        }
     }
 
     private _handleSseStream(stream: ReadableStream<Uint8Array> | null, options: StartSSEOptions, isReconnectable: boolean): void {
@@ -458,12 +502,13 @@ export class StreamableHTTPClientTransport implements Transport {
     }
 
     async close(): Promise<void> {
-        if (this._reconnectionTimeout) {
-            clearTimeout(this._reconnectionTimeout);
-            this._reconnectionTimeout = undefined;
+        try {
+            this._cancelReconnection?.();
+        } finally {
+            this._cancelReconnection = undefined;
+            this._abortController?.abort();
+            this.onclose?.();
         }
-        this._abortController?.abort();
-        this.onclose?.();
     }
 
     async send(

packages/client/src/index.ts

@@ -62,7 +62,12 @@ export type { SSEClientTransportOptions } from './client/sse.js';
 export { SSEClientTransport, SseError } from './client/sse.js';
 export type { StdioServerParameters } from './client/stdio.js';
 export { DEFAULT_INHERITED_ENV_VARS, getDefaultEnvironment, StdioClientTransport } from './client/stdio.js';
-export type { StartSSEOptions, StreamableHTTPClientTransportOptions, StreamableHTTPReconnectionOptions } from './client/streamableHttp.js';
+export type {
+    ReconnectionScheduler,
+    StartSSEOptions,
+    StreamableHTTPClientTransportOptions,
+    StreamableHTTPReconnectionOptions
+} from './client/streamableHttp.js';
 export { StreamableHTTPClientTransport } from './client/streamableHttp.js';
 export { WebSocketClientTransport } from './client/websocket.js';
 

packages/client/test/client/crossSpawn.test.ts

@@ -152,4 +152,54 @@ describe('StdioClientTransport using cross-spawn', () => {
         // verify message is sent correctly
         expect(mockProcess.stdin.write).toHaveBeenCalled();
     });
+
+    describe('windowsHide', () => {
+        const originalPlatform = process.platform;
+
+        afterEach(() => {
+            Object.defineProperty(process, 'platform', {
+                value: originalPlatform
+            });
+        });
+
+        test('should set windowsHide to true on Windows', async () => {
+            Object.defineProperty(process, 'platform', {
+                value: 'win32'
+            });
+
+            const transport = new StdioClientTransport({
+                command: 'test-command'
+            });
+
+            await transport.start();
+
+            expect(mockSpawn).toHaveBeenCalledWith(
+                'test-command',
+                [],
+                expect.objectContaining({
+                    windowsHide: true
+                })
+            );
+        });
+
+        test('should set windowsHide to false on non-Windows', async () => {
+            Object.defineProperty(process, 'platform', {
+                value: 'linux'
+            });
+
+            const transport = new StdioClientTransport({
+                command: 'test-command'
+            });
+
+            await transport.start();
+
+            expect(mockSpawn).toHaveBeenCalledWith(
+                'test-command',
+                [],
+                expect.objectContaining({
+                    windowsHide: false
+                })
+            );
+        });
+    });
 });