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: 46fe6d2

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: 46fe6d2

[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.

[claude]

🟡 The file now has two sections both labeled // Transport errors (lines 22 and 32 in sdkErrors.ts); the second section covering ClientHttp* codes should be labeled // HTTP client transport errors to distinguish the categories. This is a pre-existing naming issue, but the PR touches this file and had a natural opportunity to fix it.

Extended reasoning...

What the bug is

packages/core/src/errors/sdkErrors.ts now contains two distinct enum sections both labeled with the comment // Transport errors. The first section (line 22) groups general transport-level errors: TransportNotSupported, RequestTimeout, ConnectionClosed, and SendFailed. The second section (line 32) groups HTTP-client-specific error codes: ClientHttpNotImplemented, ClientHttpAuthentication, ClientHttpForbidden, ClientHttpUnexpectedContent, ClientHttpFailedToOpenStream, and ClientHttpFailedToTerminateSession.

The specific code path

The PR inserts TransportNotSupported correctly into the first // Transport errors section. However, the second // Transport errors comment (before the ClientHttp* codes) was already present in the file before this PR and was not renamed. The result is that a developer reading the enum sees two identically-named sections without a clear indication that one covers general transport failures and the other covers HTTP-specific client transport errors.

Why existing code does not prevent it

This is purely a naming/organizational issue in source code. There is no linter or test that enforces unique comment labels within an enum. The duplicate label slipped in as a pre-existing issue and the PR, while it touched this file, did not address it.

Impact

No functional impact. The enum values themselves are unique strings (TRANSPORT_NOT_SUPPORTED, CLIENT_HTTP_NOT_IMPLEMENTED, etc.) so there is no runtime confusion. The issue is purely a readability concern: developers scanning the enum may be confused about which section ClientHttp* codes belong to, or may mistakenly assume the two sections are redundant groupings of the same category.

How to fix

Rename the second comment from // Transport errors to // HTTP client transport errors:

// Transport errors
TransportNotSupported = "TRANSPORT_NOT_SUPPORTED",
RequestTimeout = "REQUEST_TIMEOUT",
ConnectionClosed = "CONNECTION_CLOSED",
SendFailed = "SEND_FAILED",

// HTTP client transport errors
ClientHttpNotImplemented = "CLIENT_HTTP_NOT_IMPLEMENTED",
// ...

Addressing the refutation

One verifier noted this is pre-existing and style issues should only be flagged in egregious cases. While true that the duplicate pre-dates this PR, the PR directly modifies sdkErrors.ts and adds a new entry to the first // Transport errors section, making the distinction between the two sections more relevant than before (one now explicitly contains a runtime-availability error, the other HTTP-protocol errors). The fix is a one-line comment change and the naming confusion is more pronounced after this PR.

[felixweinberger]

Stale. The PR was reworked to a ./stdio subpath export and no longer touches sdkErrors.ts (not in the current diff).