fix(core): typed-S overload types handler from passed schema; Client/Server use default S

Fix type/runtime disagreement: when calling 3-arg setRequestHandler with a
method in S, overload 1 typed handler params from S[K]['params'] but runtime
parses with the passed paramsSchema. Now constrains paramsSchema to
StandardSchemaV1<S[K]['params']> and types handler from SchemaOutput<P>.

Client/Server now extend Protocol<ProtocolSpec, ...> (default S) instead of
Protocol<McpSpec, ...>, so the typed-S overload doesn't fire on them — spec
methods use the 2-arg form, custom methods use the 3-arg string fallback.
McpSpec stays exported for users who want to compose it.

Author: felixweinberger

packages/client/src/client/client.ts

@@ -21,7 +21,7 @@ import type {
     ListResourceTemplatesRequest,
     ListToolsRequest,
     LoggingLevel,
-    McpSpec,
+    ProtocolSpec,
     MessageExtraInfo,
     NotificationMethod,
     ProtocolOptions,
@@ -206,7 +206,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<McpSpec, ClientContext> {
+export class Client extends Protocol<ProtocolSpec, ClientContext> {
     private _serverCapabilities?: ServerCapabilities;
     private _serverVersion?: Implementation;
     private _negotiatedProtocolVersion?: string;

packages/core/src/shared/protocol.ts

@@ -45,6 +45,7 @@ import {
     SUPPORTED_PROTOCOL_VERSIONS
 } from '../types/index.js';
 import type { AnySchema, SchemaOutput } from '../util/schema.js';
+import type { StandardSchemaV1 } from '../util/standardSchema.js';
 import { parseSchema } from '../util/schema.js';
 import type { TaskContext, TaskManagerHost, TaskManagerOptions, TaskRequestOptions } from './taskManager.js';
 import { NullTaskManager, TaskManager } from './taskManager.js';
@@ -308,7 +309,8 @@ export type ProtocolSpec = {
  * The {@linkcode ProtocolSpec} that describes the standard MCP method vocabulary, derived from
  * {@linkcode RequestTypeMap}, {@linkcode ResultTypeMap} and {@linkcode NotificationTypeMap}.
  *
- * `Client` and `Server` both extend `Protocol<McpSpec>`.
+ * `Client` and `Server` extend `Protocol<ProtocolSpec, ...>` (default `S`), so the typed-`S` overloads do not
+ * fire on them — spec methods use the 2-arg form, custom methods use the 3-arg string form.
  */
 export type McpSpec = {
     requests: { [M in RequestMethod]: { params: RequestTypeMap[M]['params']; result: ResultTypeMap[M] } };
@@ -831,12 +833,12 @@ export class Protocol<S extends ProtocolSpec = ProtocolSpec, ContextT extends Ba
      * Do not use this method to emit notifications! Use
      * {@linkcode Protocol.notification | notification()} instead.
      */
-    request<K extends SpecRequests<S>>(
+    request<K extends SpecRequests<S>, R extends StandardSchemaV1<_Requests<S>[K]['result']>>(
         method: K,
         params: _Requests<S>[K]['params'],
-        resultSchema: AnySchema,
+        resultSchema: R,
         options?: RequestOptions
-    ): Promise<_Requests<S>[K]['result']>;
+    ): Promise<SchemaOutput<R>>;
     request<M extends RequestMethod>(
         request: { method: M; params?: Record<string, unknown> },
         options?: RequestOptions
@@ -1118,10 +1120,10 @@ export class Protocol<S extends ProtocolSpec = ProtocolSpec, ContextT extends Ba
      *   `paramsSchema`. Absent or undefined `params` are normalized to `{}` (after stripping
      *   `_meta`) before validation, so for no-params methods use `z.object({})`.
      */
-    setRequestHandler<K extends SpecRequests<S>>(
+    setRequestHandler<K extends SpecRequests<S>, P extends StandardSchemaV1<_Requests<S>[K]['params']>>(
         method: K,
-        paramsSchema: AnySchema,
-        handler: (params: _Requests<S>[K]['params'], ctx: ContextT) => _Requests<S>[K]['result'] | Promise<_Requests<S>[K]['result']>
+        paramsSchema: P,
+        handler: (params: SchemaOutput<P>, ctx: ContextT) => _Requests<S>[K]['result'] | Promise<_Requests<S>[K]['result']>
     ): void;
     setRequestHandler<M extends RequestMethod>(
         method: M,
@@ -1186,10 +1188,10 @@ export class Protocol<S extends ProtocolSpec = ProtocolSpec, ContextT extends Ba
      * `params`). The three-arg form accepts any method string; when `method` is listed in this
      * instance's {@linkcode ProtocolSpec} the params type is inferred from `S`.
      */
-    setNotificationHandler<K extends SpecNotifications<S>>(
+    setNotificationHandler<K extends SpecNotifications<S>, P extends StandardSchemaV1<_Notifications<S>[K]['params']>>(
         method: K,
-        paramsSchema: AnySchema,
-        handler: (params: _Notifications<S>[K]['params']) => void | Promise<void>
+        paramsSchema: P,
+        handler: (params: SchemaOutput<P>) => void | Promise<void>
     ): void;
     setNotificationHandler<M extends NotificationMethod>(
         method: M,

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

@@ -225,4 +225,18 @@ describe('non-Zod StandardSchemaV1', () => {
         const r = await a.request('acme/double', { n: 21 }, Result);
         expect(r.doubled).toBe(42);
     });
+
+    it('typed-S overload types handler from passed schema, not S (regression)', () => {
+        type Spec = { requests: { 'x/y': { params: { a: string; b: string }; result: { ok: boolean } } } };
+        const p = new Protocol<Spec>();
+        const Narrow = z.object({ a: z.string() });
+        p.setRequestHandler('x/y', Narrow, params => {
+            const _a: string = params.a;
+            // @ts-expect-error -- params is SchemaOutput<Narrow>, has no 'b' even though Spec does
+            const _b: string = params.b;
+            void _a;
+            void _b;
+            return { ok: true };
+        });
+    });
 });

packages/server/src/server/server.ts

@@ -18,7 +18,7 @@ import type {
     ListRootsRequest,
     LoggingLevel,
     LoggingMessageNotification,
-    McpSpec,
+    ProtocolSpec,
     MessageExtraInfo,
     NotificationMethod,
     NotificationOptions,
@@ -101,7 +101,7 @@ export type ServerOptions = ProtocolOptions & {
  *
  * @deprecated Use {@linkcode server/mcp.McpServer | McpServer} instead for the high-level API. Only use `Server` for advanced use cases.
  */
-export class Server extends Protocol<McpSpec, ServerContext> {
+export class Server extends Protocol<ProtocolSpec, ServerContext> {
     private _clientCapabilities?: ClientCapabilities;
     private _clientVersion?: Implementation;
     private _capabilities: ServerCapabilities;