feat(sdk): @modelcontextprotocol/sdk meta-package with v1 deep-import subpaths

[felixweinberger]

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]

🦋 Changeset detected

Latest commit: 522e770

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]

Open in StackBlitz

@modelcontextprotocol/client

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

@modelcontextprotocol/server

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

@modelcontextprotocol/express

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

@modelcontextprotocol/fastify

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

@modelcontextprotocol/hono

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

@modelcontextprotocol/node

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

commit: 522e770