refactor(core): dedupe 3-arg dispatch via _parseParamsWithSchema; notification-side throws plain Error

- Extracted _parseParamsWithSchema (strip _meta + parse + throw via factory) shared by
  _wrapParamsSchemaHandler and the setNotificationHandler 3-arg path.
- Notification 3-arg validation failures throw plain Error instead of ProtocolError;
  they never cross the wire (no JSON-RPC error response), only forwarded to onerror.
- Tests: onerror scenario for 3-arg notification handler with invalid params;
  Server and Client subclass-level tests for 3-arg form parity with per-method wrappers.

Author: felixweinberger

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

@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
 
 import { CreateMessageRequestSchema, ElicitRequestSchema, InMemoryTransport } from '@modelcontextprotocol/core';
 
@@ -71,4 +72,20 @@ describe('Client.setRequestHandler — Zod-schema form parity', () => {
         expect((stringRes.error as { message: string }).message).toContain('Invalid');
         expect(schemaRes.error).toEqual(stringRes.error);
     });
+
+    it('three-arg form gets the same result-validation as string form (elicitation/create)', async () => {
+        const invalidElicitResult = { action: 'nope' };
+        const params = { mode: 'form', message: 'q', requestedSchema: { type: 'object', properties: {} } };
+        const viaThreeArg = await setup(c =>
+            c.setRequestHandler('elicitation/create', z.object({ mode: z.string() }).passthrough(), () => invalidElicitResult as never)
+        );
+        const res = await send(viaThreeArg.ct, 'elicitation/create', params);
+        expect((res.error as { message: string }).message).toContain('Invalid elicitation result');
+    });
+
+    it('three-arg form handles non-spec methods through Client', async () => {
+        const { ct } = await setup(c => c.setRequestHandler('acme/echo', z.object({ msg: z.string() }), p => ({ reply: p.msg })));
+        const res = await send(ct, 'acme/echo', { msg: 'hi' });
+        expect(res.result).toEqual({ reply: 'hi' });
+    });
 });

packages/core/src/shared/protocol.ts

@@ -1100,8 +1100,28 @@ export abstract class Protocol<ContextT extends BaseContext> {
     }
 
     /**
-     * Builds a request handler from a `paramsSchema` + params-only user handler. Strips `_meta`,
-     * validates `params` against the schema, and invokes the user handler with the parsed params.
+     * Shared by the 3-arg `setRequestHandler`/`setNotificationHandler` dispatch:
+     * strips protocol-level `_meta`, validates remaining `params` against `paramsSchema`,
+     * and returns the parsed value. Throws via `makeError` so each caller can use the
+     * error class appropriate for its path (JSON-RPC error for requests, local error for notifications).
+     */
+    private async _parseParamsWithSchema(
+        method: string,
+        paramsSchema: StandardSchemaV1,
+        rawParams: unknown,
+        makeError: (msg: string) => Error
+    ): Promise<unknown> {
+        const { _meta, ...userParams } = (rawParams ?? {}) as Record<string, unknown>;
+        void _meta;
+        const parsed = await parseStandardSchema(paramsSchema, userParams);
+        if (!parsed.success) {
+            throw makeError(`Invalid params for ${method}: ${parsed.error.message}`);
+        }
+        return parsed.data;
+    }
+
+    /**
+     * Builds a request handler from a `paramsSchema` + params-only user handler.
      * Shared by {@linkcode setRequestHandler}'s 3-arg dispatch and `Client`/`Server` overrides
      * so that per-method wrapping can be applied uniformly to the normalized handler.
      */
@@ -1111,13 +1131,10 @@ export abstract class Protocol<ContextT extends BaseContext> {
         userHandler: (params: unknown, ctx: ContextT) => unknown
     ): (request: Request, ctx: ContextT) => Promise<Result> {
         return async (request, ctx) => {
-            const { _meta, ...userParams } = (request.params ?? {}) as Record<string, unknown>;
-            void _meta;
-            const parsed = await parseStandardSchema(paramsSchema, userParams);
-            if (!parsed.success) {
-                throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Invalid params for ${method}: ${parsed.error.message}`);
-            }
-            return userHandler(parsed.data, ctx) as Result;
+            const data = await this._parseParamsWithSchema(method, paramsSchema, request.params, msg => {
+                return new ProtocolError(ProtocolErrorCode.InvalidParams, msg);
+            });
+            return userHandler(data, ctx) as Result;
         };
     }
 
@@ -1209,13 +1226,9 @@ export abstract class Protocol<ContextT extends BaseContext> {
 
         const paramsSchema = schemaOrHandler as StandardSchemaV1;
         this._notificationHandlers.set(method, async notification => {
-            const { _meta, ...userParams } = (notification.params ?? {}) as Record<string, unknown>;
-            void _meta;
-            const parsed = await parseStandardSchema(paramsSchema, userParams);
-            if (!parsed.success) {
-                throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Invalid params for ${method}: ${parsed.error.message}`);
-            }
-            return maybeHandler(parsed.data);
+            // Notification handler errors never cross the wire (no JSON-RPC response); they go to onerror.
+            const data = await this._parseParamsWithSchema(method, paramsSchema, notification.params, msg => new Error(msg));
+            return maybeHandler(data);
         });
     }
 

packages/core/test/shared/threeArgHandlers.test.ts

@@ -77,6 +77,21 @@ describe('setNotificationHandler — three-arg paramsSchema form', () => {
         await new Promise(r => setTimeout(r, 0));
         expect(received).toEqual([{ n: 1 }, { n: 2 }]);
     });
+
+    it('forwards param-validation failures to onerror (no JSON-RPC error response)', async () => {
+        const { a, b } = await makePair();
+        const errs: Error[] = [];
+        b.onerror = e => errs.push(e);
+        let invoked = false;
+        b.setNotificationHandler('acme/tick', z.object({ n: z.number() }), () => {
+            invoked = true;
+        });
+        await a.notification({ method: 'acme/tick', params: { n: 'not-a-number' } });
+        await new Promise(r => setTimeout(r, 0));
+        expect(invoked).toBe(false);
+        expect(errs.length).toBe(1);
+        expect(String(errs[0])).toMatch(/Invalid params for acme\/tick/);
+    });
 });
 
 describe('non-Zod StandardSchemaV1', () => {

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

@@ -63,4 +63,25 @@ describe('Server.setRequestHandler — Zod-schema form parity', () => {
         });
         expect(res.result).toEqual({ reply: 'hi' });
     });
+
+    it('three-arg form gets the same task-result validation as string form', async () => {
+        const invalidTaskResult = { content: [{ type: 'text' as const, text: 'not a task result' }] };
+        const viaThreeArg = await setup(s =>
+            s.setRequestHandler('tools/call', z.object({ name: z.string() }).passthrough(), () => invalidTaskResult)
+        );
+        const res = await callToolWithTask(viaThreeArg.ct);
+        expect((res.error as { message: string }).message).toContain('Invalid task creation result');
+    });
+
+    it('three-arg form handles non-spec methods through Server', async () => {
+        const { ct } = await setup(s => s.setRequestHandler('acme/echo', z.object({ msg: z.string() }), p => ({ reply: p.msg })));
+        const res = await new Promise<{ result?: unknown; error?: unknown }>(resolve => {
+            ct.onmessage = m => {
+                const msg = m as { result?: unknown; error?: unknown };
+                if ('result' in msg || 'error' in msg) resolve(msg);
+            };
+            ct.send({ jsonrpc: '2.0', id: 1, method: 'acme/echo', params: { msg: 'hi' } });
+        });
+        expect(res.result).toEqual({ reply: 'hi' });
+    });
 });