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

[felixweinberger]

Move stdio transports to a ./stdio subpath export so the package root no longer pulls in node:child_process, node:stream, or cross-spawn. Fixes bundling for browser and Cloudflare Workers consumers. Node.js, Bun, and Deno consumers update one import path.

// before
import { Client, StdioClientTransport } from '@modelcontextprotocol/client';
import { McpServer, StdioServerTransport } from '@modelcontextprotocol/server';

// after
import { Client } from '@modelcontextprotocol/client';
import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';
import { McpServer } from '@modelcontextprotocol/server';
import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';

Motivation and Context

The v2 root barrel exports StdioClientTransport, which top-level imports cross-spawn and node:child_process. Any bundler targeting browsers fails. v1 avoided this with deep subpath imports; this restores that boundary as a single ./stdio subpath.

How Has This Been Tested?

barrelClean.test.ts in both packages asserts the built dist/index.mjs (and its transitive chunks) contain zero process-spawning runtime imports, and that dist/stdio.mjs exports the moved symbols.

Breaking Changes

Yes — stdio symbols are no longer exported from the package root. Import from @modelcontextprotocol/{client,server}/stdio.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

Also moves getDefaultEnvironment, DEFAULT_INHERITED_ENV_VARS, and the StdioServerParameters type to the client ./stdio subpath.

[changeset-bot]

🦋 Changeset detected

Latest commit: c2b85db

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 6 packages

Name	Type
@modelcontextprotocol/client	Minor
@modelcontextprotocol/server	Minor
@modelcontextprotocol/express	Major
@modelcontextprotocol/fastify	Major
@modelcontextprotocol/hono	Major
@modelcontextprotocol/node	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/@modelcontextprotocol/client@1871

@modelcontextprotocol/server

npm i https://pkg.pr.new/@modelcontextprotocol/server@1871

@modelcontextprotocol/express

npm i https://pkg.pr.new/@modelcontextprotocol/express@1871

@modelcontextprotocol/fastify

npm i https://pkg.pr.new/@modelcontextprotocol/fastify@1871

@modelcontextprotocol/hono

npm i https://pkg.pr.new/@modelcontextprotocol/hono@1871

@modelcontextprotocol/node

npm i https://pkg.pr.new/@modelcontextprotocol/node@1871

commit: c2b85db

[felixweinberger]

@claude review

[claude]

LGTM — clean implementation following the existing _shims conditional-export pattern.

Extended reasoning...

Overview

The PR adds browser and workerd export conditions to the client and server package roots that swap the real stdio transports for throwing stubs. This prevents browser/CF Workers bundlers from pulling in node:child_process, node:stream, and cross-spawn. Changes span 14 files: two new index.browser.ts barrel files, two new stdioStub.ts files, updated package.json exports, build config updates, tests, a changeset, and a new SdkErrorCode.TransportNotSupported enum value in core.

Security Risks

None. The stubs throw a helpful error on use rather than silently failing. No auth, crypto, or permissions code is touched.

Level of Scrutiny

Moderate — package.json exports conditions are critical for correct module resolution across runtimes, but the change is additive (new conditions prepended before the existing default) and non-breaking. A diff of the browser vs. node barrel files shows the only difference is the stdio import source, confirming the mirrors are accurate.

Other Factors

The only reported bug is a cosmetic duplicate comment label in sdkErrors.ts, which has no functional impact. @modelcontextprotocol/core is a private (unpublished) workspace package, so the absence of a core entry in the changeset is correct. Tests verify the browser bundle excludes Node-only imports while still exporting the stub class. The approach follows the existing _shims conditional-export pattern already in the repo.

[felixweinberger]

@claude review

[felixweinberger]

@claude review

[felixweinberger]

@claude review

[claude]

🔴 The shared/stdio.js row should keep pointing at the package root, not the new /stdio subpath. v1's shared/stdio.js exported ReadBuffer, serializeMessage, and deserializeMessage, which in v2 are still re-exported from the root of @modelcontextprotocol/client and @modelcontextprotocol/server (via core/public); the new ./stdio subpaths export only the transport classes. Following this row as written produces import { ReadBuffer } from '@modelcontextprotocol/client/stdio', which fails to resolve.

Extended reasoning...

What the bug is

This PR updates three rows in the docs/migration-SKILL.md import-mapping table to point at the new ./stdio subpath. Two of those updates (sdk/client/stdio.js → @modelcontextprotocol/client/stdio and sdk/server/stdio.js → @modelcontextprotocol/server/stdio) are correct. The third — @modelcontextprotocol/sdk/shared/stdio.js → @modelcontextprotocol/client/stdio or @modelcontextprotocol/server/stdio — is wrong and is a regression introduced by this PR.

Why it's wrong

In v1, @modelcontextprotocol/sdk/shared/stdio.js exported the message-framing utilities, not transports. The current source at packages/core/src/shared/stdio.ts confirms the export set: ReadBuffer (line 7), deserializeMessage (line 44), and serializeMessage (line 48).

In v2, those three symbols are re-exported from packages/core/src/exports/public/index.ts:68:

export { deserializeMessage, ReadBuffer, serializeMessage } from '../../shared/stdio.js';

Both packages/client/src/index.ts and packages/server/src/index.ts end with export * from '@modelcontextprotocol/core/public';, so these symbols are available from the root of @modelcontextprotocol/client and @modelcontextprotocol/server — exactly what the pre-PR table row said.

The new ./stdio subpaths created in this PR do not re-export these utilities. packages/client/src/stdio.ts exports only StdioServerParameters, DEFAULT_INHERITED_ENV_VARS, getDefaultEnvironment, and StdioClientTransport. packages/server/src/stdio.ts exports only StdioServerTransport. Neither exports ReadBuffer, serializeMessage, or deserializeMessage.

Why nothing catches this

migration-SKILL.md is an LLM-consumed mapping table, not type-checked code. The barrelClean tests added in this PR verify the bundle contents but say nothing about which v2 module each v1 path's symbols actually live in, so the doc regression slips through.

Impact

This file is explicitly designed to be loaded as a skill so an LLM can mechanically rewrite imports during a v1→v2 migration. A user with v1 code like import { ReadBuffer, serializeMessage } from '@modelcontextprotocol/sdk/shared/stdio.js'; (custom transport authors are the typical consumers) will have it rewritten to import { ReadBuffer, serializeMessage } from '@modelcontextprotocol/client/stdio';, which fails with "Module has no exported member 'ReadBuffer'". The pre-PR mapping (root package) worked; this PR breaks it.

Step-by-step proof

1. v1 source: import { ReadBuffer } from '@modelcontextprotocol/sdk/shared/stdio.js';
2. Migration skill consults the table at docs/migration-SKILL.md:69 and rewrites to import { ReadBuffer } from '@modelcontextprotocol/client/stdio';
3. @modelcontextprotocol/client/stdio resolves (per packages/client/package.json exports) to dist/stdio.mjs, built from packages/client/src/stdio.ts
4. That entry exports only StdioClientTransport, getDefaultEnvironment, DEFAULT_INHERITED_ENV_VARS, and the StdioServerParameters type — no ReadBuffer
5. tsc / bundler fails: Module '"@modelcontextprotocol/client/stdio"' has no exported member 'ReadBuffer'
6. The correct rewrite (and the pre-PR table value) is import { ReadBuffer } from '@modelcontextprotocol/client';, which resolves via core/public/index.ts:68

How to fix

Revert just this one row to its pre-PR value:

| `@modelcontextprotocol/sdk/shared/stdio.js`       | `@modelcontextprotocol/client` or `@modelcontextprotocol/server` |

(Alternatively, also re-export ReadBuffer/serializeMessage/deserializeMessage from both ./stdio subpaths — but since these are pure framing utilities with no Node-only deps, keeping them at the root is consistent with the rest of the "shared" rows and avoids forcing a Node-only subpath import where none is needed.)