feat: add maxMessageBytes to stdio transports, make ReadBuffer amortized O(1)

.changeset/stdio-max-message-bytes.md

@@ -0,0 +1,10 @@
+---
+'@modelcontextprotocol/client': minor
+'@modelcontextprotocol/server': minor
+---
+
+Add `maxMessageBytes` option to the stdio transports and make the stdio read buffer amortized O(1) per byte
+
+A stdio peer that writes a very large amount of data without a newline (accidental binary output, runaway log line, or a malicious server) previously grew the receiving process's memory without bound, and each incoming chunk re-copied the entire buffered backlog (`Buffer.concat` per chunk). There was no public way to bound or replace the read buffer, so integrators who had built flood protection on v1 transport internals had nothing to migrate to.
+
+`StdioClientTransport` and `StdioServerTransport` now accept an optional `maxMessageBytes`. When a single message exceeds it, the data is dropped, an `SdkError` with the new code `SdkErrorCode.MessageTooLarge` is reported via `onerror`, and the transport recovers at the next newline boundary. The default remains unlimited. The read buffer also now grows geometrically with read/scan offsets instead of concatenating on every chunk.

docs/migration-SKILL.md

@@ -216,7 +216,7 @@ if (error instanceof OAuthError && error.code === OAuthErrorCode.InvalidClient)
 ```
 
 **Unchanged APIs** (only import paths changed): `Client` constructor and most methods, `McpServer` constructor, `server.connect()`, `server.close()`, all client transports (`StreamableHTTPClientTransport`, `SSEClientTransport`, `StdioClientTransport`), `StdioServerTransport`, all
-Zod schemas, all callback return types. Note: `callTool()` and `request()` signatures changed (schema parameter removed, see section 11).
+Zod schemas, all callback return types. Note: `callTool()` and `request()` signatures changed (schema parameter removed, see section 11). The stdio transports additionally accept a new optional `maxMessageBytes` option in v2 (see the stdio transport notes).
 
 ## 6. McpServer API Changes
 
@@ -507,6 +507,8 @@ NOT removed (wire surface, kept for 2025-11-25 interop): task Zod schemas + infe
 
 `Client.listPrompts()`, `listResources()`, `listResourceTemplates()`, `listTools()` now return empty results when the server lacks the corresponding capability (instead of sending the request). Set `enforceStrictCapabilities: true` in `ClientOptions` to throw an error instead.
 
+Stdio transports: non-JSON lines on the stream are now skipped silently (v1 surfaced a `SyntaxError` via `onerror`); valid-JSON messages failing schema validation still reach `onerror`. Both stdio transports accept an optional `maxMessageBytes` — oversized messages are dropped and reported via `onerror` as `SdkError` with code `SdkErrorCode.MessageTooLarge` (default: unlimited). Use it to replace any v1-era flood protection built on transport internals.
+
 ## 14. Runtime-Specific JSON Schema Validators (Enhancement)
 
 The SDK now auto-selects the appropriate JSON Schema validator based on runtime:

docs/migration.md

@@ -141,6 +141,27 @@
 const transport = new StreamableHTTPClientTransport(new URL('http://localhost:3000/mcp'));
 ```
 
+### Stdio transports: non-JSON lines are now skipped silently
+
+In v1, a non-JSON line on the stdio stream (for example, debug output from a hot-reload
+tool writing to stdout) surfaced as a `SyntaxError` through the transport's `onerror`
+callback. In v2, the stdio read buffer silently skips lines that are not valid JSON and
+continues with the next line; only valid-JSON messages that fail schema validation still
+reach `onerror`. If you relied on `onerror` to detect a misbehaving server that writes
+noise to stdout, that signal no longer fires for non-JSON lines.
+
+Relatedly, both stdio transports now accept an optional `maxMessageBytes` setting that
+bounds how large a single message may grow before it is dropped and reported via
+`onerror` (`SdkError` with code `SdkErrorCode.MessageTooLarge`). v1 had no built-in
+protection against a peer flooding the stream with unbounded data on a single line; if
+you implemented such protection against v1 transport internals, migrate to this option.
+
+```typescript
+import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';
+
+const transport = new StdioClientTransport({ command: 'my-server' }, { maxMessageBytes: 4 * 1024 * 1024 });
+```
+
 ### Server auth split
 
 Resource Server helpers (`requireBearerAuth`, `mcpAuthMetadataRouter`, `getOAuthProtectedResourceMetadataUrl`, `OAuthTokenVerifier`) are first-class in `@modelcontextprotocol/express`.
@@ -984,8 +1005,8 @@
 - `Client` constructor and most client methods (`connect`, `listTools`, `listPrompts`, `listResources`, `readResource`, etc.) — note: `callTool()` signature changed (schema parameter removed)
 - `McpServer` constructor, `server.connect(transport)`, `server.close()`
 - `Server` (low-level) constructor and all methods
-- `StreamableHTTPClientTransport`, `SSEClientTransport`, `StdioClientTransport` constructors and options
-- `StdioServerTransport` constructor and options
+- `StreamableHTTPClientTransport` and `SSEClientTransport` constructors and options
+- `StdioClientTransport` and `StdioServerTransport` constructors — note: both accept a new optional `maxMessageBytes` option in v2 (see the stdio transport notes above)
 - All Zod schemas and type definitions from `types.ts` (except the aliases listed above)
 - Tool, prompt, and resource callback return types
 

packages/client/src/client/stdio.ts

@@ -7,6 +7,22 @@ import type { JSONRPCMessage, Transport } from '@modelcontextprotocol/core';
 import { ReadBuffer, SdkError, SdkErrorCode, serializeMessage } from '@modelcontextprotocol/core';
 import spawn from 'cross-spawn';
 
+export type StdioClientTransportOptions = {
+    /**
+     * Maximum size, in bytes, that a single inbound message may occupy.
+     *
+     * Protects against a misbehaving server flooding the client with an unbounded
+     * amount of data on a single line (e.g. accidental binary or log output on
+     * stdout), which would otherwise grow client memory without limit. When a
+     * message exceeds this size it is dropped, an {@linkcode SdkError} with code
+     * `SdkErrorCode.MessageTooLarge` is reported via `onerror`, and the transport
+     * recovers at the next newline boundary.
+     *
+     * Defaults to undefined (no limit), matching previous behavior.
+     */
+    maxMessageBytes?: number;
+};
+
 export type StdioServerParameters = {
     /**
      * The executable to run to start the server.
@@ -92,16 +108,17 @@ export function getDefaultEnvironment(): Record<string, string> {
  */
 export class StdioClientTransport implements Transport {
     private _process?: ChildProcess;
-    private _readBuffer: ReadBuffer = new ReadBuffer();
+    private _readBuffer: ReadBuffer;
     private _serverParams: StdioServerParameters;
     private _stderrStream: PassThrough | null = null;
 
     onclose?: () => void;
     onerror?: (error: Error) => void;
     onmessage?: (message: JSONRPCMessage) => void;
 
-    constructor(server: StdioServerParameters) {
+    constructor(server: StdioServerParameters, options?: StdioClientTransportOptions) {
         this._serverParams = server;
+        this._readBuffer = new ReadBuffer({ maxMessageBytes: options?.maxMessageBytes });
         if (server.stderr === 'pipe' || server.stderr === 'overlapped') {
             this._stderrStream = new PassThrough();
         }

packages/client/src/stdio.ts

@@ -4,5 +4,5 @@
 // Cloudflare Workers targets does not pull in `node:child_process`, `node:stream`, or `cross-spawn`. Import
 // from `@modelcontextprotocol/client/stdio` only in process-spawning runtimes (Node.js, Bun, Deno).
 
-export type { StdioServerParameters } from './client/stdio.js';
+export type { StdioClientTransportOptions, StdioServerParameters } from './client/stdio.js';
 export { DEFAULT_INHERITED_ENV_VARS, getDefaultEnvironment, StdioClientTransport } from './client/stdio.js';

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

@@ -1,4 +1,5 @@
 import type { JSONRPCMessage } from '@modelcontextprotocol/core';
+import { SdkError, SdkErrorCode } from '@modelcontextprotocol/core';
 
 import type { StdioServerParameters } from '../../src/client/stdio.js';
 import { StdioClientTransport } from '../../src/client/stdio.js';
@@ -77,3 +78,84 @@ test('should return child process pid', async () => {
     await client.close();
     expect(client.pid).toBeNull();
 });
+
+test('should surface MessageTooLarge via onerror and keep running when maxMessageBytes is exceeded', async () => {
+    // `tee`/`more` echo stdin back on stdout, so an oversized outbound message
+    // becomes an oversized inbound message.
+    const client = new StdioClientTransport(serverParameters, { maxMessageBytes: 1024 });
+
+    const errors: Error[] = [];
+    const oversizedReported = new Promise<void>(resolve => {
+        client.onerror = error => {
+            errors.push(error);
+            resolve();
+        };
+    });
+
+    const messages: JSONRPCMessage[] = [];
+    const smallMessageEchoed = new Promise<void>(resolve => {
+        client.onmessage = message => {
+            messages.push(message);
+            resolve();
+        };
+    });
+
+    await client.start();
+
+    const oversized: JSONRPCMessage = {
+        jsonrpc: '2.0',
+        method: 'oversized',
+        params: { payload: 'x'.repeat(10_000) }
+    };
+    await client.send(oversized);
+    await oversizedReported;
+
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toBeInstanceOf(SdkError);
+    expect((errors[0] as SdkError).code).toBe(SdkErrorCode.MessageTooLarge);
+
+    // The transport recovers: a small message still round-trips.
+    const small: JSONRPCMessage = { jsonrpc: '2.0', method: 'small' };
+    await client.send(small);
+    await smallMessageEchoed;
+    expect(messages).toEqual([small]);
+
+    await client.close();
+});
+
+test('should recover when a child floods stdout without a newline', async () => {
+    // A misbehaving server that writes a large amount of data with no message
+    // boundary, then a valid message: the limit must trip while the flood is
+    // still incomplete, and the transport must recover at the newline.
+    const childScript = [
+        "process.stdout.write('x'.repeat(1_000_000));",
+        "process.stdout.write('\\n');",
+        "process.stdout.write(JSON.stringify({ jsonrpc: '2.0', method: 'after-flood' }) + '\\n');",
+        'setInterval(() => {}, 1 << 30);'
+    ].join(' ');
+
+    const client = new StdioClientTransport({ command: process.execPath, args: ['-e', childScript] }, { maxMessageBytes: 65_536 });
+
+    const errors: Error[] = [];
+    client.onerror = error => {
+        errors.push(error);
+    };
+
+    const messages: JSONRPCMessage[] = [];
+    const messageAfterFlood = new Promise<void>(resolve => {
+        client.onmessage = message => {
+            messages.push(message);
+            resolve();
+        };
+    });
+
+    await client.start();
+    await messageAfterFlood;
+
+    expect(messages).toEqual([{ jsonrpc: '2.0', method: 'after-flood' }]);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toBeInstanceOf(SdkError);
+    expect((errors[0] as SdkError).code).toBe(SdkErrorCode.MessageTooLarge);
+
+    await client.close();
+});

packages/core/src/errors/sdkErrors.ts

@@ -26,6 +26,8 @@ export enum SdkErrorCode {
     ConnectionClosed = 'CONNECTION_CLOSED',
     /** Failed to send message */
     SendFailed = 'SEND_FAILED',
+    /** A single inbound message exceeded the configured maximum size */
+    MessageTooLarge = 'MESSAGE_TOO_LARGE',
     /** Response result failed local schema validation */
     InvalidResult = 'INVALID_RESULT',
 

packages/core/src/exports/public/index.ts

@@ -54,6 +54,7 @@ export { DEFAULT_REQUEST_TIMEOUT_MSEC } from '../../shared/protocol.js';
 
 // stdio message framing utilities (for custom transport authors)
 export { deserializeMessage, ReadBuffer, serializeMessage } from '../../shared/stdio.js';
+export type { ReadBufferOptions } from '../../shared/stdio.js';
 
 // Transport types (NOT normalizeHeaders)
 export type { FetchLike, Transport, TransportSendOptions } from '../../shared/transport.js';