refactor(core): un-deprecate schema-arg overloads; inline _registerCompatRequestHandler

The schema-arg forms of request()/setRequestHandler()/setNotificationHandler()
are a parallel supported style, not superseded: request(req, schema) is the only
typed form for non-spec method results, and the schema-first handler form gives
full-envelope validation. Replaces the @deprecated tags with plain JSDoc guidance
so the PR's own custom-method examples no longer render with strikethrough.

Also inlines _registerCompatRequestHandler (single callsite) and fixes the stale
'schema parameter removed' note in migration.md.

Author: felixweinberger

docs/migration.md

@@ -903,7 +903,7 @@ import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/server/valida
 
 The following APIs are unchanged between v1 and v2 (only the import paths changed):
 
-- `Client` constructor and most client methods (`connect`, `listTools`, `listPrompts`, `listResources`, `readResource`, etc.) — note: `callTool()` signature changed (schema parameter removed)
+- `Client` constructor and most client methods (`connect`, `listTools`, `listPrompts`, `listResources`, `readResource`, etc.) — note: `callTool()` schema parameter is now optional
 - `McpServer` constructor, `server.connect(transport)`, `server.close()`
 - `Server` (low-level) constructor and all methods
 - `StreamableHTTPClientTransport`, `SSEClientTransport`, `StdioClientTransport` constructors and options

packages/client/src/client/client.ts

@@ -343,7 +343,7 @@ export class Client extends Protocol<ClientContext> {
         method: M,
         handler: (request: RequestTypeMap[M], ctx: ClientContext) => ResultTypeMap[M] | Promise<ResultTypeMap[M]>
     ): void;
-    /** @deprecated For spec methods, pass the method string instead. */
+    /** 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. */
     public override setRequestHandler<T extends ZodLikeRequestSchema>(
         requestSchema: T,
         handler: (request: ReturnType<T['parse']>, ctx: ClientContext) => Result | Promise<Result>
@@ -891,7 +891,7 @@ export class Client extends Protocol<ClientContext> {
      * ```
      */
     async callTool(params: CallToolRequest['params'], options?: RequestOptions): Promise<CallToolResult>;
-    /** @deprecated The result schema is resolved internally; use `callTool(params)`. The second argument is accepted for v1 source compatibility and ignored. */
+    /** The `resultSchema` argument is accepted for v1 source compatibility and ignored; output validation uses the tool's declared `outputSchema`. Prefer `callTool(params, options)`. */
     async callTool(params: CallToolRequest['params'], resultSchema: unknown, options?: RequestOptions): Promise<CallToolResult>;
     async callTool(
         params: CallToolRequest['params'],

packages/core/src/shared/protocol.ts

@@ -213,7 +213,7 @@ export type BaseContext = {
                 request: { method: M; params?: Record<string, unknown> },
                 options?: TaskRequestOptions
             ): Promise<ResultTypeMap[M]>;
-            /** @deprecated For spec methods, the result schema is resolved automatically; use `send(req)`. */
+            /** 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. */
             <T extends AnySchema>(request: Request, resultSchema: T, options?: TaskRequestOptions): Promise<SchemaOutput<T>>;
         };
 
@@ -804,7 +804,7 @@ export abstract class Protocol<ContextT extends BaseContext> {
         request: { method: M; params?: Record<string, unknown> },
         options?: RequestOptions
     ): Promise<ResultTypeMap[M]>;
-    /** @deprecated For spec methods, the result schema is resolved automatically; use `request(req)`. */
+    /** 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) {
@@ -1043,32 +1043,24 @@ export abstract class Protocol<ContextT extends BaseContext> {
         method: M,
         handler: (request: RequestTypeMap[M], ctx: ContextT) => Result | Promise<Result>
     ): void;
-    /** @deprecated For spec methods, pass the method string instead. */
+    /** 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. */
     setRequestHandler<T extends ZodLikeRequestSchema>(
         requestSchema: T,
         handler: (request: ReturnType<T['parse']>, ctx: ContextT) => Result | Promise<Result>
     ): void;
     setRequestHandler(method: string | ZodLikeRequestSchema, handler: (request: Request, ctx: ContextT) => Result | Promise<Result>): void {
         if (isZodLikeSchema(method)) {
-            return this._registerCompatRequestHandler(method, handler as (request: unknown, ctx: ContextT) => Result | Promise<Result>);
+            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))
+            );
+            return;
         }
         this._setRequestHandlerByMethod(method, handler);
     }
 
-    /**
-     * Dispatches the Zod-schema form of `setRequestHandler` — extracts the method literal from the
-     * schema and registers a handler that parses the full request through it. Called by the base
-     * {@linkcode Protocol.setRequestHandler} overload dispatcher for the schema-first signature.
-     */
-    protected _registerCompatRequestHandler(
-        requestSchema: ZodLikeRequestSchema,
-        handler: (request: unknown, ctx: ContextT) => Result | Promise<Result>
-    ): void {
-        const methodStr = extractMethodLiteral(requestSchema);
-        this.assertRequestHandlerCapability(methodStr);
-        this._requestHandlers.set(methodStr, (request, ctx) => Promise.resolve(handler(requestSchema.parse(request), ctx)));
-    }
-
     /**
      * Registers a request handler by method string, bypassing the public overload set.
      * Used by `Client`/`Server` overrides to forward without `as RequestMethod` casts.
@@ -1109,7 +1101,7 @@ export abstract class Protocol<ContextT extends BaseContext> {
         method: M,
         handler: (notification: NotificationTypeMap[M]) => void | Promise<void>
     ): void;
-    /** @deprecated For spec methods, pass the method string instead. */
+    /** 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. */
     setNotificationHandler<T extends ZodLikeRequestSchema>(
         notificationSchema: T,
         handler: (notification: ReturnType<T['parse']>) => void | Promise<void>

packages/server/src/server/server.ts

@@ -231,7 +231,7 @@ export class Server extends Protocol<ServerContext> {
         method: M,
         handler: (request: RequestTypeMap[M], ctx: ServerContext) => ResultTypeMap[M] | Promise<ResultTypeMap[M]>
     ): void;
-    /** @deprecated For spec methods, pass the method string instead. */
+    /** 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. */
     public override setRequestHandler<T extends ZodLikeRequestSchema>(
         requestSchema: T,
         handler: (request: ReturnType<T['parse']>, ctx: ServerContext) => Result | Promise<Result>