fix: address review — setNotificationHandler 3-arg passes raw notification as 2nd arg; export StandardSchemaV1; fix example headers

Author: felixweinberger

docs/migration-SKILL.md

@@ -359,9 +359,11 @@ server.setRequestHandler(z.object({ method: z.literal('acme/search'), params: P
 
 // v2: method string + schemas object; handler receives parsed params
 server.setRequestHandler('acme/search', { params: P, result: R }, async (params, ctx) => { ... });
-client.setNotificationHandler('acme/progress', { params: P }, params => { ... });
+client.setNotificationHandler('acme/progress', { params: P }, (params, notification) => { ... });
 ```
 
+The 3-arg notification handler receives the raw notification as its second argument, so `_meta` is recoverable via `notification.params?._meta`.
+
 To send a custom-method request, pass a result schema as the second argument to `request()` (and `ctx.mcpReq.send()`):
 
 ```typescript

docs/migration.md

@@ -393,6 +393,8 @@ server.setRequestHandler('acme/search', { params: SearchParams, result: SearchRe
 
 The handler receives the parsed `params` directly (not the full request envelope). `_meta` is stripped before validation and is available as `ctx.mcpReq._meta`. Supplying `result` types the handler's return value; omit it to return any `Result`.
 
+For `setNotificationHandler`, the 3-arg handler is `(params, notification) => void`. The raw notification is the second argument, so `_meta` is recoverable via `notification.params?._meta`.
+
 #### Sending custom-method requests
 
 `request()` and `ctx.mcpReq.send()` accept a result schema as the second argument; for custom methods this is required:

examples/client/src/customMethodExample.ts

@@ -2,7 +2,7 @@
  * Custom (non-spec) method example: a client that sends `acme/search` and
  * listens for `acme/searchProgress` notifications.
  *
- * Run after starting `examples/server/src/customMethodExample.ts`.
+ * Build `examples/server` first; this client spawns the server via stdio.
  */
 import { Client, StdioClientTransport } from '@modelcontextprotocol/client';
 import { z } from 'zod/v4';

examples/server/src/customMethodExample.ts

@@ -2,7 +2,7 @@
  * Custom (non-spec) method example: a server that handles a vendor-prefixed
  * `acme/search` request and emits `acme/searchProgress` notifications.
  *
- * Run alongside `examples/client/src/customMethodExample.ts`.
+ * Spawned via stdio by `examples/client/src/customMethodExample.ts`; do not run standalone.
  */
 import { McpServer, StdioServerTransport } from '@modelcontextprotocol/server';
 import { z } from 'zod/v4';

packages/core/src/exports/public/index.ts

@@ -138,7 +138,7 @@ export { isTerminal } from '../../experimental/tasks/interfaces.js';
 export { InMemoryTaskMessageQueue, InMemoryTaskStore } from '../../experimental/tasks/stores/inMemory.js';
 
 // Validator types and classes
-export type { StandardSchemaWithJSON } from '../../util/standardSchema.js';
+export type { StandardSchemaV1, StandardSchemaWithJSON } from '../../util/standardSchema.js';
 export { AjvJsonSchemaValidator } from '../../validators/ajvProvider.js';
 export type { CfWorkerSchemaDraft } from '../../validators/cfWorkerProvider.js';
 // fromJsonSchema is intentionally NOT exported here — the server and client packages

packages/core/src/shared/protocol.ts

@@ -1152,12 +1152,12 @@ export abstract class Protocol<ContextT extends BaseContext> {
     setNotificationHandler<P extends StandardSchemaV1>(
         method: string,
         schemas: { params: P },
-        handler: (params: StandardSchemaV1.InferOutput<P>) => void | Promise<void>
+        handler: (params: StandardSchemaV1.InferOutput<P>, notification: Notification) => void | Promise<void>
     ): void;
     setNotificationHandler(
         method: string,
         schemasOrHandler: { params: StandardSchemaV1 } | ((notification: unknown) => void | Promise<void>),
-        maybeHandler?: (params: unknown) => void | Promise<void>
+        maybeHandler?: (params: unknown, notification: Notification) => void | Promise<void>
     ): void {
         if (typeof schemasOrHandler === 'function') {
             const schema = getNotificationSchema(method);
@@ -1180,7 +1180,7 @@ export abstract class Protocol<ContextT extends BaseContext> {
             if (!parsed.success) {
                 throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Invalid params for notification ${method}: ${parsed.error}`);
             }
-            await maybeHandler(parsed.data);
+            await maybeHandler(parsed.data, notification);
         });
     }
 

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

@@ -112,6 +112,20 @@ describe('Protocol custom-method support', () => {
             await new Promise(r => setTimeout(r, 0));
             expect(seen).toEqual([{ stage: 'fetch', pct: 0.5 }]);
         });
+
+        it('passes the raw notification (with _meta) as the second handler argument', async () => {
+            const [a, b] = await pair();
+            const Strict = z.strictObject({ stage: z.string() });
+            let seenMeta: unknown;
+            b.setNotificationHandler('acme/searchProgress', { params: Strict }, (params, notification) => {
+                expect(params).toEqual({ stage: 'fetch' });
+                seenMeta = notification.params?._meta;
+            });
+
+            await a.notification({ method: 'acme/searchProgress', params: { stage: 'fetch', _meta: { traceId: 't1' } } });
+            await new Promise(r => setTimeout(r, 0));
+            expect(seenMeta).toEqual({ traceId: 't1' });
+        });
     });
 
     describe('request() schema overload', () => {