refactor(client,server): move stdio transports to ./stdio subpath export by felixweinberger · Pull Request #1871 · modelcontextprotocol/typescript-sdk

felixweinberger · 2026-04-09T16:01:51Z

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 · 2026-04-09T16:01:55Z

🦋 Changeset detected

Latest commit: 86a6331

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 · 2026-04-09T16:03:25Z

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: 86a6331

felixweinberger · 2026-04-09T16:11:58Z

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

Stdio transports require a process-spawning runtime (Node.js, Bun, Deno). Exporting them from the package root meant browser and Cloudflare Workers bundlers pulled in node:child_process, node:stream, and cross-spawn. Move StdioClientTransport, getDefaultEnvironment, DEFAULT_INHERITED_ENV_VARS, and StdioServerParameters to @modelcontextprotocol/client/stdio, and StdioServerTransport to @modelcontextprotocol/server/stdio. The root entry is now browser-safe; stdio consumers update one import path.

…stdio in quickstart tsconfig paths - chunkImportsOf now BFS-walks the chunk import graph so the test name ('transitively imported') matches the implementation - beforeAll builds the package if dist/ is missing (CI test job runs pnpm test:all without a build step) - examples/{client,server}-quickstart/tsconfig.json: add /stdio to paths so tsc --noEmit resolves the new subpath without a prior build

…ntegration CI test:all runs without building dist; vite-tsconfig-paths needs the /stdio mapping to resolve to src/stdio.ts.

felixweinberger · 2026-04-13T14:47:01Z

@claude review

…arify subpath comment Server stdio uses only type-level node:stream imports (erased), so the NODE_ONLY regex cannot detect re-export regressions. Add an explicit symbol-absence check and correct the misleading comment in src/stdio.ts.

felixweinberger · 2026-04-13T15:26:17Z

@claude review

felixweinberger · 2026-04-13T18:16:23Z

@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.json exports, 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

KKonstantinov · 2026-04-15T09:33:33Z

+
+const pkgDir = join(dirname(fileURLToPath(import.meta.url)), '../..');
+const distDir = join(pkgDir, 'dist');
+const NODE_ONLY = /\b(node:stream|node:child_process)\b/;


The server NODE_ONLY pattern is narrower than the client's, however think we could be more defensive about this and align on an exhaustive pattern, so that the addition of any of the listed is prohibited in the future -> right now, they could be accidentally added by a contributor and/or missed by us). Aligning on the regex will further strengthen this check.

Addressed in 86a6331.

…er index comment, align barrelClean NODE_ONLY regex

claude bot reviewed Apr 9, 2026

View reviewed changes

Comment thread packages/core/src/errors/sdkErrors.ts

felixweinberger force-pushed the fweinberger/browser-stdio-conditional-export branch from 5350730 to 95b5eca Compare April 9, 2026 16:33

felixweinberger changed the title ~~fix(client,server): browser-conditional export for stdio transports~~ refactor(client,server): move stdio transports to ./stdio subpath export Apr 9, 2026

felixweinberger force-pushed the fweinberger/browser-stdio-conditional-export branch from 95b5eca to 46fe6d2 Compare April 9, 2026 16:34

felixweinberger mentioned this pull request Apr 13, 2026

feat(core): add extension() registrar for SEP-2133 capability-aware custom methods #1868

Closed

9 tasks

felixweinberger added 2 commits April 13, 2026 14:26

fix: add /stdio tsconfig paths in examples/{client,server} and test/i…

dc84940

…ntegration CI test:all runs without building dist; vite-tsconfig-paths needs the /stdio mapping to resolve to src/stdio.ts.

claude bot reviewed Apr 13, 2026

View reviewed changes

Comment thread packages/server/src/stdio.ts

felixweinberger mentioned this pull request Apr 13, 2026

[DO NOT MERGE] Port to SDK v2 (extension() registrar / composition) modelcontextprotocol/ext-apps#612

Closed

9 tasks

claude bot reviewed Apr 13, 2026

View reviewed changes

Comment thread docs/migration-SKILL.md Outdated

Merge branch 'main' into fweinberger/browser-stdio-conditional-export

a4a6100

KKonstantinov reviewed Apr 15, 2026

View reviewed changes

felixweinberger mentioned this pull request Apr 15, 2026

feat: port to SDK v2 via concrete Protocol (typescript-sdk#1891) modelcontextprotocol/ext-apps#614

Draft

6 tasks

felixweinberger marked this pull request as ready for review April 15, 2026 19:39

felixweinberger requested a review from a team as a code owner April 15, 2026 19:39

felixweinberger added the v2-bc v2 backwards-compatibility series label Apr 15, 2026

claude bot reviewed Apr 15, 2026

View reviewed changes

Comment thread packages/server/src/index.ts Outdated

felixweinberger added this to the v2.0.0-bc milestone Apr 15, 2026

fix: address review comments — migration table shared/stdio row, serv…

86a6331

…er index comment, align barrelClean NODE_ONLY regex

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

refactor(client,server): move stdio transports to ./stdio subpath export#1871
felixweinberger wants to merge 6 commits intomainfrom
fweinberger/browser-stdio-conditional-export

felixweinberger commented Apr 9, 2026 •

edited

Loading

Uh oh!

changeset-bot bot commented Apr 9, 2026 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Apr 9, 2026 •

edited

Loading

Uh oh!

felixweinberger commented Apr 9, 2026

Uh oh!

claude bot left a comment

Uh oh!

Uh oh!

felixweinberger commented Apr 13, 2026

Uh oh!

Uh oh!

felixweinberger commented Apr 13, 2026

Uh oh!

felixweinberger commented Apr 13, 2026

Uh oh!

Uh oh!

KKonstantinov left a comment

Uh oh!

KKonstantinov Apr 15, 2026

Uh oh!

felixweinberger Apr 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

felixweinberger commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

changeset-bot bot commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-pr-new bot commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

felixweinberger commented Apr 9, 2026

Uh oh!

claude bot left a comment

Choose a reason for hiding this comment

Overview

Security Risks

Level of Scrutiny

Other Factors

Uh oh!

Uh oh!

felixweinberger commented Apr 13, 2026

Uh oh!

Uh oh!

felixweinberger commented Apr 13, 2026

Uh oh!

felixweinberger commented Apr 13, 2026

Uh oh!

Uh oh!

KKonstantinov left a comment

Choose a reason for hiding this comment

Uh oh!

KKonstantinov Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

felixweinberger Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

felixweinberger commented Apr 9, 2026 •

edited

Loading

changeset-bot bot commented Apr 9, 2026 •

edited

Loading

pkg-pr-new bot commented Apr 9, 2026 •

edited

Loading