feat(compat): add deprecated schema-argument overloads to Protocol/Client (C3/C6 in core)

- setRequestHandler/setNotificationHandler: accept Zod schema (extracts method literal, warns once)
- request(): accept (req, ResultSchema, opts?) deprecated form (schema ignored)
- callTool(): accept (params, ResultSchema, opts?) deprecated form
- sendNotification(): non-overloaded alias for notification() (test-mock friendly)
- Export AnySchema/SchemaOutput/ZodLikeRequestSchema from core/public

Author: felixweinberger

packages/client/src/client/client.ts

@@ -3,6 +3,7 @@ import type {
     AnySchema,
     BaseContext,
     CallToolRequest,
+    CallToolResult,
     ClientCapabilities,
     ClientContext,
     ClientNotification,
@@ -38,7 +39,8 @@ import type {
     TaskManagerOptions,
     Tool,
     Transport,
-    UnsubscribeRequest
+    UnsubscribeRequest,
+    ZodLikeRequestSchema
 } from '@modelcontextprotocol/core';
 import {
     assertClientRequestTaskCapability,
@@ -49,12 +51,14 @@ import {
     CreateMessageResultSchema,
     CreateMessageResultWithToolsSchema,
     CreateTaskResultSchema,
+    deprecate,
     ElicitRequestSchema,
     ElicitResultSchema,
     EmptyResultSchema,
     extractTaskManagerOptions,
     GetPromptResultSchema,
     InitializeResultSchema,
+    isZodLikeSchema,
     LATEST_PROTOCOL_VERSION,
     ListChangedOptionsBaseSchema,
     ListPromptsResultSchema,
@@ -347,11 +351,19 @@ export class Client extends Protocol<ProtocolSpec, ClientContext> {
         paramsSchema: P,
         handler: (params: SchemaOutput<P>, ctx: ClientContext) => Result | Promise<Result>
     ): void;
+    /** @deprecated Pass the method string instead of a Zod schema. Removed in v3. */
+    public override setRequestHandler<T extends ZodLikeRequestSchema>(
+        requestSchema: T,
+        handler: (request: ReturnType<T['parse']>, ctx: ClientContext) => Result | Promise<Result>
+    ): void;
     public override setRequestHandler(
-        method: string,
+        method: string | ZodLikeRequestSchema,
         schemaOrHandler: unknown,
         maybeHandler?: (params: unknown, ctx: ClientContext) => unknown
     ): void {
+        if (isZodLikeSchema(method)) {
+            return super.setRequestHandler(method, schemaOrHandler as never);
+        }
         if (maybeHandler !== undefined) {
             return super.setRequestHandler(
                 method,
@@ -890,7 +902,24 @@ export class Client extends Protocol<ProtocolSpec, ClientContext> {
      * }
      * ```
      */
-    async callTool(params: CallToolRequest['params'], options?: RequestOptions) {
+    async callTool(params: CallToolRequest['params'], options?: RequestOptions): Promise<CallToolResult>;
+    /** @deprecated The result schema is resolved automatically. Removed in v3. */
+    async callTool(params: CallToolRequest['params'], resultSchema: unknown, options?: RequestOptions): Promise<CallToolResult>;
+    async callTool(
+        params: CallToolRequest['params'],
+        optionsOrSchema?: RequestOptions | unknown,
+        maybeOptions?: RequestOptions
+    ): Promise<CallToolResult> {
+        let options: RequestOptions | undefined;
+        if (optionsOrSchema && typeof optionsOrSchema === 'object' && 'parse' in optionsOrSchema) {
+            deprecate(
+                'callTool(params, schema)',
+                'Client.callTool(params, ResultSchema) is deprecated; the result schema is resolved automatically.'
+            );
+            options = maybeOptions;
+        } else {
+            options = optionsOrSchema as RequestOptions | undefined;
+        }
         // Guard: required-task tools need experimental API
         if (this.isToolTaskRequired(params.name)) {
             throw new ProtocolError(

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

@@ -41,7 +41,9 @@ export { getDisplayName } from '../../shared/metadataUtils.js';
 // Role-agnostic Protocol class (concrete; Client/Server extend it). NOT 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';
 // Protocol types
 export type {
     BaseContext,

packages/core/src/index.ts

@@ -50,3 +50,5 @@ 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';

packages/core/src/shared/protocol.ts

@@ -44,6 +44,9 @@ import {
     ProtocolErrorCode,
     SUPPORTED_PROTOCOL_VERSIONS
 } from '../types/index.js';
+import type { ZodLikeRequestSchema } from '../util/compatSchema.js';
+import { extractMethodLiteral, isZodLikeSchema } from '../util/compatSchema.js';
+import { deprecate } from '../util/deprecate.js';
 import type { AnySchema, SchemaOutput } from '../util/schema.js';
 import { parseSchema } from '../util/schema.js';
 import type { StandardSchemaV1 } from '../util/standardSchema.js';
@@ -849,23 +852,48 @@ export class Protocol<S extends ProtocolSpec = ProtocolSpec, ContextT extends Ba
         resultSchema: R,
         options?: RequestOptions
     ): Promise<SchemaOutput<R>>;
+    /** @deprecated The result schema is resolved automatically from the method name. Removed in v3. */
+    request<M extends RequestMethod>(
+        request: { method: M; params?: Record<string, unknown> },
+        resultSchema: ZodLikeRequestSchema | AnySchema,
+        options?: RequestOptions
+    ): Promise<ResultTypeMap[M]>;
     request(
         requestOrMethod: { method: RequestMethod; params?: Record<string, unknown> } | string,
-        optionsOrParams?: RequestOptions | Record<string, unknown>,
-        resultSchema?: AnySchema,
+        optionsOrParams?: RequestOptions | Record<string, unknown> | AnySchema | ZodLikeRequestSchema,
+        resultSchema?: AnySchema | RequestOptions,
         options?: RequestOptions
     ): Promise<unknown> {
         if (typeof requestOrMethod === 'string') {
             return this._requestWithSchema(
                 { method: requestOrMethod, params: optionsOrParams as Record<string, unknown> | undefined } as Request,
-                resultSchema!,
+                resultSchema as AnySchema,
                 options
             );
         }
+        // v1-compat: request(reqObj, ResultSchema, opts?) — schema arg is ignored.
+        if (isZodLikeSchema(optionsOrParams) || (optionsOrParams && '~standard' in (optionsOrParams as object))) {
+            deprecate(
+                'request(req, schema)',
+                'Protocol.request(request, ResultSchema) is deprecated; the result schema is resolved automatically from the method name.'
+            );
+            const schema = getResultSchema(requestOrMethod.method);
+            return this._requestWithSchema(requestOrMethod as Request, schema, resultSchema as RequestOptions | undefined);
+        }
         const schema = getResultSchema(requestOrMethod.method);
         return this._requestWithSchema(requestOrMethod as Request, schema, optionsOrParams as RequestOptions | undefined);
     }
 
+    /**
+     * Non-overloaded alias for {@linkcode notification} that always takes a
+     * `Notification` object. Exists so that test code can replace
+     * `client.notification` with a single-signature mock without TypeScript
+     * complaining about overload-intersection assignability.
+     */
+    sendNotification(notification: Notification, options?: NotificationOptions): Promise<void> {
+        return this.notification(notification, options);
+    }
+
     /**
      * Sends a request and waits for a response, using the provided schema for validation.
      *
@@ -1134,11 +1162,30 @@ export class Protocol<S extends ProtocolSpec = ProtocolSpec, ContextT extends Ba
         paramsSchema: P,
         handler: (params: SchemaOutput<P>, ctx: ContextT) => Result | Promise<Result>
     ): void;
+    /** @deprecated Pass the method string instead of a Zod schema. Removed in v3. */
+    setRequestHandler<T extends ZodLikeRequestSchema>(
+        requestSchema: T,
+        handler: (request: ReturnType<T['parse']>, ctx: ContextT) => Result | Promise<Result>
+    ): void;
     setRequestHandler(
-        method: string,
+        method: string | ZodLikeRequestSchema,
         schemaOrHandler: AnySchema | ((request: Request, ctx: ContextT) => Result | Promise<Result>),
         maybeHandler?: (params: unknown, ctx: ContextT) => unknown
     ): void {
+        if (isZodLikeSchema(method)) {
+            deprecate(
+                'setRequestHandler(schema)',
+                "setRequestHandler(ZodSchema, handler) is deprecated. Pass the method string, e.g. setRequestHandler('tools/call', handler)."
+            );
+            const requestSchema = method;
+            const methodStr = extractMethodLiteral(requestSchema);
+            const handler = schemaOrHandler as (request: unknown, ctx: ContextT) => Result | Promise<Result>;
+            this.assertRequestHandlerCapability(methodStr);
+            this._requestHandlers.set(methodStr, (request, ctx) =>
+                Promise.resolve(handler(requestSchema.parse(request), ctx))
+            );
+            return;
+        }
         this.assertRequestHandlerCapability(method);
 
         if (maybeHandler === undefined) {
@@ -1202,11 +1249,27 @@ export class Protocol<S extends ProtocolSpec = ProtocolSpec, ContextT extends Ba
         paramsSchema: P,
         handler: (params: SchemaOutput<P>) => void | Promise<void>
     ): void;
+    /** @deprecated Pass the method string instead of a Zod schema. Removed in v3. */
+    setNotificationHandler<T extends ZodLikeRequestSchema>(
+        notificationSchema: T,
+        handler: (notification: ReturnType<T['parse']>) => void | Promise<void>
+    ): void;
     setNotificationHandler(
-        method: string,
+        method: string | ZodLikeRequestSchema,
         schemaOrHandler: AnySchema | ((notification: Notification) => void | Promise<void>),
         maybeHandler?: (params: unknown) => void | Promise<void>
     ): void {
+        if (isZodLikeSchema(method)) {
+            deprecate(
+                'setNotificationHandler(schema)',
+                "setNotificationHandler(ZodSchema, handler) is deprecated. Pass the method string, e.g. setNotificationHandler('notifications/initialized', handler)."
+            );
+            const notificationSchema = method;
+            const methodStr = extractMethodLiteral(notificationSchema);
+            const handler = schemaOrHandler as (notification: unknown) => void | Promise<void>;
+            this._notificationHandlers.set(methodStr, n => Promise.resolve(handler(notificationSchema.parse(n))));
+            return;
+        }
         if (maybeHandler === undefined) {
             const handler = schemaOrHandler as (notification: Notification) => void | Promise<void>;
             const schema = getNotificationSchema(method as NotificationMethod);

packages/core/src/util/compatSchema.ts

@@ -0,0 +1,49 @@
+/**
+ * v1-compat helpers for the deprecated schema-argument forms of
+ * `setRequestHandler` / `setNotificationHandler` / `request`.
+ *
+ * v1 accepted a Zod object whose `.shape.method` is `z.literal('<method>')`.
+ * v2 takes the method string directly. These helpers detect the v1 form and
+ * extract the literal so the deprecated overloads can forward to the v2 path.
+ *
+ * @internal
+ */
+
+/**
+ * Minimal structural type for a Zod object schema. The `method` literal is
+ * checked at runtime by {@link extractMethodLiteral}; the type-level constraint
+ * is intentionally loose because zod v4's `ZodLiteral` doesn't surface `.value`
+ * in its declared type (only at runtime).
+ */
+export interface ZodLikeRequestSchema {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    shape: any;
+    parse(input: unknown): unknown;
+}
+
+/** True if `arg` looks like a Zod object schema (has `.shape` and `.parse`). */
+export function isZodLikeSchema(arg: unknown): arg is ZodLikeRequestSchema {
+    return (
+        typeof arg === 'object' &&
+        arg !== null &&
+        'shape' in arg &&
+        typeof (arg as { parse?: unknown }).parse === 'function'
+    );
+}
+
+/**
+ * Extracts the string value from a Zod-like schema's `shape.method` literal.
+ * Throws if no string `method` literal is present.
+ */
+export function extractMethodLiteral(schema: ZodLikeRequestSchema): string {
+    const methodField = (schema.shape as Record<string, unknown> | undefined)?.method as
+        | { value?: unknown; def?: { values?: unknown[] } }
+        | undefined;
+    const value = methodField?.value ?? methodField?.def?.values?.[0];
+    if (typeof value !== 'string') {
+        throw new TypeError(
+            'v1-compat: schema passed to setRequestHandler/setNotificationHandler is missing a string `method` literal'
+        );
+    }
+    return value;
+}

packages/server/src/server/server.ts

@@ -36,7 +36,8 @@ import type {
     ServerResult,
     TaskManagerOptions,
     ToolResultContent,
-    ToolUseContent
+    ToolUseContent,
+    ZodLikeRequestSchema
 } from '@modelcontextprotocol/core';
 import {
     assertClientRequestTaskCapability,
@@ -48,6 +49,7 @@ import {
     CreateTaskResultSchema,
     ElicitResultSchema,
     EmptyResultSchema,
+    isZodLikeSchema,
     extractTaskManagerOptions,
     LATEST_PROTOCOL_VERSION,
     ListRootsResultSchema,
@@ -236,11 +238,19 @@ export class Server extends Protocol<ProtocolSpec, ServerContext> {
         paramsSchema: P,
         handler: (params: SchemaOutput<P>, ctx: ServerContext) => Result | Promise<Result>
     ): void;
+    /** @deprecated Pass the method string instead of a Zod schema. Removed in v3. */
+    public override setRequestHandler<T extends ZodLikeRequestSchema>(
+        requestSchema: T,
+        handler: (request: ReturnType<T['parse']>, ctx: ServerContext) => Result | Promise<Result>
+    ): void;
     public override setRequestHandler(
-        method: string,
+        method: string | ZodLikeRequestSchema,
         schemaOrHandler: unknown,
         maybeHandler?: (params: unknown, ctx: ServerContext) => unknown
     ): void {
+        if (isZodLikeSchema(method)) {
+            return super.setRequestHandler(method, schemaOrHandler as never);
+        }
         if (maybeHandler !== undefined) {
             return super.setRequestHandler(
                 method,