feat(compat): mark setRequestHandler/setNotificationHandler Zod-schema overloads @deprecated; address review

- @deprecated on the Zod-schema overloads of setRequestHandler /
  setNotificationHandler (Protocol + Client + Server). The 3-arg
  (method, paramsSchema, handler) form is the non-deprecated path
  for custom methods. request()/mcpReq.send()/callTool schema
  overloads are NOT deprecated (only typed form for custom-method
  results).
- Unify positional-schema detection via isResultSchemaLike()
  (~standard or .parse) used by request(), mcpReq.send() and
  callTool().
- request()/mcpReq.send() now reject with a clear TypeError when a
  non-spec method is called without a result schema (was: undefined
  schema crashed in parseSchema downstream).
- Avoid redundant spec-schema parses: _setRequestHandlerByMethod()
  takes skipSpecParse; Server/Client overrides pass true for their
  per-method wrappers and for the Zod-schema form. Aligns Protocol
  with subclasses (both skip when user supplied a schema).
- compatSchema.ts: drop @internal from file header (ZodLikeRequestSchema
  is publicly exported); add isResultSchemaLike helper.
- Tests: client setRequestHandlerSchemaParity (elicitation+sampling),
  compatSchema helpers, runtime-guard cases for request()/mcpReq.send().

Author: felixweinberger

packages/client/src/client/client.ts

@@ -55,6 +55,7 @@ import {
     extractTaskManagerOptions,
     GetPromptResultSchema,
     InitializeResultSchema,
+    isResultSchemaLike,
     isZodLikeSchema,
     LATEST_PROTOCOL_VERSION,
     ListChangedOptionsBaseSchema,
@@ -343,15 +344,16 @@ export class Client extends Protocol<ClientContext> {
         method: M,
         handler: (request: RequestTypeMap[M], ctx: ClientContext) => ResultTypeMap[M] | Promise<ResultTypeMap[M]>
     ): void;
-    /** For spec methods the method-string form is more concise; this overload is the supported call form for non-spec methods or when you want full-envelope validation. */
+    /** @deprecated Use the 3-arg `(method, paramsSchema, handler)` form for custom methods, or the method-string form for spec methods. */
     public override setRequestHandler<T extends ZodLikeRequestSchema>(
         requestSchema: T,
         handler: (request: ReturnType<T['parse']>, ctx: ClientContext) => Result | Promise<Result>
     ): void;
     public override setRequestHandler(methodOrSchema: string | ZodLikeRequestSchema, schemaHandler: unknown): void {
         let method: string;
         let handler: (request: Request, ctx: ClientContext) => ClientResult | Promise<ClientResult>;
-        if (isZodLikeSchema(methodOrSchema)) {
+        const fromSchema = isZodLikeSchema(methodOrSchema);
+        if (fromSchema) {
             const schema = methodOrSchema;
             const userHandler = schemaHandler as (request: unknown, ctx: ClientContext) => Result | Promise<Result>;
             method = extractMethodLiteral(schema);
@@ -426,8 +428,8 @@ export class Client extends Protocol<ClientContext> {
                 return validatedResult;
             };
 
-            // Install the wrapped handler
-            return this._setRequestHandlerByMethod(method, wrappedHandler);
+            // wrappedHandler validates with the spec schema itself; skip the extra parse in the base helper.
+            return this._setRequestHandlerByMethod(method, wrappedHandler, true);
         }
 
         if (method === 'sampling/createMessage') {
@@ -469,12 +471,12 @@ export class Client extends Protocol<ClientContext> {
                 return validationResult.data;
             };
 
-            // Install the wrapped handler
-            return this._setRequestHandlerByMethod(method, wrappedHandler);
+            // wrappedHandler validates with the spec schema itself; skip the extra parse in the base helper.
+            return this._setRequestHandlerByMethod(method, wrappedHandler, true);
         }
 
-        // Other handlers use default behavior
-        return this._setRequestHandlerByMethod(method, handler);
+        // Other methods: skip the spec parse only when the user supplied their own schema (it is the source of truth).
+        return this._setRequestHandlerByMethod(method, handler, fromSchema);
     }
 
     protected assertCapability(capability: keyof ServerCapabilities, method: string): void {
@@ -898,7 +900,7 @@ export class Client extends Protocol<ClientContext> {
         optionsOrSchema?: RequestOptions | unknown,
         maybeOptions?: RequestOptions
     ): Promise<CallToolResult> {
-        const arg2IsSchema = optionsOrSchema != null && typeof optionsOrSchema === 'object' && 'parse' in optionsOrSchema;
+        const arg2IsSchema = isResultSchemaLike(optionsOrSchema);
         // v1 allowed `callTool(params, undefined, opts)` (resultSchema was optional-with-default);
         // when arg2 is not a schema, prefer arg3 if present so opts aren't dropped.
         const options: RequestOptions | undefined = arg2IsSchema

packages/client/test/client/setRequestHandlerSchemaParity.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest';
+
+import { CreateMessageRequestSchema, ElicitRequestSchema, InMemoryTransport } from '@modelcontextprotocol/core';
+
+import { Client } from '../../src/client/client.js';
+
+/**
+ * Mirrors the server-side parity test: registering with the Zod-schema form must
+ * route through the same per-method wrapper (result-shape validation) as the
+ * method-string form.
+ */
+describe('Client.setRequestHandler — Zod-schema form parity', () => {
+    async function setup(register: (c: Client) => void) {
+        const client = new Client({ name: 't', version: '1.0' }, { capabilities: { sampling: {}, elicitation: {} } });
+        register(client);
+        const [ct, st] = InMemoryTransport.createLinkedPair();
+        await ct.start();
+        // Minimal server-side stub on ct so Client.connect's initialize handshake completes.
+        ct.onmessage = m => {
+            const msg = m as { id?: number; method?: string };
+            if (msg.method === 'initialize') {
+                void ct.send({
+                    jsonrpc: '2.0',
+                    id: msg.id!,
+                    result: { protocolVersion: '2025-06-18', serverInfo: { name: 's', version: '1.0' }, capabilities: {} }
+                });
+            }
+        };
+        await client.connect(st);
+        return { ct };
+    }
+
+    async function send(
+        ct: InMemoryTransport,
+        method: string,
+        params: Record<string, unknown>
+    ): Promise<{ result?: unknown; error?: unknown }> {
+        return await new Promise(resolve => {
+            ct.onmessage = m => {
+                const msg = m as { id?: number; result?: unknown; error?: unknown };
+                if (msg.id === 99 && ('result' in msg || 'error' in msg)) resolve(msg);
+            };
+            void ct.send({ jsonrpc: '2.0', id: 99, method, params });
+        });
+    }
+
+    it('elicitation/create — schema form gets the same result-validation as string form', async () => {
+        const invalidElicitResult = { action: 'nope' };
+        const params = { mode: 'form', message: 'q', requestedSchema: { type: 'object', properties: {} } };
+
+        const viaString = await setup(c => c.setRequestHandler('elicitation/create', () => invalidElicitResult as never));
+        const viaSchema = await setup(c => c.setRequestHandler(ElicitRequestSchema, () => invalidElicitResult as never));
+
+        const stringRes = await send(viaString.ct, 'elicitation/create', params);
+        const schemaRes = await send(viaSchema.ct, 'elicitation/create', params);
+
+        expect((stringRes.error as { message: string }).message).toContain('Invalid elicitation result');
+        expect(schemaRes.error).toEqual(stringRes.error);
+    });
+
+    it('sampling/createMessage — schema form gets the same result-validation as string form', async () => {
+        const invalidSamplingResult = { role: 'assistant' };
+        const params = { messages: [], maxTokens: 1 };
+
+        const viaString = await setup(c => c.setRequestHandler('sampling/createMessage', () => invalidSamplingResult as never));
+        const viaSchema = await setup(c => c.setRequestHandler(CreateMessageRequestSchema, () => invalidSamplingResult as never));
+
+        const stringRes = await send(viaString.ct, 'sampling/createMessage', params);
+        const schemaRes = await send(viaSchema.ct, 'sampling/createMessage', params);
+
+        expect((stringRes.error as { message: string }).message).toContain('Invalid');
+        expect(schemaRes.error).toEqual(stringRes.error);
+    });
+});

packages/core/src/index.ts

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

packages/core/src/shared/protocol.ts

@@ -45,7 +45,7 @@ import {
     SUPPORTED_PROTOCOL_VERSIONS
 } from '../types/index.js';
 import type { ZodLikeRequestSchema } from '../util/compatSchema.js';
-import { extractMethodLiteral, isZodLikeSchema } from '../util/compatSchema.js';
+import { extractMethodLiteral, isResultSchemaLike, isZodLikeSchema } from '../util/compatSchema.js';
 import type { AnySchema, SchemaOutput } from '../util/schema.js';
 import { parseSchema } from '../util/schema.js';
 import type { TaskContext, TaskManagerHost, TaskManagerOptions, TaskRequestOptions } from './taskManager.js';
@@ -611,10 +611,15 @@ export abstract class Protocol<ContextT extends BaseContext> {
                 _meta: request.params?._meta,
                 signal: abortController.signal,
                 send: ((r: Request, optionsOrSchema?: TaskRequestOptions | AnySchema, maybeOptions?: TaskRequestOptions) => {
-                    if (optionsOrSchema && '~standard' in optionsOrSchema) {
-                        return sendRequest(r, optionsOrSchema, maybeOptions);
+                    if (isResultSchemaLike(optionsOrSchema)) {
+                        return sendRequest(r, optionsOrSchema as AnySchema, maybeOptions);
                     }
                     const resultSchema = getResultSchema(r.method as RequestMethod);
+                    if (!resultSchema) {
+                        return Promise.reject(
+                            new TypeError(`mcpReq.send(): '${r.method}' is not a spec method; pass a result schema as the second argument.`)
+                        );
+                    }
                     return sendRequest(r, resultSchema, optionsOrSchema);
                 }) as BaseContext['mcpReq']['send'],
                 notify: sendNotification
@@ -807,10 +812,15 @@ export abstract class Protocol<ContextT extends BaseContext> {
     /** For spec methods the one-argument form is more concise; this overload is the supported call form for non-spec methods or custom result shapes. */
     request<T extends AnySchema>(request: Request, resultSchema: T, options?: RequestOptions): Promise<SchemaOutput<T>>;
     request(request: Request, optionsOrSchema?: RequestOptions | AnySchema, maybeOptions?: RequestOptions): Promise<unknown> {
-        if (optionsOrSchema && '~standard' in optionsOrSchema) {
-            return this._requestWithSchema(request, optionsOrSchema, maybeOptions);
+        if (isResultSchemaLike(optionsOrSchema)) {
+            return this._requestWithSchema(request, optionsOrSchema as AnySchema, maybeOptions);
         }
         const schema = getResultSchema(request.method as RequestMethod);
+        if (!schema) {
+            return Promise.reject(
+                new TypeError(`request(): '${request.method}' is not a spec method; pass a result schema as the second argument.`)
+            );
+        }
         return this._requestWithSchema(request, schema, optionsOrSchema);
     }
 
@@ -1043,7 +1053,7 @@ export abstract class Protocol<ContextT extends BaseContext> {
         method: M,
         handler: (request: RequestTypeMap[M], ctx: ContextT) => Result | Promise<Result>
     ): void;
-    /** For spec methods the method-string form is more concise; this overload is the supported call form for non-spec methods or when you want full-envelope validation. */
+    /** @deprecated Use the 3-arg `(method, paramsSchema, handler)` form for custom methods, or the method-string form for spec methods. */
     setRequestHandler<T extends ZodLikeRequestSchema>(
         requestSchema: T,
         handler: (request: ReturnType<T['parse']>, ctx: ContextT) => Result | Promise<Result>
@@ -1052,9 +1062,14 @@ export abstract class Protocol<ContextT extends BaseContext> {
         if (isZodLikeSchema(method)) {
             const requestSchema = method;
             const methodStr = extractMethodLiteral(requestSchema);
-            this.assertRequestHandlerCapability(methodStr);
-            this._requestHandlers.set(methodStr, (request, ctx) =>
-                Promise.resolve((handler as (req: unknown, ctx: ContextT) => Result | Promise<Result>)(requestSchema.parse(request), ctx))
+            // The user's schema is the source of truth; spec-schema validation is skipped to avoid double-parsing.
+            this._setRequestHandlerByMethod(
+                methodStr,
+                (request, ctx) =>
+                    Promise.resolve(
+                        (handler as (req: unknown, ctx: ContextT) => Result | Promise<Result>)(requestSchema.parse(request), ctx)
+                    ),
+                true
             );
             return;
         }
@@ -1064,9 +1079,22 @@ export abstract class Protocol<ContextT extends BaseContext> {
     /**
      * Registers a request handler by method string, bypassing the public overload set.
      * Used by `Client`/`Server` overrides to forward without `as RequestMethod` casts.
+     *
+     * @param skipSpecParse - When `true`, the handler is stored directly without
+     * wrapping it in spec-schema validation. Set this when the caller has already
+     * applied its own validation (Zod-schema form, or a method-specific wrapper)
+     * to avoid parsing the same request multiple times.
      */
-    protected _setRequestHandlerByMethod(method: string, handler: (request: Request, ctx: ContextT) => Result | Promise<Result>): void {
+    protected _setRequestHandlerByMethod(
+        method: string,
+        handler: (request: Request, ctx: ContextT) => Result | Promise<Result>,
+        skipSpecParse = false
+    ): void {
         this.assertRequestHandlerCapability(method);
+        if (skipSpecParse) {
+            this._requestHandlers.set(method, (request, ctx) => Promise.resolve(handler(request, ctx)));
+            return;
+        }
         const schema = getRequestSchema(method as RequestMethod);
         this._requestHandlers.set(method, (request, ctx) => {
             const parsed = schema ? (schema.parse(request) as Request) : request;
@@ -1101,7 +1129,7 @@ export abstract class Protocol<ContextT extends BaseContext> {
         method: M,
         handler: (notification: NotificationTypeMap[M]) => void | Promise<void>
     ): void;
-    /** For spec methods the method-string form is more concise; this overload is the supported call form for non-spec methods or when you want full-envelope validation. */
+    /** @deprecated Use the 3-arg `(method, paramsSchema, handler)` form for custom methods, or the method-string form for spec methods. */
     setNotificationHandler<T extends ZodLikeRequestSchema>(
         notificationSchema: T,
         handler: (notification: ReturnType<T['parse']>) => void | Promise<void>

packages/core/src/util/compatSchema.ts

@@ -4,15 +4,14 @@
  * v1 accepted a Zod object whose `.shape.method` is `z.literal('<method>')`.
  * v2 also accepts the method string directly. These helpers detect the schema
  * form and extract the literal so the dispatcher can route to the correct path.
- *
- * @internal
  */
 
 /**
- * Minimal structural type for a Zod object schema. The `method` literal is
- * checked at runtime by `extractMethodLiteral`; the type-level constraint
- * is intentionally loose because zod v4's `ZodLiteral` doesn't surface `.value`
- * in its declared type (only at runtime).
+ * Minimal structural type for a v1-style Zod request/notification schema: an
+ * object schema whose `.shape.method` is a string literal. The `method` literal
+ * is checked at runtime; 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
@@ -39,3 +38,13 @@ export function extractMethodLiteral(schema: ZodLikeRequestSchema): string {
     }
     return value;
 }
+
+/**
+ * True if `arg` looks like a result schema passed positionally to
+ * `request()` / `callTool()` / `mcpReq.send()`. Detects either the
+ * Standard Schema marker (`~standard`) or a Zod-style `parse` function so the
+ * v1 schema-argument form is recognised regardless of zod major version.
+ */
+export function isResultSchemaLike(arg: unknown): arg is object {
+    return arg != null && typeof arg === 'object' && ('~standard' in arg || typeof (arg as { parse?: unknown }).parse === 'function');
+}

packages/core/test/shared/customMethods.test.ts

@@ -106,6 +106,13 @@ describe('request() — explicit result schema overload', () => {
         const r = await a.request({ method: 'ping' });
         expect(r).toEqual({});
     });
+
+    it('throws a clear error for a non-spec method without a result schema', async () => {
+        const { a, b } = await makePair();
+        b.setRequestHandler(EchoRequest, req => ({ reply: req.params.msg }));
+        // @ts-expect-error — bypassing the overload set to exercise the runtime guard
+        await expect(a.request({ method: 'acme/echo', params: { msg: 'x' } })).rejects.toThrow(/'acme\/echo' is not a spec method/);
+    });
 });
 
 describe('ctx.mcpReq.send() — explicit result schema overload', () => {
@@ -132,6 +139,16 @@ describe('ctx.mcpReq.send() — explicit result schema overload', () => {
         await a.request({ method: 'acme/outer' }, z.object({}));
         expect(pingResult).toEqual({});
     });
+
+    it('throws a clear error for a non-spec method without a result schema', async () => {
+        const { a, b } = await makePair();
+        b.setRequestHandler(z.object({ method: z.literal('acme/outer') }), async (_req, ctx) => {
+            // @ts-expect-error — bypassing the overload set to exercise the runtime guard
+            await ctx.mcpReq.send({ method: 'acme/nope' });
+            return {};
+        });
+        await expect(a.request({ method: 'acme/outer' }, z.object({}))).rejects.toThrow(/'acme\/nope' is not a spec method/);
+    });
 });
 
 describe('notification() mock-assignability', () => {

packages/core/test/util/compatSchema.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+
+import { extractMethodLiteral, isResultSchemaLike, isZodLikeSchema } from '../../src/util/compatSchema.js';
+
+describe('compatSchema helpers', () => {
+    describe('isZodLikeSchema', () => {
+        it('detects a Zod object schema', () => {
+            expect(isZodLikeSchema(z.object({ method: z.literal('x') }))).toBe(true);
+        });
+        it('rejects strings, plain objects, and null', () => {
+            expect(isZodLikeSchema('tools/call')).toBe(false);
+            expect(isZodLikeSchema({ shape: {} })).toBe(false);
+            expect(isZodLikeSchema(null)).toBe(false);
+        });
+    });
+
+    describe('extractMethodLiteral', () => {
+        it('reads the method literal from a Zod object schema', () => {
+            expect(extractMethodLiteral(z.object({ method: z.literal('acme/echo') }))).toBe('acme/echo');
+        });
+        it('throws when no string method literal is present', () => {
+            expect(() => extractMethodLiteral(z.object({ method: z.string() }))).toThrow(TypeError);
+            expect(() => extractMethodLiteral(z.object({}))).toThrow(TypeError);
+        });
+    });
+
+    describe('isResultSchemaLike', () => {
+        it('detects Standard Schema (~standard) and Zod-style parse()', () => {
+            expect(isResultSchemaLike(z.string())).toBe(true);
+            expect(isResultSchemaLike({ '~standard': { version: 1, vendor: 't', validate: () => ({ value: 1 }) } })).toBe(true);
+            expect(isResultSchemaLike({ parse: (v: unknown) => v })).toBe(true);
+        });
+        it('rejects RequestOptions-shaped objects, undefined, and primitives', () => {
+            expect(isResultSchemaLike({ timeout: 100 })).toBe(false);
+            expect(isResultSchemaLike(undefined)).toBe(false);
+            expect(isResultSchemaLike('x')).toBe(false);
+        });
+    });
+});