refactor(client,server): move stdio transports to ./stdio subpath export (#1871)

felixweinberger · KKonstantinov · web-flow · commit 9fc9070b7b8e · 2026-04-29T14:48:36.000+01:00
Co-authored-by: Konstantin Konstantinov &lt;KKonstantinov@users.noreply.github.com&gt;
diff --git a/.changeset/stdio-subpath-export.md b/.changeset/stdio-subpath-export.md
@@ -0,0 +1,6 @@
+---
+'@modelcontextprotocol/client': minor
+'@modelcontextprotocol/server': minor
+---
+
+Move stdio transports to a `./stdio` subpath export. Import `StdioClientTransport`, `getDefaultEnvironment`, `DEFAULT_INHERITED_ENV_VARS`, and `StdioServerParameters` from `@modelcontextprotocol/client/stdio`, and `StdioServerTransport` from `@modelcontextprotocol/server/stdio`. The `@modelcontextprotocol/client` root entry no longer pulls in `node:child_process`, `node:stream`, or `cross-spawn`, fixing bundling for browser and Cloudflare Workers targets; the `@modelcontextprotocol/server` root entry drops its `node:stream` reference. Node.js, Bun, and Deno consumers update the import path; runtime behavior is unchanged.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -74,6 +74,7 @@ When modifying exports:
 - Use explicit named exports, not `export *`, in package `index.ts` files and `core/public`.
 - Adding a symbol to a package `index.ts` makes it public API — do so intentionally.
 - Internal helpers should stay in the core internal barrel and not be added to `core/public` or package index files.
+- The package root entry must stay runtime-neutral so browser and Cloudflare Workers bundlers can consume it. Exports whose module graph transitively touches unpolyfillable Node builtins (`node:child_process`, `node:net`, `cross-spawn`, etc.) must live at a named subpath export (e.g. `./stdio`) and be covered by a `barrelClean` test in that package.
 
 ### Transport System
 
diff --git a/README.md b/README.md
@@ -95,7 +95,8 @@ npm install @modelcontextprotocol/hono hono
 Here is what an MCP server looks like. This minimal example exposes a single `greet` tool over stdio:
 
 ```typescript
-import { McpServer, StdioServerTransport } from '@modelcontextprotocol/server';
+import { McpServer } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import * as z from 'zod/v4';
 
 const server = new McpServer({ name: 'greeting-server', version: '1.0.0' });
diff --git a/docs/client-quickstart.md b/docs/client-quickstart.md
@@ -112,7 +112,8 @@ First, let's set up our imports and create the basic client class in `src/index.
 
 ```ts source="../examples/client-quickstart/src/index.ts#prelude"
 import Anthropic from '@anthropic-ai/sdk';
-import { Client, StdioClientTransport } from '@modelcontextprotocol/client';
+import { Client } from '@modelcontextprotocol/client';
+import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';
 import readline from 'readline/promises';
 
 const ANTHROPIC_MODEL = 'claude-sonnet-4-5';
diff --git a/docs/client.md b/docs/client.md
@@ -26,9 +26,9 @@ import {
     SdkError,
     SdkErrorCode,
     SSEClientTransport,
-    StdioClientTransport,
     StreamableHTTPClientTransport
 } from '@modelcontextprotocol/client';
+import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';
 ```
 
 ## Connecting to a server
diff --git a/docs/migration-SKILL.md b/docs/migration-SKILL.md
@@ -42,7 +42,7 @@ Replace all `@modelcontextprotocol/sdk/...` imports using this table.
 | `@modelcontextprotocol/sdk/client/auth.js`           | `@modelcontextprotocol/client` |
 | `@modelcontextprotocol/sdk/client/streamableHttp.js` | `@modelcontextprotocol/client` |
 | `@modelcontextprotocol/sdk/client/sse.js`            | `@modelcontextprotocol/client` |
-| `@modelcontextprotocol/sdk/client/stdio.js`          | `@modelcontextprotocol/client` |
+| `@modelcontextprotocol/sdk/client/stdio.js`          | `@modelcontextprotocol/client/stdio` |
 | `@modelcontextprotocol/sdk/client/websocket.js`      | REMOVED (use Streamable HTTP or stdio; implement `Transport` for custom needs) |
 
 ### Server imports
@@ -51,7 +51,7 @@ Replace all `@modelcontextprotocol/sdk/...` imports using this table.
 | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `@modelcontextprotocol/sdk/server/mcp.js`            | `@modelcontextprotocol/server`                                                                                                                                                                                     |
 | `@modelcontextprotocol/sdk/server/index.js`          | `@modelcontextprotocol/server`                                                                                                                                                                                     |
-| `@modelcontextprotocol/sdk/server/stdio.js`          | `@modelcontextprotocol/server`                                                                                                                                                                                     |
+| `@modelcontextprotocol/sdk/server/stdio.js`          | `@modelcontextprotocol/server/stdio`                                                                                                                                                                                     |
 | `@modelcontextprotocol/sdk/server/streamableHttp.js` | `@modelcontextprotocol/node` (class renamed to `NodeStreamableHTTPServerTransport`) OR `@modelcontextprotocol/server` (web-standard `WebStandardStreamableHTTPServerTransport` for Cloudflare Workers, Deno, etc.) |
 | `@modelcontextprotocol/sdk/server/sse.js`            | REMOVED (migrate to Streamable HTTP)                                                                                                                                                                               |
 | `@modelcontextprotocol/sdk/server/auth/*`            | RS helpers (`requireBearerAuth`, `mcpAuthMetadataRouter`, `OAuthTokenVerifier`) → `@modelcontextprotocol/express`; AS helpers removed (use external IdP/OAuth library)                                             |
@@ -66,7 +66,7 @@ Replace all `@modelcontextprotocol/sdk/...` imports using this table.
 | `@modelcontextprotocol/sdk/shared/transport.js`   | `@modelcontextprotocol/client` or `@modelcontextprotocol/server` |
 | `@modelcontextprotocol/sdk/shared/uriTemplate.js` | `@modelcontextprotocol/client` or `@modelcontextprotocol/server` |
 | `@modelcontextprotocol/sdk/shared/auth.js`        | `@modelcontextprotocol/client` or `@modelcontextprotocol/server` |
-| `@modelcontextprotocol/sdk/shared/stdio.js`       | `@modelcontextprotocol/client` or `@modelcontextprotocol/server` |
+| `@modelcontextprotocol/sdk/shared/stdio.js`       | `@modelcontextprotocol/client` or `@modelcontextprotocol/server` (`ReadBuffer`, `serializeMessage`, `deserializeMessage` are in the root barrel; the `./stdio` subpath only has the transport class) |
 
 Notes:
 
diff --git a/docs/migration.md b/docs/migration.md
@@ -50,8 +50,10 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 **After (v2):**
 
 ```typescript
-import { Client, StreamableHTTPClientTransport, StdioClientTransport } from '@modelcontextprotocol/client';
-import { McpServer, StdioServerTransport, WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/server';
+import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
+import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';
+import { McpServer, WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 
 // Node.js HTTP server transport is in the @modelcontextprotocol/node package
 import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
diff --git a/docs/server-quickstart.md b/docs/server-quickstart.md
@@ -127,7 +127,8 @@ Now let's dive into building your server.
 Add these to the top of your `src/index.ts`:
 
 ```ts source="../examples/server-quickstart/src/index.ts#prelude"
-import { McpServer, StdioServerTransport } from '@modelcontextprotocol/server';
+import { McpServer } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import * as z from 'zod/v4';
 
 const NWS_API_BASE = 'https://api.weather.gov';
diff --git a/docs/server.md b/docs/server.md
@@ -22,7 +22,8 @@ import { randomUUID } from 'node:crypto';
 import { createMcpExpressApp } from '@modelcontextprotocol/express';
 import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
 import type { CallToolResult, ResourceLink } from '@modelcontextprotocol/server';
-import { completable, McpServer, ResourceTemplate, StdioServerTransport } from '@modelcontextprotocol/server';
+import { completable, McpServer, ResourceTemplate } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import * as z from 'zod/v4';
 ```
 
diff --git a/examples/client-quickstart/src/index.ts b/examples/client-quickstart/src/index.ts
@@ -1,6 +1,7 @@
 //#region prelude
 import Anthropic from '@anthropic-ai/sdk';
-import { Client, StdioClientTransport } from '@modelcontextprotocol/client';
+import { Client } from '@modelcontextprotocol/client';
+import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';
 import readline from 'readline/promises';
 
 const ANTHROPIC_MODEL = 'claude-sonnet-4-5';
diff --git a/examples/client-quickstart/tsconfig.json b/examples/client-quickstart/tsconfig.json
@@ -12,6 +12,7 @@
         "forceConsistentCasingInFileNames": true,
         "paths": {
             "@modelcontextprotocol/client": ["./node_modules/@modelcontextprotocol/client/src/index.ts"],
+            "@modelcontextprotocol/client/stdio": ["./node_modules/@modelcontextprotocol/client/src/stdio.ts"],
             "@modelcontextprotocol/client/_shims": ["./node_modules/@modelcontextprotocol/client/src/shimsNode.ts"],
             "@modelcontextprotocol/core": [
                 "./node_modules/@modelcontextprotocol/client/node_modules/@modelcontextprotocol/core/src/index.ts"
diff --git a/examples/client/src/clientGuide.examples.ts b/examples/client/src/clientGuide.examples.ts
@@ -21,9 +21,9 @@ import {
     SdkError,
     SdkErrorCode,
     SSEClientTransport,
-    StdioClientTransport,
     StreamableHTTPClientTransport
 } from '@modelcontextprotocol/client';
+import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';
 //#endregion imports
 
 // ---------------------------------------------------------------------------
diff --git a/examples/client/tsconfig.json b/examples/client/tsconfig.json
@@ -6,6 +6,7 @@
         "paths": {
             "*": ["./*"],
             "@modelcontextprotocol/client": ["./node_modules/@modelcontextprotocol/client/src/index.ts"],
+            "@modelcontextprotocol/client/stdio": ["./node_modules/@modelcontextprotocol/client/src/stdio.ts"],
             "@modelcontextprotocol/client/_shims": ["./node_modules/@modelcontextprotocol/client/src/shimsNode.ts"],
             "@modelcontextprotocol/core": [
                 "./node_modules/@modelcontextprotocol/client/node_modules/@modelcontextprotocol/core/src/index.ts"
diff --git a/examples/server-quickstart/src/index.ts b/examples/server-quickstart/src/index.ts
@@ -1,5 +1,6 @@
 //#region prelude
-import { McpServer, StdioServerTransport } from '@modelcontextprotocol/server';
+import { McpServer } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import * as z from 'zod/v4';
 
 const NWS_API_BASE = 'https://api.weather.gov';
diff --git a/examples/server-quickstart/tsconfig.json b/examples/server-quickstart/tsconfig.json
@@ -11,6 +11,7 @@
         "forceConsistentCasingInFileNames": true,
         "paths": {
             "@modelcontextprotocol/server": ["./node_modules/@modelcontextprotocol/server/src/index.ts"],
+            "@modelcontextprotocol/server/stdio": ["./node_modules/@modelcontextprotocol/server/src/stdio.ts"],
             "@modelcontextprotocol/server/_shims": ["./node_modules/@modelcontextprotocol/server/src/shimsNode.ts"],
             "@modelcontextprotocol/core": [
                 "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core/src/index.ts"
diff --git a/examples/server/src/arktypeExample.ts b/examples/server/src/arktypeExample.ts
@@ -4,7 +4,8 @@
  * ArkType implements the Standard Schema spec with built-in JSON Schema conversion.
  */
 
-import { McpServer, StdioServerTransport } from '@modelcontextprotocol/server';
+import { McpServer } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import { type } from 'arktype';
 
 const server = new McpServer({
diff --git a/examples/server/src/mcpServerOutputSchema.ts b/examples/server/src/mcpServerOutputSchema.ts
@@ -4,7 +4,8 @@
  * This demonstrates how to easily create tools with structured output
  */
 
-import { McpServer, StdioServerTransport } from '@modelcontextprotocol/server';
+import { McpServer } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import * as z from 'zod/v4';
 
 const server = new McpServer({
diff --git a/examples/server/src/serverGuide.examples.ts b/examples/server/src/serverGuide.examples.ts
@@ -13,7 +13,8 @@ import { randomUUID } from 'node:crypto';
 import { createMcpExpressApp } from '@modelcontextprotocol/express';
 import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
 import type { CallToolResult, ResourceLink } from '@modelcontextprotocol/server';
-import { completable, McpServer, ResourceTemplate, StdioServerTransport } from '@modelcontextprotocol/server';
+import { completable, McpServer, ResourceTemplate } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import * as z from 'zod/v4';
 //#endregion imports
 
diff --git a/examples/server/src/toolWithSampleServer.ts b/examples/server/src/toolWithSampleServer.ts
@@ -1,6 +1,7 @@
 // Run with: pnpm tsx src/toolWithSampleServer.ts
 
-import { McpServer, StdioServerTransport } from '@modelcontextprotocol/server';
+import { McpServer } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import * as z from 'zod/v4';
 
 const mcpServer = new McpServer({
diff --git a/examples/server/src/valibotExample.ts b/examples/server/src/valibotExample.ts
@@ -5,7 +5,8 @@
  * StandardJSONSchemaV1-compliant schemas.
  */
 
-import { McpServer, StdioServerTransport } from '@modelcontextprotocol/server';
+import { McpServer } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import { toStandardJsonSchema } from '@valibot/to-json-schema';
 import * as v from 'valibot';
 
diff --git a/examples/server/tsconfig.json b/examples/server/tsconfig.json
@@ -6,6 +6,7 @@
         "paths": {
             "*": ["./*"],
             "@modelcontextprotocol/server": ["./node_modules/@modelcontextprotocol/server/src/index.ts"],
+            "@modelcontextprotocol/server/stdio": ["./node_modules/@modelcontextprotocol/server/src/stdio.ts"],
             "@modelcontextprotocol/server/_shims": ["./node_modules/@modelcontextprotocol/server/src/shimsNode.ts"],
             "@modelcontextprotocol/express": ["./node_modules/@modelcontextprotocol/express/src/index.ts"],
             "@modelcontextprotocol/node": ["./node_modules/@modelcontextprotocol/node/src/index.ts"],
diff --git a/packages/client/package.json b/packages/client/package.json
@@ -24,6 +24,10 @@
             "types": "./dist/index.d.mts",
             "import": "./dist/index.mjs"
         },
+        "./stdio": {
+            "types": "./dist/stdio.d.mts",
+            "import": "./dist/stdio.mjs"
+        },
         "./validators/cf-worker": {
             "types": "./dist/validators/cfWorker.d.mts",
             "import": "./dist/validators/cfWorker.mjs"
diff --git a/packages/client/src/index.ts b/packages/client/src/index.ts
@@ -61,8 +61,8 @@ export type { LoggingOptions, Middleware, RequestLogger } from './client/middlew
 export { applyMiddlewares, createMiddleware, withLogging, withOAuth } from './client/middleware.js';
 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';
+// StdioClientTransport, getDefaultEnvironment, DEFAULT_INHERITED_ENV_VARS, StdioServerParameters are exported from
+// the './stdio' subpath to keep the root entry free of process-spawning runtime dependencies (child_process, cross-spawn).
 export type {
     ReconnectionScheduler,
     StartSSEOptions,
diff --git a/packages/client/src/stdio.ts b/packages/client/src/stdio.ts
@@ -0,0 +1,8 @@
+// Subpath entry for the stdio client transport.
+//
+// Exported separately from the root entry so that bundling `@modelcontextprotocol/client` for browser or
+// 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 { DEFAULT_INHERITED_ENV_VARS, getDefaultEnvironment, StdioClientTransport } from './client/stdio.js';
diff --git a/packages/client/test/client/barrelClean.test.ts b/packages/client/test/client/barrelClean.test.ts
@@ -0,0 +1,55 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { beforeAll, describe, expect, test } from 'vitest';
+
+const pkgDir = join(dirname(fileURLToPath(import.meta.url)), '../..');
+const distDir = join(pkgDir, 'dist');
+const NODE_ONLY = /\b(child_process|cross-spawn|node:stream|node:child_process)\b/;
+
+function chunkImportsOf(entryPath: string): string[] {
+    const visited = new Set<string>();
+    const queue = [entryPath];
+    while (queue.length > 0) {
+        const file = queue.shift()!;
+        if (visited.has(file)) continue;
+        visited.add(file);
+        const src = readFileSync(file, 'utf8');
+        for (const m of src.matchAll(/from\s+["']\.\/(.+?\.mjs)["']/g)) {
+            queue.push(join(dirname(file), m[1]!));
+        }
+    }
+    visited.delete(entryPath);
+    return [...visited];
+}
+
+describe('@modelcontextprotocol/client root entry is browser-safe', () => {
+    beforeAll(() => {
+        if (!existsSync(join(distDir, 'index.mjs')) || !existsSync(join(distDir, 'stdio.mjs'))) {
+            execFileSync('pnpm', ['build'], { cwd: pkgDir, stdio: 'inherit' });
+        }
+    }, 60_000);
+
+    test('dist/index.mjs contains no process-spawning runtime imports', () => {
+        const entry = join(distDir, 'index.mjs');
+        expect(readFileSync(entry, 'utf8')).not.toMatch(NODE_ONLY);
+    });
+
+    test('chunks transitively imported by dist/index.mjs contain no process-spawning runtime imports', () => {
+        const entry = join(distDir, 'index.mjs');
+        for (const chunk of chunkImportsOf(entry)) {
+            expect({ chunk, content: readFileSync(chunk, 'utf8') }).not.toEqual(
+                expect.objectContaining({ content: expect.stringMatching(NODE_ONLY) })
+            );
+        }
+    });
+
+    test('dist/stdio.mjs exists and exports StdioClientTransport', () => {
+        const stdio = readFileSync(join(distDir, 'stdio.mjs'), 'utf8');
+        expect(stdio).toMatch(/\bStdioClientTransport\b/);
+        expect(stdio).toMatch(/\bgetDefaultEnvironment\b/);
+        expect(stdio).toMatch(/\bDEFAULT_INHERITED_ENV_VARS\b/);
+    });
+});
diff --git a/packages/client/tsdown.config.ts b/packages/client/tsdown.config.ts
@@ -4,7 +4,7 @@ export default defineConfig({
     failOnWarn: 'ci-only',
     // 1. Entry Points
     //    Directly matches package.json include/exclude globs
-    entry: ['src/index.ts', 'src/shimsNode.ts', 'src/shimsWorkerd.ts', 'src/shimsBrowser.ts', 'src/validators/cfWorker.ts'],
+    entry: ['src/index.ts', 'src/stdio.ts', 'src/shimsNode.ts', 'src/shimsWorkerd.ts', 'src/shimsBrowser.ts', 'src/validators/cfWorker.ts'],
 
     // 2. Output Configuration
     format: ['esm'],
diff --git a/packages/server/package.json b/packages/server/package.json
@@ -24,6 +24,10 @@
             "types": "./dist/index.d.mts",
             "import": "./dist/index.mjs"
         },
+        "./stdio": {
+            "types": "./dist/stdio.d.mts",
+            "import": "./dist/stdio.mjs"
+        },
         "./validators/cf-worker": {
             "types": "./dist/validators/cfWorker.d.mts",
             "import": "./dist/validators/cfWorker.mjs"
@@ -88,7 +92,6 @@
         "@modelcontextprotocol/test-helpers": "workspace:^",
         "@modelcontextprotocol/tsconfig": "workspace:^",
         "@modelcontextprotocol/vitest-config": "workspace:^",
-        "@types/cross-spawn": "catalog:devTools",
         "@types/eventsource": "catalog:devTools",
         "@typescript/native-preview": "catalog:devTools",
         "eslint": "catalog:devTools",
diff --git a/packages/server/src/index.ts b/packages/server/src/index.ts
@@ -28,7 +28,9 @@ export type { HostHeaderValidationResult } from './server/middleware/hostHeaderV
 export { hostHeaderValidationResponse, localhostAllowedHostnames, validateHostHeader } from './server/middleware/hostHeaderValidation.js';
 export type { ServerOptions } from './server/server.js';
 export { Server } from './server/server.js';
-export { StdioServerTransport } from './server/stdio.js';
+// StdioServerTransport is exported from the './stdio' subpath — server stdio has only type-level Node
+// imports (erased at compile time), but matching the client's `./stdio` subpath gives consumers a
+// consistent shape across packages.
 export type {
     EventId,
     EventStore,
diff --git a/packages/server/src/stdio.ts b/packages/server/src/stdio.ts
diff --git a/packages/server/test/server/barrelClean.test.ts b/packages/server/test/server/barrelClean.test.ts
diff --git a/packages/server/tsdown.config.ts b/packages/server/tsdown.config.ts
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/test/integration/test/__fixtures__/serverThatHangs.ts b/test/integration/test/__fixtures__/serverThatHangs.ts
diff --git a/test/integration/test/__fixtures__/testServer.ts b/test/integration/test/__fixtures__/testServer.ts
diff --git a/test/integration/test/processCleanup.test.ts b/test/integration/test/processCleanup.test.ts
diff --git a/test/integration/tsconfig.json b/test/integration/tsconfig.json
