Skip to content

Commit 07c5491

Browse files
felixweinbergerfelixweinberger
committed
docs: minimize migration doc diff to custom-methods sections only
1 parent 4a2bf03 commit 07c5491

File tree

2 files changed

+59
-60
lines changed

2 files changed

+59
-60
lines changed

‎docs/migration-SKILL.md‎

Lines changed: 41 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -36,13 +36,13 @@ Replace all `@modelcontextprotocol/sdk/...` imports using this table.
3636

3737
### Client imports
3838

39-
| v1 import path | v2 package |
40-
| ---------------------------------------------------- | ------------------------------------------------------------------------------ |
41-
| `@modelcontextprotocol/sdk/client/index.js` | `@modelcontextprotocol/client` |
42-
| `@modelcontextprotocol/sdk/client/auth.js` | `@modelcontextprotocol/client` |
43-
| `@modelcontextprotocol/sdk/client/streamableHttp.js` | `@modelcontextprotocol/client` |
44-
| `@modelcontextprotocol/sdk/client/sse.js` | `@modelcontextprotocol/client` |
45-
| `@modelcontextprotocol/sdk/client/stdio.js` | `@modelcontextprotocol/client` |
39+
| v1 import path | v2 package |
40+
| ---------------------------------------------------- | ------------------------------ |
41+
| `@modelcontextprotocol/sdk/client/index.js` | `@modelcontextprotocol/client` |
42+
| `@modelcontextprotocol/sdk/client/auth.js` | `@modelcontextprotocol/client` |
43+
| `@modelcontextprotocol/sdk/client/streamableHttp.js` | `@modelcontextprotocol/client` |
44+
| `@modelcontextprotocol/sdk/client/sse.js` | `@modelcontextprotocol/client` |
45+
| `@modelcontextprotocol/sdk/client/stdio.js` | `@modelcontextprotocol/client` |
4646
| `@modelcontextprotocol/sdk/client/websocket.js` | REMOVED (use Streamable HTTP or stdio; implement `Transport` for custom needs) |
4747

4848
### Server imports
@@ -59,8 +59,8 @@ Replace all `@modelcontextprotocol/sdk/...` imports using this table.
5959

6060
### Types / shared imports
6161

62-
| v1 import path | v2 package |
63-
| ------------------------------------------------- | ---------------------------------------------------------------- |
62+
| v1 import path | v2 package |
63+
| ------------------------------------------------- | ---------------------------- |
6464
| `@modelcontextprotocol/sdk/types.js` | `@modelcontextprotocol/client` or `@modelcontextprotocol/server` |
6565
| `@modelcontextprotocol/sdk/shared/protocol.js` | `@modelcontextprotocol/client` or `@modelcontextprotocol/server` |
6666
| `@modelcontextprotocol/sdk/shared/transport.js` | `@modelcontextprotocol/client` or `@modelcontextprotocol/server` |
@@ -81,22 +81,22 @@ Notes:
8181

8282
## 5. Removed / Renamed Type Aliases and Symbols
8383

84-
| v1 (removed) | v2 (replacement) |
85-
| ---------------------------------------- | ------------------------------------------------------------------------------------------------- |
86-
| `JSONRPCError` | `JSONRPCErrorResponse` |
87-
| `JSONRPCErrorSchema` | `JSONRPCErrorResponseSchema` |
88-
| `isJSONRPCError` | `isJSONRPCErrorResponse` |
89-
| `isJSONRPCResponse` | `isJSONRPCResultResponse` |
90-
| `ResourceReference` | `ResourceTemplateReference` |
91-
| `ResourceReferenceSchema` | `ResourceTemplateReferenceSchema` |
92-
| `IsomorphicHeaders` | REMOVED (use Web Standard `Headers`) |
84+
| v1 (removed) | v2 (replacement) |
85+
| ---------------------------------------- | -------------------------------------------------------- |
86+
| `JSONRPCError` | `JSONRPCErrorResponse` |
87+
| `JSONRPCErrorSchema` | `JSONRPCErrorResponseSchema` |
88+
| `isJSONRPCError` | `isJSONRPCErrorResponse` |
89+
| `isJSONRPCResponse` | `isJSONRPCResultResponse` |
90+
| `ResourceReference` | `ResourceTemplateReference` |
91+
| `ResourceReferenceSchema` | `ResourceTemplateReferenceSchema` |
92+
| `IsomorphicHeaders` | REMOVED (use Web Standard `Headers`) |
9393
| `AuthInfo` (from `server/auth/types.js`) | `AuthInfo` (now re-exported by `@modelcontextprotocol/client` and `@modelcontextprotocol/server`) |
94-
| `McpError` | `ProtocolError` |
95-
| `ErrorCode` | `ProtocolErrorCode` |
96-
| `ErrorCode.RequestTimeout` | `SdkErrorCode.RequestTimeout` |
97-
| `ErrorCode.ConnectionClosed` | `SdkErrorCode.ConnectionClosed` |
98-
| `StreamableHTTPError` | REMOVED (use `SdkError` with `SdkErrorCode.ClientHttp*`) |
99-
| `WebSocketClientTransport` | REMOVED (use `StreamableHTTPClientTransport` or `StdioClientTransport`) |
94+
| `McpError` | `ProtocolError` |
95+
| `ErrorCode` | `ProtocolErrorCode` |
96+
| `ErrorCode.RequestTimeout` | `SdkErrorCode.RequestTimeout` |
97+
| `ErrorCode.ConnectionClosed` | `SdkErrorCode.ConnectionClosed` |
98+
| `StreamableHTTPError` | REMOVED (use `SdkError` with `SdkErrorCode.ClientHttp*`) |
99+
| `WebSocketClientTransport` | REMOVED (use `StreamableHTTPClientTransport` or `StdioClientTransport`) |
100100

101101
All other symbols from `@modelcontextprotocol/sdk/types.js` retain their original names (e.g., `CallToolResultSchema`, `ListToolsResultSchema`, etc.).
102102

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

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

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
214-
`fromJsonSchema(schema)` from `@modelcontextprotocol/server` (validator defaults automatically; pass an explicit validator for custom configurations). Applies to `inputSchema`, `outputSchema`, and `argsSchema`.
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)` from `@modelcontextprotocol/server` (validator defaults automatically; pass an explicit validator for custom configurations). Applies to `inputSchema`, `outputSchema`, and `argsSchema`.
215214

216215
### Tools
217216

@@ -281,20 +280,20 @@ Note: the third argument (`metadata`) is required — pass `{}` if no metadata.
281280

282281
### Schema Migration Quick Reference
283282

284-
| v1 (raw shape) | v2 (Standard Schema object) |
285-
| ---------------------------------- | -------------------------------------------- |
286-
| `{ name: z.string() }` | `z.object({ name: z.string() })` |
283+
| v1 (raw shape) | v2 (Standard Schema object) |
284+
|----------------|-----------------|
285+
| `{ name: z.string() }` | `z.object({ name: z.string() })` |
287286
| `{ count: z.number().optional() }` | `z.object({ count: z.number().optional() })` |
288287
| `{}` (empty) | `z.object({})` |
289288
| `undefined` (no schema) | `undefined` or omit the field |
290289

291290
### Removed core exports
292291

293-
| Removed from `@modelcontextprotocol/core` | Replacement |
294-
| ------------------------------------------------------------------------------------ | ----------------------------------------- |
295-
| `schemaToJson(schema)` | `standardSchemaToJsonSchema(schema)` |
296-
| `parseSchemaAsync(schema, data)` | `validateStandardSchema(schema, data)` |
297-
| `SchemaInput<T>` | `StandardSchemaWithJSON.InferInput<T>` |
292+
| Removed from `@modelcontextprotocol/core` | Replacement |
293+
|---|---|
294+
| `schemaToJson(schema)` | `standardSchemaToJsonSchema(schema)` |
295+
| `parseSchemaAsync(schema, data)` | `validateStandardSchema(schema, data)` |
296+
| `SchemaInput<T>` | `StandardSchemaWithJSON.InferInput<T>` |
298297
| `getSchemaShape`, `getSchemaDescription`, `isOptionalSchema`, `unwrapOptionalSchema` | none (internal Zod introspection helpers) |
299298

300299
## 7. Headers API
@@ -390,6 +389,7 @@ Request/notification params remain fully typed. Remove unused schema imports aft
390389

391390
The v1 schema's `.shape.params` becomes the `ParamsSchema` argument; the `method: z.literal('...')` value becomes the string argument.
392391

392+
393393
## 10. Request Handler Context Types
394394

395395
`RequestHandlerExtra` → structured context types with nested groups. Rename `extra` → `ctx` in all handler callbacks.
@@ -452,18 +452,18 @@ Remove unused schema imports: `CallToolResultSchema`, `CompatibilityCallToolResu
452452

453453
`TaskCreationParams.ttl` changed from `z.union([z.number(), z.null()]).optional()` to `z.number().optional()`. Per the MCP spec, `null` TTL (unlimited lifetime) is only valid in server responses (`Task.ttl`), not in client requests. Omit `ttl` to let the server decide.
454454

455-
| v1 | v2 |
456-
| ---------------------- | ---------------------------------- |
457-
| `task: { ttl: null }` | `task: {}` (omit ttl) |
455+
| v1 | v2 |
456+
|---|---|
457+
| `task: { ttl: null }` | `task: {}` (omit ttl) |
458458
| `task: { ttl: 60000 }` | `task: { ttl: 60000 }` (unchanged) |
459459

460460
Type changes in handler context:
461461

462-
| Type | v1 | v2 |
463-
| ------------------------------------------- | ----------------------------- | --------------------- |
464-
| `TaskContext.requestedTtl` | `number \| null \| undefined` | `number \| undefined` |
462+
| Type | v1 | v2 |
463+
|---|---|---|
464+
| `TaskContext.requestedTtl` | `number \| null \| undefined` | `number \| undefined` |
465465
| `CreateTaskServerContext.task.requestedTtl` | `number \| null \| undefined` | `number \| undefined` |
466-
| `TaskServerContext.task.requestedTtl` | `number \| null \| undefined` | `number \| undefined` |
466+
| `TaskServerContext.task.requestedTtl` | `number \| null \| undefined` | `number \| undefined` |
467467

468468
> These task APIs are `@experimental` and may change without notice.
469469

‎docs/migration.md‎

Lines changed: 18 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -57,8 +57,7 @@ import { McpServer, StdioServerTransport, WebStandardStreamableHTTPServerTranspo
5757
import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
5858
```
5959

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
61-
— it is an internal package.
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

@@ -295,11 +294,11 @@ This applies to:
295294

296295
**Removed Zod-specific helpers** from `@modelcontextprotocol/core` (use Standard Schema equivalents):
297296

298-
| Removed | Replacement |
299-
| ------------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
300-
| `schemaToJson(schema)` | `standardSchemaToJsonSchema(schema)` |
301-
| `parseSchemaAsync(schema, data)` | `validateStandardSchema(schema, data)` |
302-
| `SchemaInput<T>` | `StandardSchemaWithJSON.InferInput<T>` |
297+
| Removed | Replacement |
298+
|---|---|
299+
| `schemaToJson(schema)` | `standardSchemaToJsonSchema(schema)` |
300+
| `parseSchemaAsync(schema, data)` | `validateStandardSchema(schema, data)` |
301+
| `SchemaInput<T>` | `StandardSchemaWithJSON.InferInput<T>` |
303302
| `getSchemaShape`, `getSchemaDescription`, `isOptionalSchema`, `unwrapOptionalSchema` | No replacement — these are now internal Zod introspection helpers |
304303

305304
### Host header validation moved
@@ -436,6 +435,7 @@ before sending and gives typed `params`; passing a bare result schema sends para
436435
For larger sub-protocols where neither side is semantically an MCP client or server, prefer composition: hold a `Client` (or `Server`) instance, register custom handlers on it, and expose typed facade methods. See `examples/server/src/customMethodExtAppsExample.ts` for a worked
437436
example.
438437

438+
439439
### `Protocol.request()`, `ctx.mcpReq.send()`, and `Client.callTool()` no longer take a schema parameter
440440

441441
The public `Protocol.request()`, `BaseContext.mcpReq.send()`, and `Client.callTool()` methods no longer accept a Zod result schema argument. The SDK now resolves the correct result schema internally based on the method name. This means you no longer need to import result schemas
@@ -531,15 +531,15 @@ For **production in-process connections**, use `StreamableHTTPClientTransport` w
531531

532532
The following deprecated type aliases have been removed from `@modelcontextprotocol/core`:
533533

534-
| Removed | Replacement |
535-
| ---------------------------------------- | ------------------------------------------------------------------------------------------------- |
536-
| `JSONRPCError` | `JSONRPCErrorResponse` |
537-
| `JSONRPCErrorSchema` | `JSONRPCErrorResponseSchema` |
538-
| `isJSONRPCError` | `isJSONRPCErrorResponse` |
539-
| `isJSONRPCResponse` | `isJSONRPCResultResponse` |
540-
| `ResourceReferenceSchema` | `ResourceTemplateReferenceSchema` |
541-
| `ResourceReference` | `ResourceTemplateReference` |
542-
| `IsomorphicHeaders` | Use Web Standard `Headers` |
534+
| Removed | Replacement |
535+
| ---------------------------------------- | ------------------------------------------------ |
536+
| `JSONRPCError` | `JSONRPCErrorResponse` |
537+
| `JSONRPCErrorSchema` | `JSONRPCErrorResponseSchema` |
538+
| `isJSONRPCError` | `isJSONRPCErrorResponse` |
539+
| `isJSONRPCResponse` | `isJSONRPCResultResponse` |
540+
| `ResourceReferenceSchema` | `ResourceTemplateReferenceSchema` |
541+
| `ResourceReference` | `ResourceTemplateReference` |
542+
| `IsomorphicHeaders` | Use Web Standard `Headers` |
543543
| `AuthInfo` (from `server/auth/types.js`) | `AuthInfo` (now re-exported by `@modelcontextprotocol/client` and `@modelcontextprotocol/server`) |
544544

545545
All other types and schemas exported from `@modelcontextprotocol/sdk/types.js` retain their original names — import them from `@modelcontextprotocol/client` or `@modelcontextprotocol/server`.
@@ -570,7 +570,7 @@ The `RequestHandlerExtra` type has been replaced with a structured context type
570570
| `extra.sendRequest(...)` | `ctx.mcpReq.send(...)` |
571571
| `extra.sendNotification(...)` | `ctx.mcpReq.notify(...)` |
572572
| `extra.authInfo` | `ctx.http?.authInfo` |
573-
| `extra.requestInfo` | `ctx.http?.req` (standard Web `Request`, only on `ServerContext`) |
573+
| `extra.requestInfo` | `ctx.http?.req` (standard Web `Request`, only on `ServerContext`) |
574574
| `extra.closeSSEStream` | `ctx.http?.closeSSE` (only on `ServerContext`) |
575575
| `extra.closeStandaloneSSEStream` | `ctx.http?.closeStandaloneSSE` (only on `ServerContext`) |
576576
| `extra.sessionId` | `ctx.sessionId` |
@@ -837,8 +837,7 @@ try {
837837

838838
### Experimental: `TaskCreationParams.ttl` no longer accepts `null`
839839

840-
The `ttl` field in `TaskCreationParams` (used when requesting the server to create a task) no longer accepts `null`. Per the MCP spec, `null` TTL (meaning unlimited lifetime) is only valid in server responses (`Task.ttl`), not in client requests. Clients should omit `ttl` to let
841-
the server decide the lifetime.
840+
The `ttl` field in `TaskCreationParams` (used when requesting the server to create a task) no longer accepts `null`. Per the MCP spec, `null` TTL (meaning unlimited lifetime) is only valid in server responses (`Task.ttl`), not in client requests. Clients should omit `ttl` to let the server decide the lifetime.
842841

843842
This also narrows the type of `requestedTtl` in `TaskContext`, `CreateTaskServerContext`, and `TaskServerContext` from `number | null | undefined` to `number | undefined`.
844843

0 commit comments

Comments
 (0)