Skip to content

Commit d08eaca

Browse files
felixweinbergerfelixweinberger
committed
feat(core): route sendCustomNotification through notification(); add typed-params overloads; migration docs
- sendCustomNotification now delegates to notification() so debouncing and task-queued delivery apply to custom methods - sendCustomRequest/sendCustomNotification gain a {params, result}/{params} schema-bundle overload that validates outbound params before sending - clarify JSDoc: capability checks are a no-op for custom methods regardless of enforceStrictCapabilities - add migration.md / migration-SKILL.md sections for custom protocol methods
1 parent 1a0a5a1 commit d08eaca

File tree

4 files changed

+248
-69
lines changed

4 files changed

+248
-69
lines changed

‎docs/migration-SKILL.md‎

Lines changed: 53 additions & 40 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,7 +210,8 @@ 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 `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
214+
`fromJsonSchema(schema)` from `@modelcontextprotocol/server` (validator defaults automatically; pass an explicit validator for custom configurations). Applies to `inputSchema`, `outputSchema`, and `argsSchema`.
214215

215216
### Tools
216217

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

281282
### Schema Migration Quick Reference
282283

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

290291
### Removed core exports
291292

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>` |
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>` |
297298
| `getSchemaShape`, `getSchemaDescription`, `isOptionalSchema`, `unwrapOptionalSchema` | none (internal Zod introspection helpers) |
298299

299300
## 7. Headers API
@@ -380,6 +381,18 @@ Schema to method string mapping:
380381

381382
Request/notification params remain fully typed. Remove unused schema imports after migration.
382383

384+
**Custom (non-standard) methods** — vendor extensions or sub-protocols whose method strings are not in the MCP spec — are no longer accepted by `setRequestHandler`/`setNotificationHandler`. Use the `*Custom*` API instead:
385+
386+
| v1 | v2 |
387+
| ------------------------------------------------------------ | ------------------------------------------------------------------------------ |
388+
| `setRequestHandler(CustomReqSchema, (req, extra) => ...)` | `setCustomRequestHandler('vendor/method', ParamsSchema, (params, ctx) => ...)` |
389+
| `setNotificationHandler(CustomNotifSchema, n => ...)` | `setCustomNotificationHandler('vendor/method', ParamsSchema, params => ...)` |
390+
| `this.request({ method: 'vendor/x', params }, ResultSchema)` | `this.sendCustomRequest('vendor/x', params, ResultSchema)` |
391+
| `this.notification({ method: 'vendor/x', params })` | `this.sendCustomNotification('vendor/x', params)` |
392+
| `class X extends Protocol<Req, Notif, Res>` | `class X extends Client` (or `Server`), or compose a `Client` instance |
393+
394+
The v1 schema's `.shape.params` becomes the `ParamsSchema` argument; the `method: z.literal('...')` value becomes the string argument.
395+
383396
## 10. Request Handler Context Types
384397

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

444457
`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.
445458

446-
| v1 | v2 |
447-
|---|---|
448-
| `task: { ttl: null }` | `task: {}` (omit ttl) |
459+
| v1 | v2 |
460+
| ---------------------- | ---------------------------------- |
461+
| `task: { ttl: null }` | `task: {}` (omit ttl) |
449462
| `task: { ttl: 60000 }` | `task: { ttl: 60000 }` (unchanged) |
450463

451464
Type changes in handler context:
452465

453-
| Type | v1 | v2 |
454-
|---|---|---|
455-
| `TaskContext.requestedTtl` | `number \| null \| undefined` | `number \| undefined` |
466+
| Type | v1 | v2 |
467+
| ------------------------------------------- | ----------------------------- | --------------------- |
468+
| `TaskContext.requestedTtl` | `number \| null \| undefined` | `number \| undefined` |
456469
| `CreateTaskServerContext.task.requestedTtl` | `number \| null \| undefined` | `number \| undefined` |
457-
| `TaskServerContext.task.requestedTtl` | `number \| null \| undefined` | `number \| undefined` |
470+
| `TaskServerContext.task.requestedTtl` | `number \| null \| undefined` | `number \| undefined` |
458471

459472
> These task APIs are `@experimental` and may change without notice.
460473

0 commit comments

Comments
 (0)