Skip to content

Commit 0ed7237

Browse files
KKonstantinovfelixweinberger
KKonstantinov
and
felixweinberger
authored
v2: limit public exports (#1680)
Co-authored-by: Felix Weinberger <fweinberger@anthropic.com> Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com>
1 parent f1ade75 commit 0ed7237

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

47 files changed

+3084
-2566
lines changed

‎CLAUDE.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,19 @@ The SDK is organized into three main layers:
6262
- `Server` (`packages/server/src/server/server.ts`) - Server implementation extending Protocol with request handler registration
6363
- `McpServer` (`packages/server/src/server/mcp.ts`) - High-level server API with simplified resource/tool/prompt registration
6464

65+
### Public API Exports
66+
67+
The SDK has a two-layer export structure to separate internal code from the public API:
68+
69+
- **`@modelcontextprotocol/core`** (main entry, `packages/core/src/index.ts`) — Internal barrel. Exports everything (including Zod schemas, Protocol class, stdio utils). Only consumed by sibling packages within the monorepo (`private: true`).
70+
- **`@modelcontextprotocol/core/public`** (`packages/core/src/exports/public/index.ts`) — Curated public API. Exports only TypeScript types, error classes, constants, and guards. Re-exported by client and server packages.
71+
- **`@modelcontextprotocol/client`** and **`@modelcontextprotocol/server`** (`packages/*/src/index.ts`) — Final public surface. Package-specific exports (named explicitly) plus re-exports from `core/public`.
72+
73+
When modifying exports:
74+
- Use explicit named exports, not `export *`, in package `index.ts` files and `core/public`.
75+
- Adding a symbol to a package `index.ts` makes it public API — do so intentionally.
76+
- Internal helpers should stay in the core internal barrel and not be added to `core/public` or package index files.
77+
6578
### Transport System
6679

6780
Transports (`packages/core/src/shared/transport.ts`) provide the communication layer:

‎docs/migration-SKILL.md‎

Lines changed: 13 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -61,18 +61,17 @@ Replace all `@modelcontextprotocol/sdk/...` imports using this table.
6161

6262
| v1 import path | v2 package |
6363
| ------------------------------------------------- | ---------------------------- |
64-
| `@modelcontextprotocol/sdk/types.js` | `@modelcontextprotocol/core` |
65-
| `@modelcontextprotocol/sdk/shared/protocol.js` | `@modelcontextprotocol/core` |
66-
| `@modelcontextprotocol/sdk/shared/transport.js` | `@modelcontextprotocol/core` |
67-
| `@modelcontextprotocol/sdk/shared/stdio.js` | `@modelcontextprotocol/core` |
68-
| `@modelcontextprotocol/sdk/shared/uriTemplate.js` | `@modelcontextprotocol/core` |
69-
| `@modelcontextprotocol/sdk/shared/auth.js` | `@modelcontextprotocol/core` |
64+
| `@modelcontextprotocol/sdk/types.js` | `@modelcontextprotocol/client` or `@modelcontextprotocol/server` |
65+
| `@modelcontextprotocol/sdk/shared/protocol.js` | `@modelcontextprotocol/client` or `@modelcontextprotocol/server` |
66+
| `@modelcontextprotocol/sdk/shared/transport.js` | `@modelcontextprotocol/client` or `@modelcontextprotocol/server` |
67+
| `@modelcontextprotocol/sdk/shared/uriTemplate.js` | `@modelcontextprotocol/client` or `@modelcontextprotocol/server` |
68+
| `@modelcontextprotocol/sdk/shared/auth.js` | `@modelcontextprotocol/client` or `@modelcontextprotocol/server` |
69+
| `@modelcontextprotocol/sdk/shared/stdio.js` | `@modelcontextprotocol/client` or `@modelcontextprotocol/server` |
7070

7171
Notes:
7272

73-
- `@modelcontextprotocol/client` and `@modelcontextprotocol/server` both re-export everything from `@modelcontextprotocol/core`, so you can import types from whichever package you already depend on.
73+
- `@modelcontextprotocol/client` and `@modelcontextprotocol/server` both re-export shared types from `@modelcontextprotocol/core`, so import from whichever package you already depend on. Do not import from `@modelcontextprotocol/core` directly — it is an internal package.
7474
- When multiple v1 imports map to the same v2 package, consolidate them into a single import statement.
75-
- If code imports from `sdk/client/...`, install `@modelcontextprotocol/client`. If from `sdk/server/...`, install `@modelcontextprotocol/server`. If from `sdk/types.js` or `sdk/shared/...` only, install `@modelcontextprotocol/core`.
7675

7776
## 4. Renamed Symbols
7877

@@ -91,7 +90,7 @@ Notes:
9190
| `ResourceReference` | `ResourceTemplateReference` |
9291
| `ResourceReferenceSchema` | `ResourceTemplateReferenceSchema` |
9392
| `IsomorphicHeaders` | REMOVED (use Web Standard `Headers`) |
94-
| `AuthInfo` (from `server/auth/types.js`) | `AuthInfo` (now in `@modelcontextprotocol/core`) |
93+
| `AuthInfo` (from `server/auth/types.js`) | `AuthInfo` (now re-exported by `@modelcontextprotocol/client` and `@modelcontextprotocol/server`) |
9594
| `McpError` | `ProtocolError` |
9695
| `ErrorCode` | `ProtocolErrorCode` |
9796
| `ErrorCode.RequestTimeout` | `SdkErrorCode.RequestTimeout` |
@@ -144,7 +143,7 @@ Update error handling:
144143
if (error instanceof McpError && error.code === ErrorCode.RequestTimeout) { ... }
145144

146145
// v2
147-
import { SdkError, SdkErrorCode } from '@modelcontextprotocol/core';
146+
import { SdkError, SdkErrorCode } from '@modelcontextprotocol/client';
148147
if (error instanceof SdkError && error.code === SdkErrorCode.RequestTimeout) { ... }
149148
```
150149

@@ -158,7 +157,7 @@ if (error instanceof StreamableHTTPError) {
158157
}
159158

160159
// v2
161-
import { SdkError, SdkErrorCode } from '@modelcontextprotocol/core';
160+
import { SdkError, SdkErrorCode } from '@modelcontextprotocol/client';
162161
if (error instanceof SdkError && error.code === SdkErrorCode.ClientHttpFailedToOpenStream) {
163162
const status = (error.data as { status?: number })?.status;
164163
}
@@ -195,11 +194,11 @@ Update OAuth error handling:
195194

196195
```typescript
197196
// v1
198-
import { InvalidClientError, InvalidGrantError } from '@modelcontextprotocol/core';
197+
import { InvalidClientError, InvalidGrantError } from '@modelcontextprotocol/client';
199198
if (error instanceof InvalidClientError) { ... }
200199

201200
// v2
202-
import { OAuthError, OAuthErrorCode } from '@modelcontextprotocol/core';
201+
import { OAuthError, OAuthErrorCode } from '@modelcontextprotocol/client';
203202
if (error instanceof OAuthError && error.code === OAuthErrorCode.InvalidClient) { ... }
204203
```
205204

@@ -210,7 +209,7 @@ Zod schemas, all callback return types. Note: `callTool()` and `request()` signa
210209

211210
The variadic `.tool()`, `.prompt()`, `.resource()` methods are removed. Use the `register*` methods with a config object.
212211

213-
**IMPORTANT**: v2 requires schema objects implementing [Standard Schema](https://standardschema.dev/) — raw shapes like `{ name: z.string() }` are no longer supported. Wrap with `z.object()` (Zod v4), or use ArkType's `type({...})`, or Valibot. For raw JSON Schema, wrap with `fromJsonSchema(schema, validator)` from `@modelcontextprotocol/core`. Applies to `inputSchema`, `outputSchema`, and `argsSchema`.
212+
**IMPORTANT**: v2 requires schema objects implementing [Standard Schema](https://standardschema.dev/) — raw shapes like `{ name: z.string() }` are no longer supported. Wrap with `z.object()` (Zod v4), or use ArkType's `type({...})`, or Valibot. For raw JSON Schema, wrap with `fromJsonSchema(schema, validator)` from `@modelcontextprotocol/server`. Applies to `inputSchema`, `outputSchema`, and `argsSchema`.
214213

215214
### Tools
216215

‎docs/migration.md‎

Lines changed: 26 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -52,13 +52,12 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
5252
```typescript
5353
import { Client, StreamableHTTPClientTransport, StdioClientTransport } from '@modelcontextprotocol/client';
5454
import { McpServer, StdioServerTransport, WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/server';
55-
import { CallToolResultSchema } from '@modelcontextprotocol/core';
5655

5756
// Node.js HTTP server transport is in the @modelcontextprotocol/node package
5857
import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
5958
```
6059

61-
Note: `@modelcontextprotocol/client` and `@modelcontextprotocol/server` both re-export everything from `@modelcontextprotocol/core`, so you can import types from whichever package you already depend on.
60+
Note: `@modelcontextprotocol/client` and `@modelcontextprotocol/server` both re-export shared types from `@modelcontextprotocol/core`, so you can import types and error classes from whichever package you already depend on. Do not import from `@modelcontextprotocol/core` directly — it is an internal package.
6261

6362
### Dropped Node.js 18 and CommonJS
6463

@@ -117,7 +116,7 @@ Server-side OAuth/auth has been removed entirely from the SDK. This includes `mc
117116

118117
Use a dedicated auth library (e.g., `better-auth`) or a full Authorization Server instead. See the [examples](../examples/server/src/) for a working demo with `better-auth`.
119118

120-
Note: `AuthInfo` has moved from `server/auth/types.ts` to `@modelcontextprotocol/core` (it's now a core type).
119+
Note: `AuthInfo` has moved from `server/auth/types.ts` to the core types and is now re-exported by `@modelcontextprotocol/client` and `@modelcontextprotocol/server`.
121120

122121
### `Headers` object instead of plain objects
123122

@@ -252,7 +251,7 @@ server.registerTool('greet', {
252251
}, async ({ name }) => { ... });
253252

254253
// Raw JSON Schema via fromJsonSchema
255-
import { fromJsonSchema, AjvJsonSchemaValidator } from '@modelcontextprotocol/core';
254+
import { fromJsonSchema, AjvJsonSchemaValidator } from '@modelcontextprotocol/server';
256255
server.registerTool('greet', {
257256
inputSchema: fromJsonSchema({ type: 'object', properties: { name: { type: 'string' } } }, new AjvJsonSchemaValidator())
258257
}, handler);
@@ -434,6 +433,22 @@ const client = new Client(
434433
);
435434
```
436435

436+
### `InMemoryTransport` removed from public API
437+
438+
`InMemoryTransport` has been removed from the public API surface. It was previously used for in-process client-server connections and testing.
439+
440+
For **testing**, import it directly from the internal core package:
441+
442+
```typescript
443+
// v1
444+
import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
445+
446+
// v2 (testing only — @modelcontextprotocol/core is internal, not for production use)
447+
import { InMemoryTransport } from '@modelcontextprotocol/core';
448+
```
449+
450+
For **production in-process connections**, use `StreamableHTTPClientTransport` with a local server URL, or connect client and server via paired streams.
451+
437452
### Removed type aliases and deprecated exports
438453

439454
The following deprecated type aliases have been removed from `@modelcontextprotocol/core`:
@@ -447,9 +462,9 @@ The following deprecated type aliases have been removed from `@modelcontextproto
447462
| `ResourceReferenceSchema` | `ResourceTemplateReferenceSchema` |
448463
| `ResourceReference` | `ResourceTemplateReference` |
449464
| `IsomorphicHeaders` | Use Web Standard `Headers` |
450-
| `AuthInfo` (from `server/auth/types.js`) | `AuthInfo` (now in `@modelcontextprotocol/core`) |
465+
| `AuthInfo` (from `server/auth/types.js`) | `AuthInfo` (now re-exported by `@modelcontextprotocol/client` and `@modelcontextprotocol/server`) |
451466

452-
All other types and schemas exported from `@modelcontextprotocol/sdk/types.js` retain their original names in `@modelcontextprotocol/core`.
467+
All other types and schemas exported from `@modelcontextprotocol/sdk/types.js` retain their original names — import them from `@modelcontextprotocol/client` or `@modelcontextprotocol/server`.
453468

454469
**Before (v1):**
455470

@@ -460,7 +475,7 @@ import { JSONRPCError, ResourceReference, isJSONRPCError } from '@modelcontextpr
460475
**After (v2):**
461476

462477
```typescript
463-
import { JSONRPCErrorResponse, ResourceTemplateReference, isJSONRPCErrorResponse } from '@modelcontextprotocol/core';
478+
import { JSONRPCErrorResponse, ResourceTemplateReference, isJSONRPCErrorResponse } from '@modelcontextprotocol/server';
464479
```
465480

466481
### Request handler context types
@@ -576,7 +591,7 @@ try {
576591
**After (v2):**
577592

578593
```typescript
579-
import { ProtocolError, ProtocolErrorCode, SdkError, SdkErrorCode } from '@modelcontextprotocol/core';
594+
import { ProtocolError, ProtocolErrorCode, SdkError, SdkErrorCode } from '@modelcontextprotocol/client';
580595

581596
try {
582597
await client.callTool({ name: 'test', arguments: {} });
@@ -633,7 +648,7 @@ try {
633648
**After (v2):**
634649

635650
```typescript
636-
import { SdkError, SdkErrorCode } from '@modelcontextprotocol/core';
651+
import { SdkError, SdkErrorCode } from '@modelcontextprotocol/client';
637652

638653
try {
639654
await transport.send(message);
@@ -703,7 +718,7 @@ The `OAUTH_ERRORS` constant has also been removed.
703718
**Before (v1):**
704719

705720
```typescript
706-
import { InvalidClientError, InvalidGrantError, ServerError } from '@modelcontextprotocol/core';
721+
import { InvalidClientError, InvalidGrantError, ServerError } from '@modelcontextprotocol/client';
707722

708723
try {
709724
await refreshToken();
@@ -721,7 +736,7 @@ try {
721736
**After (v2):**
722737

723738
```typescript
724-
import { OAuthError, OAuthErrorCode } from '@modelcontextprotocol/core';
739+
import { OAuthError, OAuthErrorCode } from '@modelcontextprotocol/client';
725740

726741
try {
727742
await refreshToken();

‎examples/client-quickstart/tsconfig.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,9 @@
1515
"@modelcontextprotocol/client/_shims": ["./node_modules/@modelcontextprotocol/client/src/shimsNode.ts"],
1616
"@modelcontextprotocol/core": [
1717
"./node_modules/@modelcontextprotocol/client/node_modules/@modelcontextprotocol/core/src/index.ts"
18+
],
19+
"@modelcontextprotocol/core/public": [
20+
"./node_modules/@modelcontextprotocol/client/node_modules/@modelcontextprotocol/core/src/exports/public/index.ts"
1821
]
1922
}
2023
},

‎examples/client/tsconfig.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,9 @@
1010
"@modelcontextprotocol/core": [
1111
"./node_modules/@modelcontextprotocol/client/node_modules/@modelcontextprotocol/core/src/index.ts"
1212
],
13+
"@modelcontextprotocol/core/public": [
14+
"./node_modules/@modelcontextprotocol/client/node_modules/@modelcontextprotocol/core/src/exports/public/index.ts"
15+
],
1316
"@modelcontextprotocol/eslint-config": ["./node_modules/@modelcontextprotocol/eslint-config/tsconfig.json"],
1417
"@modelcontextprotocol/vitest-config": ["./node_modules/@modelcontextprotocol/vitest-config/tsconfig.json"],
1518
"@modelcontextprotocol/examples-shared": ["./node_modules/@modelcontextprotocol/examples-shared/src/index.ts"]

‎examples/server-quickstart/tsconfig.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,9 @@
1414
"@modelcontextprotocol/server/_shims": ["./node_modules/@modelcontextprotocol/server/src/shimsNode.ts"],
1515
"@modelcontextprotocol/core": [
1616
"./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core/src/index.ts"
17+
],
18+
"@modelcontextprotocol/core/public": [
19+
"./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core/src/exports/public/index.ts"
1720
]
1821
}
1922
},

‎examples/server/tsconfig.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,9 @@
1313
"@modelcontextprotocol/core": [
1414
"./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core/src/index.ts"
1515
],
16+
"@modelcontextprotocol/core/public": [
17+
"./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core/src/exports/public/index.ts"
18+
],
1619
"@modelcontextprotocol/examples-shared": ["./node_modules/@modelcontextprotocol/examples-shared/src/index.ts"],
1720
"@modelcontextprotocol/eslint-config": ["./node_modules/@modelcontextprotocol/eslint-config/tsconfig.json"],
1821
"@modelcontextprotocol/vitest-config": ["./node_modules/@modelcontextprotocol/vitest-config/tsconfig.json"]

‎examples/shared/tsconfig.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,9 @@
1212
"@modelcontextprotocol/core": [
1313
"./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core/src/index.ts"
1414
],
15+
"@modelcontextprotocol/core/public": [
16+
"./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core/src/exports/public/index.ts"
17+
],
1518
"@modelcontextprotocol/eslint-config": ["./node_modules/@modelcontextprotocol/eslint-config/tsconfig.json"],
1619
"@modelcontextprotocol/vitest-config": ["./node_modules/@modelcontextprotocol/vitest-config/tsconfig.json"],
1720
"@modelcontextprotocol/test-helpers": ["./node_modules/@modelcontextprotocol/test-helpers/src/index.ts"],

‎packages/client/src/index.ts‎

Lines changed: 70 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,73 @@
1-
export * from './client/auth.js';
2-
export * from './client/authExtensions.js';
3-
export * from './client/client.js';
4-
export * from './client/crossAppAccess.js';
5-
export * from './client/middleware.js';
6-
export * from './client/sse.js';
7-
export * from './client/stdio.js';
8-
export * from './client/streamableHttp.js';
9-
export * from './client/websocket.js';
1+
// Public API for @modelcontextprotocol/client.
2+
//
3+
// This file defines the complete public surface. It consists of:
4+
// - Package-specific exports: listed explicitly below (named imports)
5+
// - Protocol-level types: re-exported from @modelcontextprotocol/core/public
6+
//
7+
// Any new export added here becomes public API. Use named exports, not wildcards.
8+
9+
export type {
10+
AddClientAuthentication,
11+
AuthProvider,
12+
AuthResult,
13+
ClientAuthMethod,
14+
OAuthClientProvider,
15+
OAuthDiscoveryState,
16+
OAuthServerInfo
17+
} from './client/auth.js';
18+
export {
19+
auth,
20+
buildDiscoveryUrls,
21+
discoverAuthorizationServerMetadata,
22+
discoverOAuthMetadata,
23+
discoverOAuthProtectedResourceMetadata,
24+
discoverOAuthServerInfo,
25+
exchangeAuthorization,
26+
extractResourceMetadataUrl,
27+
extractWWWAuthenticateParams,
28+
fetchToken,
29+
isHttpsUrl,
30+
parseErrorResponse,
31+
prepareAuthorizationCodeRequest,
32+
refreshAuthorization,
33+
registerClient,
34+
selectClientAuthMethod,
35+
selectResourceURL,
36+
startAuthorization,
37+
UnauthorizedError
38+
} from './client/auth.js';
39+
export type {
40+
AssertionCallback,
41+
ClientCredentialsProviderOptions,
42+
CrossAppAccessContext,
43+
CrossAppAccessProviderOptions,
44+
PrivateKeyJwtProviderOptions,
45+
StaticPrivateKeyJwtProviderOptions
46+
} from './client/authExtensions.js';
47+
export {
48+
ClientCredentialsProvider,
49+
createPrivateKeyJwtAuth,
50+
CrossAppAccessProvider,
51+
PrivateKeyJwtProvider,
52+
StaticPrivateKeyJwtProvider
53+
} from './client/authExtensions.js';
54+
export type { ClientOptions } from './client/client.js';
55+
export { Client } from './client/client.js';
56+
export { getSupportedElicitationModes } from './client/client.js';
57+
export type { DiscoverAndRequestJwtAuthGrantOptions, JwtAuthGrantResult, RequestJwtAuthGrantOptions } from './client/crossAppAccess.js';
58+
export { discoverAndRequestJwtAuthGrant, exchangeJwtAuthGrant, requestJwtAuthorizationGrant } from './client/crossAppAccess.js';
59+
export type { LoggingOptions, Middleware, RequestLogger } from './client/middleware.js';
60+
export { applyMiddlewares, createMiddleware, withLogging, withOAuth } from './client/middleware.js';
61+
export type { SSEClientTransportOptions } from './client/sse.js';
62+
export { SSEClientTransport, SseError } from './client/sse.js';
63+
export type { StdioServerParameters } from './client/stdio.js';
64+
export { DEFAULT_INHERITED_ENV_VARS, getDefaultEnvironment, StdioClientTransport } from './client/stdio.js';
65+
export type { StartSSEOptions, StreamableHTTPClientTransportOptions, StreamableHTTPReconnectionOptions } from './client/streamableHttp.js';
66+
export { StreamableHTTPClientTransport } from './client/streamableHttp.js';
67+
export { WebSocketClientTransport } from './client/websocket.js';
1068

1169
// experimental exports
12-
export * from './experimental/index.js';
70+
export { ExperimentalClientTasks } from './experimental/tasks/client.js';
1371

14-
// re-export shared types
15-
export * from '@modelcontextprotocol/core';
72+
// re-export curated public API from core
73+
export * from '@modelcontextprotocol/core/public';

‎packages/client/tsconfig.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
"paths": {
77
"*": ["./*"],
88
"@modelcontextprotocol/core": ["./node_modules/@modelcontextprotocol/core/src/index.ts"],
9+
"@modelcontextprotocol/core/public": ["./node_modules/@modelcontextprotocol/core/src/exports/public/index.ts"],
910
"@modelcontextprotocol/test-helpers": ["./node_modules/@modelcontextprotocol/test-helpers/src/index.ts"],
1011
"@modelcontextprotocol/client/_shims": ["./src/shimsNode.ts"]
1112
}

0 commit comments

Comments
 (0)