Skip to content

Commit 176d3b5

Browse files
felixweinbergerfelixweinberger
committed
docs: add migration guidance for specTypeSchema()/isSpecType()
1 parent c604601 commit 176d3b5

File tree

2 files changed

+92
-70
lines changed

2 files changed

+92
-70
lines changed

‎docs/migration-SKILL.md‎

Lines changed: 54 additions & 47 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,24 +81,25 @@ 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` |
84+
| v1 (removed) | v2 (replacement) |
85+
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
86+
| `JSONRPCError` | `JSONRPCErrorResponse` |
87+
| `JSONRPCErrorSchema` | `JSONRPCErrorResponseSchema` |
88+
| `isJSONRPCError` | `isJSONRPCErrorResponse` |
8989
| `isJSONRPCResponse` (deprecated in v1) | `isJSONRPCResultResponse` (**not** v2's new `isJSONRPCResponse`, which correctly matches both result and error) |
90-
| `ResourceReference` | `ResourceTemplateReference` |
91-
| `ResourceReferenceSchema` | `ResourceTemplateReferenceSchema` |
92-
| `IsomorphicHeaders` | REMOVED (use Web Standard `Headers`) |
93-
| `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`) |
100-
101-
All other **type** symbols from `@modelcontextprotocol/sdk/types.js` retain their original names. **Zod schemas** (e.g., `CallToolResultSchema`, `ListToolsResultSchema`) are no longer part of the public API — they are internal to the SDK. For runtime validation, use type guard functions like `isCallToolResult` instead of `CallToolResultSchema.safeParse()`.
90+
| `ResourceReference` | `ResourceTemplateReference` |
91+
| `ResourceReferenceSchema` | `ResourceTemplateReferenceSchema` |
92+
| `IsomorphicHeaders` | REMOVED (use Web Standard `Headers`) |
93+
| `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`) |
100+
101+
All other **type** symbols from `@modelcontextprotocol/sdk/types.js` retain their original names. **Zod schemas** (e.g., `CallToolResultSchema`, `ListToolsResultSchema`) are no longer part of the public API — they are internal to the SDK. For runtime validation, use
102+
`isSpecType('TypeName', value)` (e.g., `isSpecType('CallToolResult', v)`) or `specTypeSchema('TypeName')` for the `StandardSchemaV1` validator object. The `'TypeName'` argument is typed as `SpecTypeName`, a literal union of all spec type names.
102103

103104
### Error class changes
104105

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

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

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

215217
### Tools
216218

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

281283
### Schema Migration Quick Reference
282284

283-
| v1 (raw shape) | v2 (Standard Schema object) |
284-
|----------------|-----------------|
285-
| `{ name: z.string() }` | `z.object({ name: z.string() })` |
285+
| v1 (raw shape) | v2 (Standard Schema object) |
286+
| ---------------------------------- | -------------------------------------------- |
287+
| `{ name: z.string() }` | `z.object({ name: z.string() })` |
286288
| `{ count: z.number().optional() }` | `z.object({ count: z.number().optional() })` |
287289
| `{}` (empty) | `z.object({})` |
288290
| `undefined` (no schema) | `undefined` or omit the field |
289291

290292
### Removed core exports
291293

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>` |
294+
| Removed from `@modelcontextprotocol/core` | Replacement |
295+
| ------------------------------------------------------------------------------------ | ----------------------------------------- |
296+
| `schemaToJson(schema)` | `standardSchemaToJsonSchema(schema)` |
297+
| `parseSchemaAsync(schema, data)` | `validateStandardSchema(schema, data)` |
298+
| `SchemaInput<T>` | `StandardSchemaWithJSON.InferInput<T>` |
297299
| `getSchemaShape`, `getSchemaDescription`, `isOptionalSchema`, `unwrapOptionalSchema` | none (internal Zod introspection helpers) |
298300

299301
## 7. Headers API
@@ -435,29 +437,33 @@ const tool = await client.callTool({ name: 'my-tool', arguments: {} });
435437

436438
Remove unused schema imports: `CallToolResultSchema`, `CompatibilityCallToolResultSchema`, `ElicitResultSchema`, `CreateMessageResultSchema`, etc., when they were only used in `request()`/`send()`/`callTool()` calls.
437439

438-
If `CallToolResultSchema` was used for **runtime validation** (not just as a `request()` argument), replace with the `isCallToolResult` type guard:
440+
If a `*Schema` constant was used for **runtime validation** (not just as a `request()` argument), replace with `isSpecType()` / `specTypeSchema()`:
439441

440-
| v1 pattern | v2 replacement |
441-
| --------------------------------------------------- | -------------------------- |
442-
| `CallToolResultSchema.safeParse(value).success` | `isCallToolResult(value)` |
443-
| `CallToolResultSchema.parse(value)` | Use `isCallToolResult(value)` then cast, or use `CallToolResult` type |
442+
| v1 pattern | v2 replacement |
443+
| -------------------------------------------------- | -------------------------------------------------------------- |
444+
| `CallToolResultSchema.safeParse(value).success` | `isSpecType('CallToolResult', value)` |
445+
| `<TypeName>Schema.safeParse(value).success` | `isSpecType('<TypeName>', value)` |
446+
| `<TypeName>Schema.parse(value)` | `specTypeSchema('<TypeName>')['~standard'].validate(value)` |
447+
| Passing `<TypeName>Schema` as a validator argument | `specTypeSchema('<TypeName>')` (returns `StandardSchemaV1<T>`) |
448+
449+
`isCallToolResult(value)` still works, but `isSpecType` covers every spec type by name.
444450

445451
## 12. Experimental: `TaskCreationParams.ttl` no longer accepts `null`
446452

447453
`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.
448454

449-
| v1 | v2 |
450-
|---|---|
451-
| `task: { ttl: null }` | `task: {}` (omit ttl) |
455+
| v1 | v2 |
456+
| ---------------------- | ---------------------------------- |
457+
| `task: { ttl: null }` | `task: {}` (omit ttl) |
452458
| `task: { ttl: 60000 }` | `task: { ttl: 60000 }` (unchanged) |
453459

454460
Type changes in handler context:
455461

456-
| Type | v1 | v2 |
457-
|---|---|---|
458-
| `TaskContext.requestedTtl` | `number \| null \| undefined` | `number \| undefined` |
462+
| Type | v1 | v2 |
463+
| ------------------------------------------- | ----------------------------- | --------------------- |
464+
| `TaskContext.requestedTtl` | `number \| null \| undefined` | `number \| undefined` |
459465
| `CreateTaskServerContext.task.requestedTtl` | `number \| null \| undefined` | `number \| undefined` |
460-
| `TaskServerContext.task.requestedTtl` | `number \| null \| undefined` | `number \| undefined` |
466+
| `TaskServerContext.task.requestedTtl` | `number \| null \| undefined` | `number \| undefined` |
461467

462468
> These task APIs are `@experimental` and may change without notice.
463469
@@ -488,6 +494,7 @@ new McpServer({ name: 'server', version: '1.0.0' }, {});
488494
```
489495

490496
Access validators explicitly:
497+
491498
- Runtime-aware default: `import { DefaultJsonSchemaValidator } from '@modelcontextprotocol/server/_shims';`
492499
- AJV (Node.js): `import { AjvJsonSchemaValidator } from '@modelcontextprotocol/server';`
493500
- CF Worker: `import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/server/validators/cf-worker';`

0 commit comments

Comments
 (0)