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: 677968c

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: 677968c

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

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 5018344 Compare April 16, 2026 14:44

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

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

claude bot reviewed Apr 16, 2026

View reviewed changes

Comment thread packages/sdk/src/index.ts

Comment thread packages/sdk/src/types.ts Outdated

Comment thread packages/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 30b3ecd Compare April 16, 2026 19:39

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

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

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

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

claude bot reviewed Apr 16, 2026

View reviewed changes

Comment thread packages/sdk/src/server/auth/errors.ts Outdated

Comment thread packages/sdk/src/index.ts

felixweinberger force-pushed the fweinberger/v2-bc-sdk-meta-package branch from 361201e to 87d4f17 Compare 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

Draft

5 tasks

claude bot reviewed Apr 16, 2026

View reviewed changes

Comment thread packages/sdk/src/server/auth/middleware/bearerAuth.ts Outdated

Comment thread packages/sdk/package.json Outdated

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

Comment thread packages/sdk/package.json

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

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

claude bot reviewed Apr 17, 2026

View reviewed changes

Comment thread packages/sdk/package.json

Comment thread packages/sdk/src/client/sse.ts Outdated

Comment thread packages/sdk/package.json Outdated

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

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

claude bot reviewed Apr 17, 2026

View reviewed changes

Comment thread packages/sdk/README.md

felixweinberger force-pushed the fweinberger/v2-bc-sdk-meta-package branch 3 times, most recently from 34d1e26 to 2e18a44 Compare April 17, 2026 10:46

felixweinberger added 6 commits April 17, 2026 11:47

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

d82c17d

feat(sdk): re-export Protocol/ProtocolSpec from shared/protocol; add …

6f8c2a1

…server/zod-compat subpath

fix(sdk): dedupe types field; add SseError/SSEServerTransportOptions/…

ec3650c

…StartSSEOptions to subpaths

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

55f4068

felixweinberger force-pushed the fweinberger/v2-bc-sdk-meta-package branch from 2e18a44 to 55f4068 Compare April 17, 2026 11:48

feat(sdk): re-export LegacyToolCallback/LegacyPromptCallback from sdk…

677968c

…/server/mcp

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-bot bot 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-new bot 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-bot bot commented Apr 16, 2026 •

edited

Loading

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

edited

Loading