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.

// beforeimport{Client,StdioClientTransport}from'@modelcontextprotocol/client';import{McpServer,StdioServerTransport}from'@modelcontextprotocol/server';// afterimport{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: 9b2b5d3

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: 9b2b5d3

[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

[KKonstantinov]

Few comments, none of them blocking:

• @types/cross-spawn in packages/server/package.json - could be cleaned-up, not used
• packages/server/src/server/mcp.examples.ts - still imports from /stdio.js, but this file is synced via pnpm sync:snippets. Users who copy the example will get ./stdio.js, which is a path that only resolves inside the monorepo source tree, not from the published package
• CLAUDE.md - probably would be good to add an explicit rule to the "Public API Exports" section as the PR establishes a clean invariant. E.g. something like

Exports whose module graph transitively touches unpolyfillable Node builtins (node:child_process, node:net, node:stream's runtime APIs, cross-spawn, etc.) must live at a named subpath export (e.g. ./stdio) and be covered by a barrelClean test in that package. The package root must stay runtime-neutral so browser and Cloudflare Workers bundlers can consume it.

• Five tsconfigs now mirror thw ./stdio subpath by hand - it adds a drift risk, we could do some small follow-up lint/script that reads packages/{client,server}/package.jsonexports, derives the expected paths entries, and fails if any of the many tsconfigs are missing ones. Not needed for this PR, just an idea as the list grows longer

[felixweinberger]

@KKonstantinov thanks. Addressed in 9b2b5d3: dropped @types/cross-spawn from server, added the runtime-neutral root rule to CLAUDE.md, and fixed the README quickstart import while I was at it. Left mcp.examples.ts alone since sync:snippets only copies the #region body into JSDoc (the import line isn't synced) and all sibling .examples.ts files use the same relative pattern. Agree the tsconfig drift check would be a nice follow-up.

[claude]

Thanks — 9b2b5d3 picks up the README quickstart import, and a repo-wide grep now finds zero remaining root-barrel Stdio*Transport imports. Everything I flagged is addressed; deferring to a maintainer for final sign-off on the breaking export-map change.

Extended reasoning...

Overview

This PR moves StdioClientTransport (plus getDefaultEnvironment, DEFAULT_INHERITED_ENV_VARS, StdioServerParameters) and StdioServerTransport from the package root barrels to new ./stdio subpath exports in @modelcontextprotocol/client and @modelcontextprotocol/server. It adds the subpath to both package.jsonexports maps and typesVersions, adds src/stdio.ts entry points to both tsdown configs, drops the unused @types/cross-spawn devDep from the server package, adds barrelClean.test.ts regression guards in both packages, and migrates every doc/example/integration-test callsite (36 files total). A CLAUDE.md rule codifies the runtime-neutral-root-entry constraint.

Since my last review (2026-04-27)

Commit 9b2b5d3 adds README.md to the diff with the split import, which was the last open item I'd raised. A fresh grep for Stdio(Server|Client)Transport.*from\s+['"]@modelcontextprotocol/(client|server)['"] across the repo now returns zero matches, and the moved helper symbols (getDefaultEnvironment, DEFAULT_INHERITED_ENV_VARS, StdioServerParameters) have no remaining root-barrel references outside the new subpath/tests. The changeset prose, server index.ts/stdio.ts comments, migration-SKILL.mdshared/stdio.js row, and server barrelClean symbol-absence assertion from earlier rounds are all in their corrected form.

Security risks

None. This is an export-map/packaging refactor; no auth, crypto, network, or input-handling code paths change. Runtime behavior of the transports themselves is untouched.

Level of scrutiny

Moderate-to-high. The implementation is mechanical, but it is an intentional breaking change to the public API surface of two published packages (removing four root exports and introducing a new subpath), wired through package.jsonexports, typesVersions, and the tsdown entry list. That falls under the repo's "every new export is intentional" / "removing from public API" bar and the v2-bc label, so a maintainer should give the final ack on the API shape rather than a bot.

Other factors

• KKonstantinov reviewed an earlier revision and his NODE_ONLY-regex alignment request was applied (both barrelClean tests now share the same pattern plus the server symbol-absence check).
• barrelClean tests give a build-output regression guard; integration tests and all type-checked *.examples.ts exercise the new import path.
• Migration docs (migration.md, migration-SKILL.md) and the changeset cover the break per repo checklist.

[KKonstantinov]

LGTM!

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

// beforeimport{Client,StdioClientTransport}from'@modelcontextprotocol/client';import{McpServer,StdioServerTransport}from'@modelcontextprotocol/server';// afterimport{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: 9b2b5d3

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: 9b2b5d3

[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

[KKonstantinov]

Few comments, none of them blocking:

• @types/cross-spawn in packages/server/package.json - could be cleaned-up, not used
• packages/server/src/server/mcp.examples.ts - still imports from /stdio.js, but this file is synced via pnpm sync:snippets. Users who copy the example will get ./stdio.js, which is a path that only resolves inside the monorepo source tree, not from the published package
• CLAUDE.md - probably would be good to add an explicit rule to the "Public API Exports" section as the PR establishes a clean invariant. E.g. something like

Exports whose module graph transitively touches unpolyfillable Node builtins (node:child_process, node:net, node:stream's runtime APIs, cross-spawn, etc.) must live at a named subpath export (e.g. ./stdio) and be covered by a barrelClean test in that package. The package root must stay runtime-neutral so browser and Cloudflare Workers bundlers can consume it.

• Five tsconfigs now mirror thw ./stdio subpath by hand - it adds a drift risk, we could do some small follow-up lint/script that reads packages/{client,server}/package.jsonexports, derives the expected paths entries, and fails if any of the many tsconfigs are missing ones. Not needed for this PR, just an idea as the list grows longer

[felixweinberger]

@KKonstantinov thanks. Addressed in 9b2b5d3: dropped @types/cross-spawn from server, added the runtime-neutral root rule to CLAUDE.md, and fixed the README quickstart import while I was at it. Left mcp.examples.ts alone since sync:snippets only copies the #region body into JSDoc (the import line isn't synced) and all sibling .examples.ts files use the same relative pattern. Agree the tsconfig drift check would be a nice follow-up.

[claude]

Thanks — 9b2b5d3 picks up the README quickstart import, and a repo-wide grep now finds zero remaining root-barrel Stdio*Transport imports. Everything I flagged is addressed; deferring to a maintainer for final sign-off on the breaking export-map change.

Extended reasoning...

Overview

This PR moves StdioClientTransport (plus getDefaultEnvironment, DEFAULT_INHERITED_ENV_VARS, StdioServerParameters) and StdioServerTransport from the package root barrels to new ./stdio subpath exports in @modelcontextprotocol/client and @modelcontextprotocol/server. It adds the subpath to both package.jsonexports maps and typesVersions, adds src/stdio.ts entry points to both tsdown configs, drops the unused @types/cross-spawn devDep from the server package, adds barrelClean.test.ts regression guards in both packages, and migrates every doc/example/integration-test callsite (36 files total). A CLAUDE.md rule codifies the runtime-neutral-root-entry constraint.

Since my last review (2026-04-27)

Commit 9b2b5d3 adds README.md to the diff with the split import, which was the last open item I'd raised. A fresh grep for Stdio(Server|Client)Transport.*from\s+['"]@modelcontextprotocol/(client|server)['"] across the repo now returns zero matches, and the moved helper symbols (getDefaultEnvironment, DEFAULT_INHERITED_ENV_VARS, StdioServerParameters) have no remaining root-barrel references outside the new subpath/tests. The changeset prose, server index.ts/stdio.ts comments, migration-SKILL.mdshared/stdio.js row, and server barrelClean symbol-absence assertion from earlier rounds are all in their corrected form.

Security risks

None. This is an export-map/packaging refactor; no auth, crypto, network, or input-handling code paths change. Runtime behavior of the transports themselves is untouched.

Level of scrutiny

Moderate-to-high. The implementation is mechanical, but it is an intentional breaking change to the public API surface of two published packages (removing four root exports and introducing a new subpath), wired through package.jsonexports, typesVersions, and the tsdown entry list. That falls under the repo's "every new export is intentional" / "removing from public API" bar and the v2-bc label, so a maintainer should give the final ack on the API shape rather than a bot.

Other factors

• KKonstantinov reviewed an earlier revision and his NODE_ONLY-regex alignment request was applied (both barrelClean tests now share the same pattern plus the server symbol-absence check).
• barrelClean tests give a build-output regression guard; integration tests and all type-checked *.examples.ts exercise the new import path.
• Migration docs (migration.md, migration-SKILL.md) and the changeset cover the break per repo checklist.

[KKonstantinov]

LGTM!

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

// beforeimport{Client,StdioClientTransport}from'@modelcontextprotocol/client';import{McpServer,StdioServerTransport}from'@modelcontextprotocol/server';// afterimport{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: 9b2b5d3

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: 9b2b5d3

[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

[KKonstantinov]

Few comments, none of them blocking:

• @types/cross-spawn in packages/server/package.json - could be cleaned-up, not used
• packages/server/src/server/mcp.examples.ts - still imports from /stdio.js, but this file is synced via pnpm sync:snippets. Users who copy the example will get ./stdio.js, which is a path that only resolves inside the monorepo source tree, not from the published package
• CLAUDE.md - probably would be good to add an explicit rule to the "Public API Exports" section as the PR establishes a clean invariant. E.g. something like

Exports whose module graph transitively touches unpolyfillable Node builtins (node:child_process, node:net, node:stream's runtime APIs, cross-spawn, etc.) must live at a named subpath export (e.g. ./stdio) and be covered by a barrelClean test in that package. The package root must stay runtime-neutral so browser and Cloudflare Workers bundlers can consume it.

• Five tsconfigs now mirror thw ./stdio subpath by hand - it adds a drift risk, we could do some small follow-up lint/script that reads packages/{client,server}/package.jsonexports, derives the expected paths entries, and fails if any of the many tsconfigs are missing ones. Not needed for this PR, just an idea as the list grows longer

[felixweinberger]

@KKonstantinov thanks. Addressed in 9b2b5d3: dropped @types/cross-spawn from server, added the runtime-neutral root rule to CLAUDE.md, and fixed the README quickstart import while I was at it. Left mcp.examples.ts alone since sync:snippets only copies the #region body into JSDoc (the import line isn't synced) and all sibling .examples.ts files use the same relative pattern. Agree the tsconfig drift check would be a nice follow-up.

[claude]

Thanks — 9b2b5d3 picks up the README quickstart import, and a repo-wide grep now finds zero remaining root-barrel Stdio*Transport imports. Everything I flagged is addressed; deferring to a maintainer for final sign-off on the breaking export-map change.

Extended reasoning...

Overview

This PR moves StdioClientTransport (plus getDefaultEnvironment, DEFAULT_INHERITED_ENV_VARS, StdioServerParameters) and StdioServerTransport from the package root barrels to new ./stdio subpath exports in @modelcontextprotocol/client and @modelcontextprotocol/server. It adds the subpath to both package.jsonexports maps and typesVersions, adds src/stdio.ts entry points to both tsdown configs, drops the unused @types/cross-spawn devDep from the server package, adds barrelClean.test.ts regression guards in both packages, and migrates every doc/example/integration-test callsite (36 files total). A CLAUDE.md rule codifies the runtime-neutral-root-entry constraint.

Since my last review (2026-04-27)

Commit 9b2b5d3 adds README.md to the diff with the split import, which was the last open item I'd raised. A fresh grep for Stdio(Server|Client)Transport.*from\s+['"]@modelcontextprotocol/(client|server)['"] across the repo now returns zero matches, and the moved helper symbols (getDefaultEnvironment, DEFAULT_INHERITED_ENV_VARS, StdioServerParameters) have no remaining root-barrel references outside the new subpath/tests. The changeset prose, server index.ts/stdio.ts comments, migration-SKILL.mdshared/stdio.js row, and server barrelClean symbol-absence assertion from earlier rounds are all in their corrected form.

Security risks

None. This is an export-map/packaging refactor; no auth, crypto, network, or input-handling code paths change. Runtime behavior of the transports themselves is untouched.

Level of scrutiny

Moderate-to-high. The implementation is mechanical, but it is an intentional breaking change to the public API surface of two published packages (removing four root exports and introducing a new subpath), wired through package.jsonexports, typesVersions, and the tsdown entry list. That falls under the repo's "every new export is intentional" / "removing from public API" bar and the v2-bc label, so a maintainer should give the final ack on the API shape rather than a bot.

Other factors

• KKonstantinov reviewed an earlier revision and his NODE_ONLY-regex alignment request was applied (both barrelClean tests now share the same pattern plus the server symbol-absence check).
• barrelClean tests give a build-output regression guard; integration tests and all type-checked *.examples.ts exercise the new import path.
• Migration docs (migration.md, migration-SKILL.md) and the changeset cover the break per repo checklist.

[KKonstantinov]

LGTM!

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

// beforeimport{Client,StdioClientTransport}from'@modelcontextprotocol/client';import{McpServer,StdioServerTransport}from'@modelcontextprotocol/server';// afterimport{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: 9b2b5d3

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: 9b2b5d3

[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

[KKonstantinov]

Few comments, none of them blocking:

• @types/cross-spawn in packages/server/package.json - could be cleaned-up, not used
• packages/server/src/server/mcp.examples.ts - still imports from /stdio.js, but this file is synced via pnpm sync:snippets. Users who copy the example will get ./stdio.js, which is a path that only resolves inside the monorepo source tree, not from the published package
• CLAUDE.md - probably would be good to add an explicit rule to the "Public API Exports" section as the PR establishes a clean invariant. E.g. something like

Exports whose module graph transitively touches unpolyfillable Node builtins (node:child_process, node:net, node:stream's runtime APIs, cross-spawn, etc.) must live at a named subpath export (e.g. ./stdio) and be covered by a barrelClean test in that package. The package root must stay runtime-neutral so browser and Cloudflare Workers bundlers can consume it.

• Five tsconfigs now mirror thw ./stdio subpath by hand - it adds a drift risk, we could do some small follow-up lint/script that reads packages/{client,server}/package.jsonexports, derives the expected paths entries, and fails if any of the many tsconfigs are missing ones. Not needed for this PR, just an idea as the list grows longer

[felixweinberger]

@KKonstantinov thanks. Addressed in 9b2b5d3: dropped @types/cross-spawn from server, added the runtime-neutral root rule to CLAUDE.md, and fixed the README quickstart import while I was at it. Left mcp.examples.ts alone since sync:snippets only copies the #region body into JSDoc (the import line isn't synced) and all sibling .examples.ts files use the same relative pattern. Agree the tsconfig drift check would be a nice follow-up.

[claude]

Thanks — 9b2b5d3 picks up the README quickstart import, and a repo-wide grep now finds zero remaining root-barrel Stdio*Transport imports. Everything I flagged is addressed; deferring to a maintainer for final sign-off on the breaking export-map change.

Extended reasoning...

Overview

This PR moves StdioClientTransport (plus getDefaultEnvironment, DEFAULT_INHERITED_ENV_VARS, StdioServerParameters) and StdioServerTransport from the package root barrels to new ./stdio subpath exports in @modelcontextprotocol/client and @modelcontextprotocol/server. It adds the subpath to both package.jsonexports maps and typesVersions, adds src/stdio.ts entry points to both tsdown configs, drops the unused @types/cross-spawn devDep from the server package, adds barrelClean.test.ts regression guards in both packages, and migrates every doc/example/integration-test callsite (36 files total). A CLAUDE.md rule codifies the runtime-neutral-root-entry constraint.

Since my last review (2026-04-27)

Commit 9b2b5d3 adds README.md to the diff with the split import, which was the last open item I'd raised. A fresh grep for Stdio(Server|Client)Transport.*from\s+['"]@modelcontextprotocol/(client|server)['"] across the repo now returns zero matches, and the moved helper symbols (getDefaultEnvironment, DEFAULT_INHERITED_ENV_VARS, StdioServerParameters) have no remaining root-barrel references outside the new subpath/tests. The changeset prose, server index.ts/stdio.ts comments, migration-SKILL.mdshared/stdio.js row, and server barrelClean symbol-absence assertion from earlier rounds are all in their corrected form.

Security risks

None. This is an export-map/packaging refactor; no auth, crypto, network, or input-handling code paths change. Runtime behavior of the transports themselves is untouched.

Level of scrutiny

Moderate-to-high. The implementation is mechanical, but it is an intentional breaking change to the public API surface of two published packages (removing four root exports and introducing a new subpath), wired through package.jsonexports, typesVersions, and the tsdown entry list. That falls under the repo's "every new export is intentional" / "removing from public API" bar and the v2-bc label, so a maintainer should give the final ack on the API shape rather than a bot.

Other factors

• KKonstantinov reviewed an earlier revision and his NODE_ONLY-regex alignment request was applied (both barrelClean tests now share the same pattern plus the server symbol-absence check).
• barrelClean tests give a build-output regression guard; integration tests and all type-checked *.examples.ts exercise the new import path.
• Migration docs (migration.md, migration-SKILL.md) and the changeset cover the break per repo checklist.

[KKonstantinov]

LGTM!

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

// beforeimport{Client,StdioClientTransport}from'@modelcontextprotocol/client';import{McpServer,StdioServerTransport}from'@modelcontextprotocol/server';// afterimport{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: 9b2b5d3

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: 9b2b5d3

[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

[KKonstantinov]

Few comments, none of them blocking:

• @types/cross-spawn in packages/server/package.json - could be cleaned-up, not used
• packages/server/src/server/mcp.examples.ts - still imports from /stdio.js, but this file is synced via pnpm sync:snippets. Users who copy the example will get ./stdio.js, which is a path that only resolves inside the monorepo source tree, not from the published package
• CLAUDE.md - probably would be good to add an explicit rule to the "Public API Exports" section as the PR establishes a clean invariant. E.g. something like

Exports whose module graph transitively touches unpolyfillable Node builtins (node:child_process, node:net, node:stream's runtime APIs, cross-spawn, etc.) must live at a named subpath export (e.g. ./stdio) and be covered by a barrelClean test in that package. The package root must stay runtime-neutral so browser and Cloudflare Workers bundlers can consume it.

• Five tsconfigs now mirror thw ./stdio subpath by hand - it adds a drift risk, we could do some small follow-up lint/script that reads packages/{client,server}/package.jsonexports, derives the expected paths entries, and fails if any of the many tsconfigs are missing ones. Not needed for this PR, just an idea as the list grows longer

[felixweinberger]

@KKonstantinov thanks. Addressed in 9b2b5d3: dropped @types/cross-spawn from server, added the runtime-neutral root rule to CLAUDE.md, and fixed the README quickstart import while I was at it. Left mcp.examples.ts alone since sync:snippets only copies the #region body into JSDoc (the import line isn't synced) and all sibling .examples.ts files use the same relative pattern. Agree the tsconfig drift check would be a nice follow-up.

[claude]

Thanks — 9b2b5d3 picks up the README quickstart import, and a repo-wide grep now finds zero remaining root-barrel Stdio*Transport imports. Everything I flagged is addressed; deferring to a maintainer for final sign-off on the breaking export-map change.

Extended reasoning...

Overview

This PR moves StdioClientTransport (plus getDefaultEnvironment, DEFAULT_INHERITED_ENV_VARS, StdioServerParameters) and StdioServerTransport from the package root barrels to new ./stdio subpath exports in @modelcontextprotocol/client and @modelcontextprotocol/server. It adds the subpath to both package.jsonexports maps and typesVersions, adds src/stdio.ts entry points to both tsdown configs, drops the unused @types/cross-spawn devDep from the server package, adds barrelClean.test.ts regression guards in both packages, and migrates every doc/example/integration-test callsite (36 files total). A CLAUDE.md rule codifies the runtime-neutral-root-entry constraint.

Since my last review (2026-04-27)

Commit 9b2b5d3 adds README.md to the diff with the split import, which was the last open item I'd raised. A fresh grep for Stdio(Server|Client)Transport.*from\s+['"]@modelcontextprotocol/(client|server)['"] across the repo now returns zero matches, and the moved helper symbols (getDefaultEnvironment, DEFAULT_INHERITED_ENV_VARS, StdioServerParameters) have no remaining root-barrel references outside the new subpath/tests. The changeset prose, server index.ts/stdio.ts comments, migration-SKILL.mdshared/stdio.js row, and server barrelClean symbol-absence assertion from earlier rounds are all in their corrected form.

Security risks

None. This is an export-map/packaging refactor; no auth, crypto, network, or input-handling code paths change. Runtime behavior of the transports themselves is untouched.

Level of scrutiny

Moderate-to-high. The implementation is mechanical, but it is an intentional breaking change to the public API surface of two published packages (removing four root exports and introducing a new subpath), wired through package.jsonexports, typesVersions, and the tsdown entry list. That falls under the repo's "every new export is intentional" / "removing from public API" bar and the v2-bc label, so a maintainer should give the final ack on the API shape rather than a bot.

Other factors

• KKonstantinov reviewed an earlier revision and his NODE_ONLY-regex alignment request was applied (both barrelClean tests now share the same pattern plus the server symbol-absence check).
• barrelClean tests give a build-output regression guard; integration tests and all type-checked *.examples.ts exercise the new import path.
• Migration docs (migration.md, migration-SKILL.md) and the changeset cover the break per repo checklist.

[KKonstantinov]

LGTM!

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

// beforeimport{Client,StdioClientTransport}from'@modelcontextprotocol/client';import{McpServer,StdioServerTransport}from'@modelcontextprotocol/server';// afterimport{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: 9b2b5d3

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: 9b2b5d3

[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

[KKonstantinov]

Few comments, none of them blocking:

• @types/cross-spawn in packages/server/package.json - could be cleaned-up, not used
• packages/server/src/server/mcp.examples.ts - still imports from /stdio.js, but this file is synced via pnpm sync:snippets. Users who copy the example will get ./stdio.js, which is a path that only resolves inside the monorepo source tree, not from the published package
• CLAUDE.md - probably would be good to add an explicit rule to the "Public API Exports" section as the PR establishes a clean invariant. E.g. something like

Exports whose module graph transitively touches unpolyfillable Node builtins (node:child_process, node:net, node:stream's runtime APIs, cross-spawn, etc.) must live at a named subpath export (e.g. ./stdio) and be covered by a barrelClean test in that package. The package root must stay runtime-neutral so browser and Cloudflare Workers bundlers can consume it.

• Five tsconfigs now mirror thw ./stdio subpath by hand - it adds a drift risk, we could do some small follow-up lint/script that reads packages/{client,server}/package.jsonexports, derives the expected paths entries, and fails if any of the many tsconfigs are missing ones. Not needed for this PR, just an idea as the list grows longer

[felixweinberger]

@KKonstantinov thanks. Addressed in 9b2b5d3: dropped @types/cross-spawn from server, added the runtime-neutral root rule to CLAUDE.md, and fixed the README quickstart import while I was at it. Left mcp.examples.ts alone since sync:snippets only copies the #region body into JSDoc (the import line isn't synced) and all sibling .examples.ts files use the same relative pattern. Agree the tsconfig drift check would be a nice follow-up.

[claude]

Thanks — 9b2b5d3 picks up the README quickstart import, and a repo-wide grep now finds zero remaining root-barrel Stdio*Transport imports. Everything I flagged is addressed; deferring to a maintainer for final sign-off on the breaking export-map change.

Extended reasoning...

Overview

This PR moves StdioClientTransport (plus getDefaultEnvironment, DEFAULT_INHERITED_ENV_VARS, StdioServerParameters) and StdioServerTransport from the package root barrels to new ./stdio subpath exports in @modelcontextprotocol/client and @modelcontextprotocol/server. It adds the subpath to both package.jsonexports maps and typesVersions, adds src/stdio.ts entry points to both tsdown configs, drops the unused @types/cross-spawn devDep from the server package, adds barrelClean.test.ts regression guards in both packages, and migrates every doc/example/integration-test callsite (36 files total). A CLAUDE.md rule codifies the runtime-neutral-root-entry constraint.

Since my last review (2026-04-27)

Commit 9b2b5d3 adds README.md to the diff with the split import, which was the last open item I'd raised. A fresh grep for Stdio(Server|Client)Transport.*from\s+['"]@modelcontextprotocol/(client|server)['"] across the repo now returns zero matches, and the moved helper symbols (getDefaultEnvironment, DEFAULT_INHERITED_ENV_VARS, StdioServerParameters) have no remaining root-barrel references outside the new subpath/tests. The changeset prose, server index.ts/stdio.ts comments, migration-SKILL.mdshared/stdio.js row, and server barrelClean symbol-absence assertion from earlier rounds are all in their corrected form.

Security risks

None. This is an export-map/packaging refactor; no auth, crypto, network, or input-handling code paths change. Runtime behavior of the transports themselves is untouched.

Level of scrutiny

Moderate-to-high. The implementation is mechanical, but it is an intentional breaking change to the public API surface of two published packages (removing four root exports and introducing a new subpath), wired through package.jsonexports, typesVersions, and the tsdown entry list. That falls under the repo's "every new export is intentional" / "removing from public API" bar and the v2-bc label, so a maintainer should give the final ack on the API shape rather than a bot.

Other factors

• KKonstantinov reviewed an earlier revision and his NODE_ONLY-regex alignment request was applied (both barrelClean tests now share the same pattern plus the server symbol-absence check).
• barrelClean tests give a build-output regression guard; integration tests and all type-checked *.examples.ts exercise the new import path.
• Migration docs (migration.md, migration-SKILL.md) and the changeset cover the break per repo checklist.

[KKonstantinov]

LGTM!

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

// beforeimport{Client,StdioClientTransport}from'@modelcontextprotocol/client';import{McpServer,StdioServerTransport}from'@modelcontextprotocol/server';// afterimport{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: 9b2b5d3

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: 9b2b5d3

[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

[KKonstantinov]

Few comments, none of them blocking:

• @types/cross-spawn in packages/server/package.json - could be cleaned-up, not used
• packages/server/src/server/mcp.examples.ts - still imports from /stdio.js, but this file is synced via pnpm sync:snippets. Users who copy the example will get ./stdio.js, which is a path that only resolves inside the monorepo source tree, not from the published package
• CLAUDE.md - probably would be good to add an explicit rule to the "Public API Exports" section as the PR establishes a clean invariant. E.g. something like

Exports whose module graph transitively touches unpolyfillable Node builtins (node:child_process, node:net, node:stream's runtime APIs, cross-spawn, etc.) must live at a named subpath export (e.g. ./stdio) and be covered by a barrelClean test in that package. The package root must stay runtime-neutral so browser and Cloudflare Workers bundlers can consume it.

• Five tsconfigs now mirror thw ./stdio subpath by hand - it adds a drift risk, we could do some small follow-up lint/script that reads packages/{client,server}/package.jsonexports, derives the expected paths entries, and fails if any of the many tsconfigs are missing ones. Not needed for this PR, just an idea as the list grows longer

[felixweinberger]

@KKonstantinov thanks. Addressed in 9b2b5d3: dropped @types/cross-spawn from server, added the runtime-neutral root rule to CLAUDE.md, and fixed the README quickstart import while I was at it. Left mcp.examples.ts alone since sync:snippets only copies the #region body into JSDoc (the import line isn't synced) and all sibling .examples.ts files use the same relative pattern. Agree the tsconfig drift check would be a nice follow-up.

[claude]

Thanks — 9b2b5d3 picks up the README quickstart import, and a repo-wide grep now finds zero remaining root-barrel Stdio*Transport imports. Everything I flagged is addressed; deferring to a maintainer for final sign-off on the breaking export-map change.

Extended reasoning...

Overview

This PR moves StdioClientTransport (plus getDefaultEnvironment, DEFAULT_INHERITED_ENV_VARS, StdioServerParameters) and StdioServerTransport from the package root barrels to new ./stdio subpath exports in @modelcontextprotocol/client and @modelcontextprotocol/server. It adds the subpath to both package.jsonexports maps and typesVersions, adds src/stdio.ts entry points to both tsdown configs, drops the unused @types/cross-spawn devDep from the server package, adds barrelClean.test.ts regression guards in both packages, and migrates every doc/example/integration-test callsite (36 files total). A CLAUDE.md rule codifies the runtime-neutral-root-entry constraint.

Since my last review (2026-04-27)

Commit 9b2b5d3 adds README.md to the diff with the split import, which was the last open item I'd raised. A fresh grep for Stdio(Server|Client)Transport.*from\s+['"]@modelcontextprotocol/(client|server)['"] across the repo now returns zero matches, and the moved helper symbols (getDefaultEnvironment, DEFAULT_INHERITED_ENV_VARS, StdioServerParameters) have no remaining root-barrel references outside the new subpath/tests. The changeset prose, server index.ts/stdio.ts comments, migration-SKILL.mdshared/stdio.js row, and server barrelClean symbol-absence assertion from earlier rounds are all in their corrected form.

Security risks

None. This is an export-map/packaging refactor; no auth, crypto, network, or input-handling code paths change. Runtime behavior of the transports themselves is untouched.

Level of scrutiny

Moderate-to-high. The implementation is mechanical, but it is an intentional breaking change to the public API surface of two published packages (removing four root exports and introducing a new subpath), wired through package.jsonexports, typesVersions, and the tsdown entry list. That falls under the repo's "every new export is intentional" / "removing from public API" bar and the v2-bc label, so a maintainer should give the final ack on the API shape rather than a bot.

Other factors

• KKonstantinov reviewed an earlier revision and his NODE_ONLY-regex alignment request was applied (both barrelClean tests now share the same pattern plus the server symbol-absence check).
• barrelClean tests give a build-output regression guard; integration tests and all type-checked *.examples.ts exercise the new import path.
• Migration docs (migration.md, migration-SKILL.md) and the changeset cover the break per repo checklist.

[KKonstantinov]

LGTM!

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

// beforeimport{Client,StdioClientTransport}from'@modelcontextprotocol/client';import{McpServer,StdioServerTransport}from'@modelcontextprotocol/server';// afterimport{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: 9b2b5d3

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: 9b2b5d3

[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

[KKonstantinov]

Few comments, none of them blocking:

• @types/cross-spawn in packages/server/package.json - could be cleaned-up, not used
• packages/server/src/server/mcp.examples.ts - still imports from /stdio.js, but this file is synced via pnpm sync:snippets. Users who copy the example will get ./stdio.js, which is a path that only resolves inside the monorepo source tree, not from the published package
• CLAUDE.md - probably would be good to add an explicit rule to the "Public API Exports" section as the PR establishes a clean invariant. E.g. something like

Exports whose module graph transitively touches unpolyfillable Node builtins (node:child_process, node:net, node:stream's runtime APIs, cross-spawn, etc.) must live at a named subpath export (e.g. ./stdio) and be covered by a barrelClean test in that package. The package root must stay runtime-neutral so browser and Cloudflare Workers bundlers can consume it.

• Five tsconfigs now mirror thw ./stdio subpath by hand - it adds a drift risk, we could do some small follow-up lint/script that reads packages/{client,server}/package.jsonexports, derives the expected paths entries, and fails if any of the many tsconfigs are missing ones. Not needed for this PR, just an idea as the list grows longer

[felixweinberger]

@KKonstantinov thanks. Addressed in 9b2b5d3: dropped @types/cross-spawn from server, added the runtime-neutral root rule to CLAUDE.md, and fixed the README quickstart import while I was at it. Left mcp.examples.ts alone since sync:snippets only copies the #region body into JSDoc (the import line isn't synced) and all sibling .examples.ts files use the same relative pattern. Agree the tsconfig drift check would be a nice follow-up.

[claude]

Thanks — 9b2b5d3 picks up the README quickstart import, and a repo-wide grep now finds zero remaining root-barrel Stdio*Transport imports. Everything I flagged is addressed; deferring to a maintainer for final sign-off on the breaking export-map change.

Extended reasoning...

Overview

This PR moves StdioClientTransport (plus getDefaultEnvironment, DEFAULT_INHERITED_ENV_VARS, StdioServerParameters) and StdioServerTransport from the package root barrels to new ./stdio subpath exports in @modelcontextprotocol/client and @modelcontextprotocol/server. It adds the subpath to both package.jsonexports maps and typesVersions, adds src/stdio.ts entry points to both tsdown configs, drops the unused @types/cross-spawn devDep from the server package, adds barrelClean.test.ts regression guards in both packages, and migrates every doc/example/integration-test callsite (36 files total). A CLAUDE.md rule codifies the runtime-neutral-root-entry constraint.

Since my last review (2026-04-27)

Commit 9b2b5d3 adds README.md to the diff with the split import, which was the last open item I'd raised. A fresh grep for Stdio(Server|Client)Transport.*from\s+['"]@modelcontextprotocol/(client|server)['"] across the repo now returns zero matches, and the moved helper symbols (getDefaultEnvironment, DEFAULT_INHERITED_ENV_VARS, StdioServerParameters) have no remaining root-barrel references outside the new subpath/tests. The changeset prose, server index.ts/stdio.ts comments, migration-SKILL.mdshared/stdio.js row, and server barrelClean symbol-absence assertion from earlier rounds are all in their corrected form.

Security risks

None. This is an export-map/packaging refactor; no auth, crypto, network, or input-handling code paths change. Runtime behavior of the transports themselves is untouched.

Level of scrutiny

Moderate-to-high. The implementation is mechanical, but it is an intentional breaking change to the public API surface of two published packages (removing four root exports and introducing a new subpath), wired through package.jsonexports, typesVersions, and the tsdown entry list. That falls under the repo's "every new export is intentional" / "removing from public API" bar and the v2-bc label, so a maintainer should give the final ack on the API shape rather than a bot.

Other factors

• KKonstantinov reviewed an earlier revision and his NODE_ONLY-regex alignment request was applied (both barrelClean tests now share the same pattern plus the server symbol-absence check).
• barrelClean tests give a build-output regression guard; integration tests and all type-checked *.examples.ts exercise the new import path.
• Migration docs (migration.md, migration-SKILL.md) and the changeset cover the break per repo checklist.

[KKonstantinov]

LGTM!