feat(sdk): @modelcontextprotocol/sdk meta-package with v1 deep-import subpaths by felixweinberger · Pull Request #1913 · modelcontextprotocol/typescript-sdk

felixweinberger · 2026-04-16T13:41:12Z

Part of the v2 backwards-compatibility series — see reviewer guide.

The Layer-2 lever: a meta-package depending on client+server+node+server-auth-legacy that re-exports at v1's ~28 deep-import subpaths (sdk/types.js, sdk/server/mcp.js, etc.) with extensionless aliases. Permanent primary entry — split packages opt-in for bundle-conscious users.

Motivation and Context

The Layer-2 lever: a meta-package depending on client+server+node+server-auth-legacy that re-exports at v1's ~28 deep-import subpaths (sdk/types.js, sdk/server/mcp.js, etc.) with extensionless aliases. Permanent primary entry — split packages opt-in for bundle-conscious users.

v1 vs v2 pattern & evidence

v1 pattern:

import{McpServer}from'@modelcontextprotocol/sdk/server/mcp.js'// (or extensionless `/server/mcp`)

v2-native:

// Same — meta-package is the recommended entry.import{McpServer}from'@modelcontextprotocol/sdk/server/mcp.js'// Or, for split packages:import{McpServer}from'@modelcontextprotocol/server'

Evidence: This is what makes 'bump only' work. Validated: 5 OSS repos at 0 SDK errors with bump-only install.

How Has This Been Tested?

packages/sdk/test/compat.test.ts — 5 cases (subpath resolution + schema-arg shim reachability via re-exports)
test/integration/test/compat/v1Surface.test.ts — 6 end-to-end cases via v1 paths only (McpServer.tool() + InMemoryTransport + callTool(params, ResultSchema))
Integration: validated bump-only against 5 OSS repos via the v2-bc-integration validation branch
pnpm typecheck:all && pnpm lint:all && pnpm test:all green (sdk 5/5, integration 428/428)

Breaking Changes

None — additive @deprecated shim. Removed in v3.

Types of changes

New feature (non-breaking change which adds functionality)

Checklist

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

Additional context

Stacks on fweinberger/v2-bc-d1-base = main + #1891 (A1), #1898 (B4), #1900 (C2), #1901 (C4), #1902 (C5), #1903 (C7), #1904 (C8), #1906 (C10), #1908 (E2), #1909 (E3), #1834 (A4). Re-exports their surface; tests exercise the combined v1 API. As those land on main, this PR will be retargeted and the diff stays at ~1000 LOC (44 files).

typedoc.config.mjs: excludes @modelcontextprotocol/sdk from API-doc generation — it's a pure re-export package, and inherited {@link} JSDoc on re-exported symbols can't resolve cross-package module paths (spurious warnings, no doc value added).

changeset-bot · 2026-04-16T13:41:17Z

🦋 Changeset detected

Latest commit: 6f398c0

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

This PR includes changesets to release 1 package

Name	Type
@modelcontextprotocol/sdk	Patch

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-16T13:42:59Z

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/client@1913

@modelcontextprotocol/server

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/server@1913

@modelcontextprotocol/server-auth-legacy

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/server-auth-legacy@1913

@modelcontextprotocol/express

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/express@1913

@modelcontextprotocol/fastify

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/fastify@1913

@modelcontextprotocol/hono

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/hono@1913

@modelcontextprotocol/node

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/node@1913

commit: 6f398c0

felixweinberger · 2026-04-16T19:22:18Z

@claude review

felixweinberger · 2026-04-16T20:23:17Z

@claude review

felixweinberger · 2026-04-16T20:36:46Z

@claude review

felixweinberger · 2026-04-16T20:57:38Z

@claude review

felixweinberger · 2026-04-17T08:06:55Z

@claude review

felixweinberger · 2026-04-17T08:30:51Z

@claude review

…-import subpaths Adds packages/sdk as the primary v2 entry point. Re-exports the full server + client + node surface from a single root barrel (TS2308-safe named re-exports for client/node) and preserves v1 deep-import subpaths (/types.js, /server/mcp.js, /client/index.js, /shared/transport.js, /shared/protocol.js, /server/auth/errors.js with the 17 OAuth error subclasses, etc.). Folds in the C3/C6 schema-arg shims: the sdk-exported Server and Client are thin subclasses that additionally accept the deprecated v1 calling conventions setRequestHandler(ZodSchema, h), setNotificationHandler( ZodSchema, h) and request(req, ResultSchema, opts), extracting the method literal and forwarding to the v2 string-based API with a one-time deprecation warning.

…root; optional express/hono peers - All five server/auth/* subpaths now re-export from @modelcontextprotocol/server-auth-legacy so OAuth error subclasses share the same OAuthError identity that the legacy router and requireBearerAuth check with instanceof. Previously errors.ts defined local subclasses extending core's OAuthError and bearerAuth.ts re-exported /express, causing instanceof to fail (HTTP 500 instead of 400/401). - Drop @modelcontextprotocol/express dependency (no longer imported). - Forward express and hono as optional peerDependencies so consumers who do not use the auth or hono-adapter subpaths get no unmet-peer warnings. - Add top-level types field for legacy moduleResolution: node. - Revert 87d4f17's stdio re-exports from the root barrel; stdio remains subpath-only to match the underlying client/server packages.

…server/zod-compat subpath

…StartSSEOptions to subpaths

…/server/mcp

…t-arg setRequestHandler; drop re-exports of types removed by closing #1900/#1917

…nstead of closed .tool() variadic (C2/#1900)

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

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

felixweinberger force-pushed the fweinberger/v2-bc-d1-base branch from 4eeafa1 to 5018344Compare April 16, 2026 14:44

felixweinberger force-pushed the fweinberger/v2-bc-sdk-meta-package branch from 33a3b30 to 522e770Compare April 16, 2026 14:55

felixweinberger force-pushed the fweinberger/v2-bc-d1-base branch from 47a96d5 to dfc33ccCompare April 16, 2026 19:27

claudeBot reviewed Apr 16, 2026
View reviewed changes

Comment threadpackages/sdk/src/index.ts
Comment threadpackages/sdk/src/types.ts Outdated
Comment threadpackages/sdk/package.json
Comment thread.changeset/sdk-meta-package.md Outdated

felixweinberger force-pushed the fweinberger/v2-bc-sdk-meta-package branch 2 times, most recently from 9cdd4b2 to 30b3ecdCompare April 16, 2026 19:39

felixweinberger force-pushed the fweinberger/v2-bc-d1-base branch from 9145c02 to 5798b1aCompare April 16, 2026 20:10

felixweinberger force-pushed the fweinberger/v2-bc-sdk-meta-package branch from 30b3ecd to 1f1f722Compare April 16, 2026 20:13

felixweinberger force-pushed the fweinberger/v2-bc-sdk-meta-package branch from 1f1f722 to aa25cbcCompare April 16, 2026 20:23

felixweinberger force-pushed the fweinberger/v2-bc-sdk-meta-package branch 2 times, most recently from a84e5bf to 361201eCompare April 16, 2026 20:38

claudeBot reviewed Apr 16, 2026
View reviewed changes

Comment threadpackages/sdk/src/server/auth/errors.ts Outdated
Comment threadpackages/sdk/src/index.ts

felixweinberger force-pushed the fweinberger/v2-bc-sdk-meta-package branch from 361201e to 87d4f17Compare April 16, 2026 20:56

felixweinberger mentioned this pull request Apr 16, 2026
feat(compat): add /server/zod-schemas subpath re-exporting *Schema constants #1906
Closed
5 tasks

claudeBot reviewed Apr 16, 2026
View reviewed changes

Comment threadpackages/sdk/src/server/auth/middleware/bearerAuth.ts Outdated
Comment threadpackages/sdk/package.json Outdated
Comment threadpackages/sdk/src/index.ts Outdated
Comment threadpackages/sdk/package.json

felixweinberger force-pushed the fweinberger/v2-bc-d1-base branch from d0bc434 to a856a3bCompare April 16, 2026 23:49

felixweinberger force-pushed the fweinberger/v2-bc-sdk-meta-package branch 3 times, most recently from 08e958d to 44a1d41Compare April 17, 2026 08:04

claudeBot reviewed Apr 17, 2026
View reviewed changes

Comment threadpackages/sdk/package.json
Comment threadpackages/sdk/src/client/sse.ts Outdated
Comment threadpackages/sdk/package.json Outdated

felixweinberger force-pushed the fweinberger/v2-bc-sdk-meta-package branch from 44a1d41 to bf3af27Compare April 17, 2026 08:22

felixweinberger force-pushed the fweinberger/v2-bc-sdk-meta-package branch from bf3af27 to c673ae7Compare April 17, 2026 08:27

claudeBot reviewed Apr 17, 2026
View reviewed changes

Comment threadpackages/sdk/README.md

felixweinberger force-pushed the fweinberger/v2-bc-sdk-meta-package branch 4 times, most recently from 2e18a44 to 55f4068Compare April 17, 2026 11:48

felixweinberger mentioned this pull request Apr 21, 2026
[DO NOT MERGE] RFC reference: request-first SDK architecture #1942
Closed

claudeBot mentioned this pull request Apr 27, 2026
docs: reframe migration guide as 'most servers: just bump' + 21 doc gaps #1910
Closed
5 tasks

bhosmer-ant mentioned this pull request Apr 27, 2026
fix(packages): add types/typesVersions for legacy moduleResolution: node #1898
Merged
5 tasks

felixweinberger force-pushed the fweinberger/v2-bc-d1-base branch from b9e6b2d to e07c470Compare April 29, 2026 16:46

felixweinberger force-pushed the fweinberger/v2-bc-sdk-meta-package branch 2 times, most recently from 34f89ec to 4b69caaCompare April 29, 2026 19:01

felixweinberger added 10 commits April 30, 2026 14:56

fix(sdk): add top-level types field for legacy moduleResolution
7bdc098

feat(sdk): re-export Protocol/ProtocolSpec from shared/protocol; add …
a66ca86
…server/zod-compat subpath

fix(sdk): dedupe types field; add SseError/SSEServerTransportOptions/…
7e433e6
…StartSSEOptions to subpaths

docs(sdk): note optional express/hono peers for auth and sse subpaths
31ab1fe

feat(sdk): re-export LegacyToolCallback/LegacyPromptCallback from sdk…
7a71ebb
…/server/mcp

feat(sdk): v1-compat Server/Client/McpServer wrappers add schema-firs…
b66f185
…t-arg setRequestHandler; drop re-exports of types removed by closing #1900/#1917

test(integration): v1Surface uses registerTool raw-shape (C4/#1901) i…
fbfdda6
…nstead of closed .tool() variadic (C2/#1900)

chore(sdk): lint:fix import-type-specifier + sort after rebase
6f398c0

felixweinberger force-pushed the fweinberger/v2-bc-d1-base branch from 40587aa to 65a1e5cCompare April 30, 2026 15:16

felixweinberger force-pushed the fweinberger/v2-bc-sdk-meta-package branch from 4b69caa to 6f398c0Compare April 30, 2026 15:16

felixweinberger closed this Jun 8, 2026

Uh oh!

Conversation

felixweinberger commented Apr 16, 2026

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

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

Uh oh!

🦋 Changeset detected

Uh oh!

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

Uh oh!

Uh oh!

felixweinberger commented Apr 16, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

felixweinberger commented Apr 16, 2026

Uh oh!

felixweinberger commented Apr 16, 2026

Uh oh!

Uh oh!

Uh oh!

felixweinberger commented Apr 16, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

felixweinberger commented Apr 17, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

felixweinberger commented Apr 17, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

changeset-botBot commented Apr 16, 2026•
edited
Loading

pkg-pr-newBot commented Apr 16, 2026•
edited
Loading