v2: limit public exports

[KKonstantinov]

Limit public API exports to a curated surface, hiding internal implementation details (Zod schemas, Protocol class, stdio internals, etc.) from end users.

Motivation and Context

The SDK currently re-exports everything from @modelcontextprotocol/core through @modelcontextprotocol/client and @modelcontextprotocol/server via blanket export * statements. This leaks internal implementation details into the public API surface — Zod schema objects, the abstract Protocol class, internal helpers like normalizeHeaders and mergeCapabilities, and the InMemoryTransport test utility.

This PR introduces a two-tier export system:

• Internal (@modelcontextprotocol/core): Full export * for use by client/server packages internally
• Public (@modelcontextprotocol/core/public): Curated named exports for end users, re-exported by @modelcontextprotocol/client and @modelcontextprotocol/server

Additionally, the monolithic types.ts file (~2800 lines) is split into focused modules: schemas.ts (Zod schema definitions only), types.ts (TypeScript type aliases and standalone interfaces), constants.ts, enums.ts, errors.ts, and guards.ts.

How Has This Been Tested?

• pnpm typecheck:all — passes across all packages
• pnpm lint:all — passes across all packages
• pnpm test:all — all 386 tests pass
• pnpm check:all — passes (includes typecheck + lint + docs:check with 0 warnings)

Breaking Changes

Yes — consumers who imported internal symbols that are no longer part of the public API will need to update their code:

• Zod schema objects (ToolSchema, ResourceSchema, etc.) are no longer exported publicly. TypeScript types derived from them (Tool, Resource, etc.) remain available.
• InMemoryTransport is no longer exported publicly (test utility only).
• Protocol class and mergeCapabilities are no longer exported publicly (internal abstractions).
• Internal helpers (normalizeHeaders, stdio parsing, etc.) are no longer exported publicly.
• All protocol TypeScript types, error classes, type guards, constants, enums, auth types/utilities, transport interfaces, and response message utilities remain in the public API.

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

Architecture

The new @modelcontextprotocol/core/public subpath export (packages/core/src/exports/public/index.ts) contains explicit named exports for each public symbol, organized by category. Client and server barrels now use export * from '@modelcontextprotocol/core/public' instead of export * from '@modelcontextprotocol/core', combined with explicit named exports for their own symbols.

Types split

The original packages/core/src/types/types.ts has been split into:

File	Contents
schemas.ts	All Zod schema definitions, runtime schema lookup functions
types.ts	All TypeScript type aliases (Infer<typeof Schema>), standalone interfaces, protocol type maps
constants.ts	Protocol version constants, JSON-RPC error codes
enums.ts	ProtocolErrorCode enum
errors.ts	ProtocolError and UrlElicitationRequiredError classes
guards.ts	Type guard functions (isJSONRPCRequest, etc.)
index.ts	Internal barrel re-exporting all of the above

An internal barrel (types/index.ts) re-exports everything for internal package use. The public barrel (exports/public/index.ts) exports from types/types.ts but NOT from types/schemas.ts, keeping Zod runtime objects internal.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 7c3542e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/client

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

@modelcontextprotocol/server

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

@modelcontextprotocol/express

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

@modelcontextprotocol/hono

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

@modelcontextprotocol/node

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

commit: 72e446c