fix(client): reject stdio send() when the write fails instead of waiting for 'drain'

.changeset/stdio-client-send-drain-hang.md

@@ -0,0 +1,9 @@
+---
+'@modelcontextprotocol/client': patch
+---
+
+Fix `StdioClientTransport.send()` never settling when a backpressured write is still in flight and the pipe to the server dies. `send()` waited for a `'drain'` event, but a destroyed stream never drains, so the returned promise stayed pending and the `'drain'` listener was never removed. It now settles from the `write()` callback, which Node invokes on flush or on failure, so the send rejects with the underlying write error instead. This is what `StdioServerTransport.send()` already does for its own stdout.
+
+The visible symptom was `await client.notification(...)`, which never returned: the notification path awaits the transport send with no timeout, and the connection-closed teardown settles pending responses but not pending sends. Requests were already rescued by that teardown, so `callTool()` and friends now report the actual write error (`EPIPE`, `EOF`) rather than a generic connection-closed error.
+
+Reaching this needs a write the pipe will not accept in one go, which starts anywhere from tens to hundreds of KB depending on the platform pipe buffer and the Node version, sizes that base64 image payloads and file contents in tool arguments reach routinely.

packages/client/src/client/stdio.ts

@@ -313,16 +313,18 @@ export class StdioClientTransport implements Transport {
     }
 
     send(message: JSONRPCMessage): Promise<void> {
-        return new Promise(resolve => {
+        return new Promise((resolve, reject) => {
             if (!this._process?.stdin) {
                 throw new SdkError(SdkErrorCode.NotConnected, 'Not connected');
             }
 
             const json = serializeMessage(message);
-            if (this._process.stdin.write(json)) {
+            // The write callback runs once the chunk is flushed or the write fails,
+            // so a backpressured send still settles when the server exits and
+            // destroys the pipe. Waiting on 'drain' alone parks forever there,
+            // because a destroyed stream never drains.
+            if (this._process.stdin.write(json, error => (error ? reject(error) : resolve()))) {
                 resolve();
-            } else {
-                this._process.stdin.once('drain', resolve);
             }
         });
     }

packages/client/test/client/stdio.test.ts

@@ -150,3 +150,41 @@ test('_dispose releases the parent-side pipe handles even when a helper process
     expect(proc.stdout?.destroyed).toBe(true);
     expect(proc.stdin?.destroyed).toBe(true);
 }, 10_000);
+
+test('send() rejects instead of hanging when the server exits before a large write flushes', async () => {
+    // A server that never reads stdin and then exits: the write stays buffered,
+    // and the exit destroys the pipe, so the stream can never flush or drain.
+    const transport = new StdioClientTransport({
+        command: process.execPath,
+        args: ['-e', 'setTimeout(() => process.exit(0), 200)']
+    });
+    transport.onerror = () => {};
+    await transport.start();
+    const stdin = (transport as unknown as { _process: import('node:child_process').ChildProcess })._process.stdin!;
+
+    // 8 MB of params, far past stdin's 16 KB high water mark, so write() returns
+    // false and the send has to wait for the stream instead of resolving at once.
+    const pending = transport.send({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'tools/call',
+        params: { name: 'echo', arguments: { blob: 'x'.repeat(8 * 1024 * 1024) } }
+    });
+
+    // Bounded so the unfixed behaviour reports as 'hung' rather than as a suite
+    // timeout. The rejection reason is platform specific (EPIPE, EOF), so only
+    // the fact that it settles is asserted.
+    const outcome = await Promise.race([
+        pending.then(
+            () => 'resolved' as const,
+            () => 'rejected' as const
+        ),
+        new Promise<'hung'>(resolve => {
+            setTimeout(() => resolve('hung'), 3000).unref();
+        })
+    ]);
+
+    expect(outcome).toBe('rejected');
+    expect(stdin.listenerCount('drain')).toBe(0);
+    await transport.close();
+}, 15_000);