feat(core): custom-method overloads on setRequestHandler/setNotificationHandler; method-keyed request() return; deprecated v1 schema-arg overloads; ProtocolSpec generic

Author: felixweinberger

docs/migration-SKILL.md

@@ -377,16 +377,18 @@ Schema to method string mapping:
 
 Request/notification params remain fully typed. Remove unused schema imports after migration.
 
-**Custom (non-standard) methods** — vendor extensions or sub-protocols whose method strings are not in the MCP spec — use the three-arg overloads of `setRequestHandler`/`setNotificationHandler`/`request`/`notification`, which accept any method string with a caller-supplied params/result schema. `Protocol` is now concrete and exported, so MCP-dialect protocols can subclass it directly:
+**Custom (non-standard) methods** — vendor extensions or sub-protocols whose method strings are not in the MCP spec — use the three-arg overloads of `setRequestHandler`/`setNotificationHandler`/`request`. `Protocol` is now concrete and exported, so MCP-dialect protocols can subclass it directly:
 
 | v1                                                           | v2                                                                             |
 | ------------------------------------------------------------ | ------------------------------------------------------------------------------ |
 | `setRequestHandler(CustomReqSchema, (req, extra) => ...)`    | `setRequestHandler('vendor/method', ParamsSchema, (params, ctx) => ...)` |
 | `setNotificationHandler(CustomNotifSchema, n => ...)`        | `setNotificationHandler('vendor/method', ParamsSchema, params => ...)`   |
 | `this.request({ method: 'vendor/x', params }, ResultSchema)` | `this.request('vendor/x', params, ResultSchema)`                     |
-| `this.notification({ method: 'vendor/x', params })`          | `this.notification('vendor/x', params)`                              |
+| `this.notification({ method: 'vendor/x', params })`          | unchanged                                                                      |
 | `class X extends Protocol<Req, Notif, Res>`                  | `class X extends Client` (or `Server`), or compose a `Client` instance         |
 
+`notification()` keeps a single object-form signature so tests can replace it with a mock without TS overload-intersection errors. To send a custom notification, use `notification({ method: 'vendor/x', params })` (unchanged from v1).
+
 The v1 schema's `.shape.params` becomes the `ParamsSchema` argument; the `method: z.literal('...')` value becomes the string argument.
 
 

examples/client/src/customMethodExample.ts

@@ -1,47 +1,35 @@
 #!/usr/bin/env node
 /**
- * Demonstrates calling a vendor method via the three-arg `client.request(method, params, resultSchema)`
- * overload and registering a vendor notification handler with the three-arg `setNotificationHandler`
- * overload.
+ * Calling vendor-specific (non-spec) JSON-RPC methods from a `Client`.
  *
- * Pair with: examples/server/src/customMethodExample.ts (which contains the in-memory pair).
+ * - Send a custom request: 3-arg `client.request(method, params, resultSchema)`
+ * - Send a custom notification: `client.notification({ method, params })` (unchanged from v1)
+ * - Receive a custom notification: 3-arg `client.setNotificationHandler(method, paramsSchema, handler)`
+ *
+ * These overloads are on `Client` and `Server` directly — you do NOT need a raw
+ * `Protocol` instance for custom methods.
+ *
+ * Pair with the server in examples/server/src/customMethodExample.ts.
  */
 
-import { Client, InMemoryTransport, Protocol } from '@modelcontextprotocol/client';
+import { Client, StdioClientTransport } from '@modelcontextprotocol/client';
 import { z } from 'zod';
 
-const SearchParams = z.object({ query: z.string() });
 const SearchResult = z.object({ hits: z.array(z.string()) });
 const ProgressParams = z.object({ stage: z.string(), pct: z.number() });
 
-async function main() {
-    const peer = new Protocol();
-    peer.setRequestHandler('acme/search', SearchParams, async p => {
-        await peer.notification('acme/searchProgress', { stage: 'started', pct: 0 });
-        await peer.notification('acme/searchProgress', { stage: 'done', pct: 100 });
-        return { hits: [p.query, p.query + '-2'] };
-    });
-    // The bare Protocol must respond to MCP initialize so Client.connect() completes.
-    peer.setRequestHandler('initialize', req => ({
-        protocolVersion: req.params.protocolVersion,
-        capabilities: {},
-        serverInfo: { name: 'peer', version: '1.0.0' }
-    }));
-
-    const client = new Client({ name: 'c', version: '1.0.0' }, { capabilities: {} });
-    client.setNotificationHandler('acme/searchProgress', ProgressParams, p => {
-        console.log(`[client] progress: ${p.stage} ${p.pct}%`);
-    });
-
-    const [t1, t2] = InMemoryTransport.createLinkedPair();
-    await peer.connect(t2);
-    await client.connect(t1);
-
-    const r = await client.request('acme/search', { query: 'widgets' }, SearchResult);
-    console.log('[client] hits=' + JSON.stringify(r.hits));
-
-    await client.close();
-    await peer.close();
-}
-
-await main();
+const client = new Client({ name: 'custom-method-client', version: '1.0.0' }, { capabilities: {} });
+
+client.setNotificationHandler('acme/searchProgress', ProgressParams, p => {
+    console.log(`[client] progress: ${p.stage} ${p.pct}%`);
+});
+
+await client.connect(new StdioClientTransport({ command: 'node', args: ['../server/dist/customMethodExample.js'] }));
+
+const r = await client.request('acme/search', { query: 'widgets' }, SearchResult);
+console.log('[client] hits=' + JSON.stringify(r.hits));
+
+await client.notification({ method: 'acme/tick', params: { n: 1 } });
+await client.notification({ method: 'acme/tick', params: { n: 2 } });
+
+await client.close();

examples/server/src/customMethodExample.ts

@@ -1,47 +1,33 @@
 #!/usr/bin/env node
 /**
- * Demonstrates registering vendor-specific JSON-RPC methods directly on a stock `Server`, and
- * calling them from a bare `Protocol` peer (which is role-agnostic and so can act as the client
- * side without depending on the client package).
+ * Registering vendor-specific (non-spec) JSON-RPC methods on a `Server`.
+ *
+ * Custom methods use the 3-arg form of `setRequestHandler` / `setNotificationHandler`:
+ * pass the method string, a params schema, and the handler. The same overload is
+ * available on `Client` (for server→client custom methods) — you do NOT need a raw
+ * `Protocol` instance for this.
+ *
+ * To call these from the client side, use:
+ *   await client.request('acme/search', { query: 'widgets' }, SearchResult)
+ *   await client.notification({ method: 'acme/tick', params: { n: 1 } })
+ * See examples/client/src/customMethodExample.ts.
  */
 
-import { InMemoryTransport, Protocol, Server } from '@modelcontextprotocol/server';
+import { Server, StdioServerTransport } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 
 const SearchParams = z.object({ query: z.string() });
-const SearchResult = z.object({ hits: z.array(z.string()) });
 const TickParams = z.object({ n: z.number() });
 
-async function main() {
-    const server = new Server({ name: 'custom-method-server', version: '1.0.0' }, { capabilities: {} });
+const server = new Server({ name: 'custom-method-server', version: '1.0.0' }, { capabilities: {} });
 
-    server.setRequestHandler('acme/search', SearchParams, params => {
-        console.log('[server] acme/search query=' + params.query);
-        return { hits: [params.query, params.query + '-result'] };
-    });
+server.setRequestHandler('acme/search', SearchParams, params => {
+    console.log('[server] acme/search query=' + params.query);
+    return { hits: [params.query, params.query + '-result'] };
+});
 
-    server.setNotificationHandler('acme/tick', TickParams, p => {
-        console.log('[server] acme/tick n=' + p.n);
-    });
+server.setNotificationHandler('acme/tick', TickParams, p => {
+    console.log('[server] acme/tick n=' + p.n);
+});
 
-    const peer = new Protocol();
-
-    const [peerTransport, serverTransport] = InMemoryTransport.createLinkedPair();
-    await server.connect(serverTransport);
-    await peer.connect(peerTransport);
-    await peer.request({
-        method: 'initialize',
-        params: { protocolVersion: '2025-11-25', clientInfo: { name: 'peer', version: '1.0.0' }, capabilities: {} }
-    });
-
-    const r = await peer.request('acme/search', { query: 'widgets' }, SearchResult);
-    console.log('[peer] hits=' + JSON.stringify(r.hits));
-
-    await peer.notification('acme/tick', { n: 1 });
-    await peer.notification('acme/tick', { n: 2 });
-
-    await peer.close();
-    await server.close();
-}
-
-await main();
+await server.connect(new StdioServerTransport());

examples/server/src/customMethodExtAppsExample.ts

@@ -71,11 +71,11 @@ class App extends Protocol<AppSpec> {
     }
 
     sendLog(level: string, data: unknown) {
-        return this.notification('notifications/message', { level, data });
+        return this.notification({ method: 'notifications/message', params: { level, data } });
     }
 
     notifySize(width: number, height: number) {
-        return this.notification('ui/size-changed', { width, height });
+        return this.notification({ method: 'ui/size-changed', params: { width, height } });
     }
 }
 
@@ -103,7 +103,7 @@ class Host extends Protocol<AppSpec> {
     }
 
     notifyToolResult(toolName: string, text: string) {
-        return this.notification('ui/tool-result', { toolName, text });
+        return this.notification({ method: 'ui/tool-result', params: { toolName, text } });
     }
 }
 

packages/client/src/client/client.ts

@@ -25,7 +25,6 @@ import type {
     MessageExtraInfo,
     NotificationMethod,
     ProtocolOptions,
-    ProtocolSpec,
     ReadResourceRequest,
     Request,
     RequestMethod,
@@ -210,7 +209,7 @@ export type ClientOptions = ProtocolOptions & {
  * The client will automatically begin the initialization flow with the server when {@linkcode connect} is called.
  *
  */
-export class Client extends Protocol<ProtocolSpec, ClientContext> {
+export class Client extends Protocol<ClientContext> {
     private _serverCapabilities?: ServerCapabilities;
     private _serverVersion?: Implementation;
     private _negotiatedProtocolVersion?: string;
@@ -613,7 +612,7 @@ export class Client extends Protocol<ProtocolSpec, ClientContext> {
         return this._instructions;
     }
 
-    protected override assertCapabilityForMethod(method: RequestMethod): void {
+    protected assertCapabilityForMethod(method: RequestMethod): void {
         switch (method as ClientRequest['method']) {
             case 'logging/setLevel': {
                 if (!this._serverCapabilities?.logging) {
@@ -676,7 +675,7 @@ export class Client extends Protocol<ProtocolSpec, ClientContext> {
         }
     }
 
-    protected override assertNotificationCapability(method: NotificationMethod): void {
+    protected assertNotificationCapability(method: NotificationMethod): void {
         switch (method as ClientNotification['method']) {
             case 'notifications/roots/list_changed': {
                 if (!this._capabilities.roots?.listChanged) {
@@ -705,7 +704,7 @@ export class Client extends Protocol<ProtocolSpec, ClientContext> {
         }
     }
 
-    protected override assertRequestHandlerCapability(method: string): void {
+    protected assertRequestHandlerCapability(method: string): void {
         switch (method) {
             case 'sampling/createMessage': {
                 if (!this._capabilities.sampling) {
@@ -744,11 +743,11 @@ export class Client extends Protocol<ProtocolSpec, ClientContext> {
         }
     }
 
-    protected override assertTaskCapability(method: string): void {
+    protected assertTaskCapability(method: string): void {
         assertToolsCallTaskCapability(this._serverCapabilities?.tasks?.requests, method, 'Server');
     }
 
-    protected override assertTaskHandlerCapability(method: string): void {
+    protected assertTaskHandlerCapability(method: string): void {
         assertClientRequestTaskCapability(this._capabilities?.tasks?.requests, method, 'Client');
     }
 

packages/core/src/exports/public/index.ts

@@ -38,9 +38,8 @@ export { checkResourceAllowed, resourceUrlFromServerUrl } from '../../shared/aut
 // Metadata utilities
 export { getDisplayName } from '../../shared/metadataUtils.js';
 
-// Role-agnostic Protocol class (concrete; Client/Server extend it). NOT mergeCapabilities.
+// Protocol-spec types for typed custom-method vocabularies. NOT the Protocol class itself or mergeCapabilities.
 export type { McpSpec, ProtocolSpec, SpecNotifications, SpecRequests } from '../../shared/protocol.js';
-export { Protocol } from '../../shared/protocol.js';
 export type { ZodLikeRequestSchema } from '../../util/compatSchema.js';
 export { InMemoryTransport } from '../../util/inMemory.js';
 export type { AnySchema, SchemaOutput } from '../../util/schema.js';

packages/core/src/index.ts

@@ -48,7 +48,7 @@ export * from './validators/fromJsonSchema.js';
  */
 
 // Core types only - implementations are exported via separate entry points
-export type { JsonSchemaType, JsonSchemaValidator, jsonSchemaValidator, JsonSchemaValidatorResult } from './validators/types.js';
-export { deprecate } from './util/deprecate.js';
 export type { ZodLikeRequestSchema } from './util/compatSchema.js';
 export { extractMethodLiteral, isZodLikeSchema } from './util/compatSchema.js';
+export { deprecate } from './util/deprecate.js';
+export type { JsonSchemaType, JsonSchemaValidator, jsonSchemaValidator, JsonSchemaValidatorResult } from './validators/types.js';