fix: enforce result type on Client/Server 3-arg setRequestHandler; clarify ProtocolSpec.params is informational

Author: felixweinberger

.changeset/export-protocol-spec.md

@@ -3,4 +3,4 @@
 '@modelcontextprotocol/server': minor
 ---
 
-Export the abstract `Protocol` class (was reachable in v1 via deep imports) and add `Protocol<ContextT, SpecT extends ProtocolSpec = McpSpec>` for typed custom-method vocabularies. Subclasses supplying a concrete `ProtocolSpec` get method-name autocomplete and params/result correlation on the typed `setRequestHandler`/`setNotificationHandler` overloads.
+Export the abstract `Protocol` class (was reachable in v1 via deep imports) and add `Protocol<ContextT, SpecT extends ProtocolSpec = McpSpec>` for typed custom-method vocabularies. Subclasses supplying a concrete `ProtocolSpec` get method-name autocomplete and result-type correlation on the typed `setRequestHandler`/`setNotificationHandler` overloads (handler param types come from the `paramsSchema` argument; `ProtocolSpec['params']` is informational).

packages/client/src/client/client.ts

@@ -344,8 +344,13 @@ export class Client extends Protocol<ClientContext> {
         method: M,
         handler: (request: RequestTypeMap[M], ctx: ClientContext) => ResultTypeMap[M] | Promise<ResultTypeMap[M]>
     ): void;
-    public override setRequestHandler<P extends StandardSchemaV1>(
-        method: string,
+    public override setRequestHandler<M extends RequestMethod, P extends StandardSchemaV1>(
+        method: M,
+        paramsSchema: P,
+        handler: (params: StandardSchemaV1.InferOutput<P>, ctx: ClientContext) => ResultTypeMap[M] | Promise<ResultTypeMap[M]>
+    ): void;
+    public override setRequestHandler<M extends string, P extends StandardSchemaV1>(
+        method: M extends RequestMethod ? never : M,
         paramsSchema: P,
         handler: (params: StandardSchemaV1.InferOutput<P>, ctx: ClientContext) => Result | Promise<Result>
     ): void;

packages/core/src/shared/protocol.ts

@@ -309,9 +309,12 @@ type TimeoutInfo = {
  * Declares the request and notification vocabulary a `Protocol` subclass speaks.
  *
  * Supplying a concrete `ProtocolSpec` as `Protocol`'s second type argument gives method-name
- * autocomplete and params/result correlation on the typed overloads of `setRequestHandler`
+ * autocomplete and result-type correlation on the typed overloads of `setRequestHandler`
  * and `setNotificationHandler`. `Protocol` defaults to {@linkcode McpSpec}; using the bare
  * `ProtocolSpec` type leaves methods string-keyed and untyped.
+ *
+ * Only `requests[K].result` is enforced by the type system; `params` shapes are informational
+ * (handler param types come from the `paramsSchema` you pass at the call site).
  */
 export type ProtocolSpec = {
     requests?: Record<string, { params?: unknown; result: unknown }>;

packages/server/src/server/server.ts

@@ -232,8 +232,13 @@ export class Server extends Protocol<ServerContext> {
         method: M,
         handler: (request: RequestTypeMap[M], ctx: ServerContext) => ResultTypeMap[M] | Promise<ResultTypeMap[M]>
     ): void;
-    public override setRequestHandler<P extends StandardSchemaV1>(
-        method: string,
+    public override setRequestHandler<M extends RequestMethod, P extends StandardSchemaV1>(
+        method: M,
+        paramsSchema: P,
+        handler: (params: StandardSchemaV1.InferOutput<P>, ctx: ServerContext) => ResultTypeMap[M] | Promise<ResultTypeMap[M]>
+    ): void;
+    public override setRequestHandler<M extends string, P extends StandardSchemaV1>(
+        method: M extends RequestMethod ? never : M,
         paramsSchema: P,
         handler: (params: StandardSchemaV1.InferOutput<P>, ctx: ServerContext) => Result | Promise<Result>
     ): void;

packages/server/test/server/setRequestHandlerSchemaParity.test.ts

@@ -63,4 +63,12 @@ describe('Server.setRequestHandler — Zod-schema form parity', () => {
         });
         expect(res.result).toEqual({ reply: 'hi' });
     });
+
+    it('three-arg form on Server enforces spec-method result type (no fallthrough to loose overload)', () => {
+        const s = new Server({ name: 't', version: '1.0' }, { capabilities: { tools: {} } });
+        // @ts-expect-error -- result for 'ping' must be EmptyResult-compatible; loose overload is never-guarded for spec methods
+        s.setRequestHandler('ping', z.object({}), () => ({ ok: 'wrong-type' }) as { ok: string });
+        // non-spec methods still allow loose Result
+        s.setRequestHandler('acme/custom', z.object({}), () => ({ anything: 1 }));
+    });
 });