refactor: move notification.send → mcpReq.notify, notification.log → mcpReq.log

All request-scoped operations now live under mcpReq:
send(), notify(), log(), elicitInput(), requestSampling().
The notification group is removed.

Author: felixweinberger

CLAUDE.md

@@ -179,17 +179,15 @@ The `ctx` parameter in handlers provides a structured context:
   - `_meta?`: Request metadata
   - `signal`: AbortSignal for cancellation
   - `send(request, schema, options?)`: Send related request (for bidirectional flows)
+  - `notify(notification)`: Send related notification back
 - `http?`: HTTP transport info (undefined for stdio)
   - `authInfo?`: Validated auth token info
 - `task?`: Task context (`{ id?, store, requestedTtl? }`) when task storage is configured
-- `notification`: Outbound notifications
-  - `send(notification)`: Send related notification back
 
-**`ServerContext`** extends each `BaseContext` group via type intersection:
+**`ServerContext`** extends `BaseContext.mcpReq` and `BaseContext.http?` via type intersection:
 
-- `mcpReq` adds: `elicitInput(params, options?)`, `requestSampling(params, options?)`
+- `mcpReq` adds: `log(level, data, logger?)`, `elicitInput(params, options?)`, `requestSampling(params, options?)`
 - `http?` adds: `req?` (HTTP request info), `closeSSE?`, `closeStandaloneSSE?`
-- `notification` adds: `log(level, data, logger?)`
 
 **`ClientContext`** is currently identical to `BaseContext`.
 

docs/migration-SKILL.md

@@ -367,7 +367,7 @@ Request/notification params remain fully typed. Remove unused schema imports aft
 | `extra.requestId` | `ctx.mcpReq.id` |
 | `extra._meta` | `ctx.mcpReq._meta` |
 | `extra.sendRequest(...)` | `ctx.mcpReq.send(...)` |
-| `extra.sendNotification(...)` | `ctx.notification.send(...)` |
+| `extra.sendNotification(...)` | `ctx.mcpReq.notify(...)` |
 | `extra.authInfo` | `ctx.http?.authInfo` |
 | `extra.sessionId` | `ctx.sessionId` |
 | `extra.requestInfo` | `ctx.http?.req` (only `ServerContext`) |
@@ -381,15 +381,15 @@ Request/notification params remain fully typed. Remove unused schema imports aft
 
 | Method | Description | Replaces |
 |--------|-------------|----------|
-| `ctx.notification.log(level, data, logger?)` | Send log notification (respects client's level filter) | `server.sendLoggingMessage(...)` from within handler |
+| `ctx.mcpReq.log(level, data, logger?)` | Send log notification (respects client's level filter) | `server.sendLoggingMessage(...)` from within handler |
 | `ctx.mcpReq.elicitInput(params, options?)` | Elicit user input (form or URL) | `server.elicitInput(...)` from within handler |
 | `ctx.mcpReq.requestSampling(params, options?)` | Request LLM sampling from client | `server.createMessage(...)` from within handler |
 
 ## 11. Client Behavioral Changes
 
 `Client.listPrompts()`, `listResources()`, `listResourceTemplates()`, `listTools()` now return empty results when the server lacks the corresponding capability (instead of sending the request). Set `enforceStrictCapabilities: true` in `ClientOptions` to throw an error instead.
 
-## 11. Runtime-Specific JSON Schema Validators (Enhancement)
+## 12. Runtime-Specific JSON Schema Validators (Enhancement)
 
 The SDK now auto-selects the appropriate JSON Schema validator based on runtime:
 - Node.js → `AjvJsonSchemaValidator` (no change from v1)
@@ -409,7 +409,7 @@ new McpServer({ name: 'server', version: '1.0.0' }, {});
 
 Access validators via `_shims` export: `import { DefaultJsonSchemaValidator } from '@modelcontextprotocol/server/_shims';`
 
-## 12. Migration Steps (apply in this order)
+## 13. Migration Steps (apply in this order)
 
 1. Update `package.json`: `npm uninstall @modelcontextprotocol/sdk`, install the appropriate v2 packages
 2. Replace all imports from `@modelcontextprotocol/sdk/...` using the import mapping tables (sections 3-4), including `StreamableHTTPServerTransport` → `NodeStreamableHTTPServerTransport`

docs/migration.md

@@ -356,7 +356,7 @@ The `RequestHandlerExtra` type has been replaced with a structured context type
 | `extra.requestId` | `ctx.mcpReq.id` |
 | `extra._meta` | `ctx.mcpReq._meta` |
 | `extra.sendRequest(...)` | `ctx.mcpReq.send(...)` |
-| `extra.sendNotification(...)` | `ctx.notification.send(...)` |
+| `extra.sendNotification(...)` | `ctx.mcpReq.notify(...)` |
 | `extra.authInfo` | `ctx.http?.authInfo` |
 | `extra.requestInfo` | `ctx.http?.req` (only on `ServerContext`) |
 | `extra.closeSSEStream` | `ctx.http?.closeSSE` (only on `ServerContext`) |
@@ -383,17 +383,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
 server.setRequestHandler('tools/call', async (request, ctx) => {
   const headers = ctx.http?.req?.headers;
   const taskStore = ctx.task?.store;
-  await ctx.notification.send({ method: 'notifications/progress', params: { progressToken: 'abc', progress: 50, total: 100 } });
+  await ctx.mcpReq.notify({ method: 'notifications/progress', params: { progressToken: 'abc', progress: 50, total: 100 } });
   return { content: [{ type: 'text', text: 'result' }] };
 });
 ```
 
 Context fields are organized into 4 groups:
 
-- **`mcpReq`** — request-level concerns: `id`, `method`, `_meta`, `signal`, `send()`, plus server-only `elicitInput()` and `requestSampling()`
+- **`mcpReq`** — request-level concerns: `id`, `method`, `_meta`, `signal`, `send()`, `notify()`, plus server-only `log()`, `elicitInput()`, and `requestSampling()`
 - **`http?`** — HTTP transport concerns (undefined for stdio): `authInfo`, plus server-only `req`, `closeSSE`, `closeStandaloneSSE`
 - **`task?`** — task lifecycle: `id`, `store`, `requestedTtl`
-- **`notification`** — outbound notifications: `send()`, plus server-only `log()`
 
 `BaseContext` is the common base type shared by both `ServerContext` and `ClientContext`. `ServerContext` extends each group with server-specific additions via type intersection.
 
@@ -402,7 +401,7 @@ Context fields are organized into 4 groups:
 ```typescript
 server.setRequestHandler('tools/call', async (request, ctx) => {
   // Send a log message (respects client's log level filter)
-  await ctx.notification.log('info', 'Processing tool call', 'my-logger');
+  await ctx.mcpReq.log('info', 'Processing tool call', 'my-logger');
 
   // Request client to sample an LLM
   const samplingResult = await ctx.mcpReq.requestSampling({

packages/core/src/shared/protocol.ts

@@ -303,6 +303,13 @@ export type BaseContext<SendRequestT extends Request, SendNotificationT extends
          * This is used by certain transports to correctly associate related messages.
          */
         send: <U extends AnySchema>(request: SendRequestT, resultSchema: U, options?: TaskRequestOptions) => Promise<SchemaOutput<U>>;
+
+        /**
+         * Sends a notification that relates to the current request being handled.
+         *
+         * This is used by certain transports to correctly associate related messages.
+         */
+        notify: (notification: SendNotificationT) => Promise<void>;
     };
 
     /**
@@ -319,18 +326,6 @@ export type BaseContext<SendRequestT extends Request, SendNotificationT extends
      * Task context, available when task storage is configured.
      */
     task?: TaskContext;
-
-    /**
-     * Outbound notification sending.
-     */
-    notification: {
-        /**
-         * Sends a notification that relates to the current request being handled.
-         *
-         * This is used by certain transports to correctly associate related messages.
-         */
-        send: (notification: SendNotificationT) => Promise<void>;
-    };
 };
 
 /**
@@ -341,6 +336,12 @@ export type ServerContext<
     SendNotificationT extends Notification = ServerNotification
 > = BaseContext<SendRequestT, SendNotificationT> & {
     mcpReq: {
+        /**
+         * Send a log message notification to the client.
+         * Respects the client's log level filter set via logging/setLevel.
+         */
+        log: (level: LoggingLevel, data: unknown, logger?: string) => Promise<void>;
+
         /**
          * Send an elicitation request to the client, requesting user input.
          */
@@ -373,14 +374,6 @@ export type ServerContext<
          */
         closeStandaloneSSE?: () => void;
     };
-
-    notification: {
-        /**
-         * Send a log message notification to the client.
-         * Respects the client's log level filter set via logging/setLevel.
-         */
-        log: (level: LoggingLevel, data: unknown, logger?: string) => Promise<void>;
-    };
 };
 
 /**
@@ -841,19 +834,17 @@ export abstract class Protocol<
                         await taskStore.updateTaskStatus(effectiveTaskId, 'input_required');
                     }
                     return await this.request(r, resultSchema, requestOptions);
-                }
-            },
-            http: extra?.authInfo ? { authInfo: extra.authInfo } : undefined,
-            task,
-            notification: {
-                send: async notification => {
+                },
+                notify: async notification => {
                     const notificationOptions: NotificationOptions = { relatedRequestId: request.id };
                     if (relatedTaskId) {
                         notificationOptions.relatedTask = { taskId: relatedTaskId };
                     }
                     await this.notification(notification, notificationOptions);
                 }
-            }
+            },
+            http: extra?.authInfo ? { authInfo: extra.authInfo } : undefined,
+            task
         };
         const ctx = this.buildContext(baseCtx, extra);
 

packages/core/test/shared/protocol.test.ts

@@ -2081,8 +2081,8 @@ describe('Task-based execution', () => {
 
             // Set up a handler that uses sendRequest and sendNotification
             serverProtocol.setRequestHandler('tools/call', async (_request, ctx) => {
-                // Send a notification using the ctx.notification.send
-                await ctx.notification.send({
+                // Send a notification using the ctx.mcpReq.notify
+                await ctx.mcpReq.notify({
                     method: 'notifications/message',
                     params: { level: 'info', data: 'test' }
                 });

packages/server/src/server/server.ts

@@ -167,6 +167,7 @@ export class Server<
             ...ctx,
             mcpReq: {
                 ...ctx.mcpReq,
+                log: (level, data, logger) => this.sendLoggingMessage({ level, data, logger }),
                 elicitInput: (params, options) => this.elicitInput(params, options),
                 requestSampling: (params, options) => this.createMessage(params, options)
             },
@@ -175,10 +176,6 @@ export class Server<
                 req: transportInfo?.requestInfo,
                 closeSSE: transportInfo?.closeSSEStream,
                 closeStandaloneSSE: transportInfo?.closeStandaloneSSEStream
-            },
-            notification: {
-                ...ctx.notification,
-                log: (level, data, logger) => this.sendLoggingMessage({ level, data, logger })
             }
         };
     }

test/conformance/src/everythingServer.ts

@@ -203,7 +203,7 @@ function createMcpServer() {
             inputSchema: {}
         },
         async (_args, ctx): Promise<CallToolResult> => {
-            await ctx.notification.send({
+            await ctx.mcpReq.notify({
                 method: 'notifications/message',
                 params: {
                     level: 'info',
@@ -212,7 +212,7 @@ function createMcpServer() {
             });
             await new Promise(resolve => setTimeout(resolve, 50));
 
-            await ctx.notification.send({
+            await ctx.mcpReq.notify({
                 method: 'notifications/message',
                 params: {
                     level: 'info',
@@ -221,7 +221,7 @@ function createMcpServer() {
             });
             await new Promise(resolve => setTimeout(resolve, 50));
 
-            await ctx.notification.send({
+            await ctx.mcpReq.notify({
                 method: 'notifications/message',
                 params: {
                     level: 'info',
@@ -244,7 +244,7 @@ function createMcpServer() {
         async (_args, ctx): Promise<CallToolResult> => {
             const progressToken = ctx.mcpReq._meta?.progressToken ?? 0;
             console.log('Progress token:', progressToken);
-            await ctx.notification.send({
+            await ctx.mcpReq.notify({
                 method: 'notifications/progress',
                 params: {
                     progressToken,
@@ -255,7 +255,7 @@ function createMcpServer() {
             });
             await new Promise(resolve => setTimeout(resolve, 50));
 
-            await ctx.notification.send({
+            await ctx.mcpReq.notify({
                 method: 'notifications/progress',
                 params: {
                     progressToken,
@@ -266,7 +266,7 @@ function createMcpServer() {
             });
             await new Promise(resolve => setTimeout(resolve, 50));
 
-            await ctx.notification.send({
+            await ctx.mcpReq.notify({
                 method: 'notifications/progress',
                 params: {
                     progressToken,

test/integration/test/server/mcp.test.ts

@@ -121,7 +121,7 @@ describe.each(zodTestMatrix)('$zodVersionLabel', (entry: ZodMatrixEntry) => {
                     if (progressToken) {
                         // Send progress notification for each step
                         for (let i = 1; i <= steps; i++) {
-                            await ctx.notification.send({
+                            await ctx.mcpReq.notify({
                                 method: 'notifications/progress',
                                 params: {
                                     progressToken,
@@ -1444,7 +1444,7 @@ describe.each(zodTestMatrix)('$zodVersionLabel', (entry: ZodMatrixEntry) => {
             });
 
             mcpServer.registerTool('test-tool', {}, async ctx => {
-                await ctx.notification.send({
+                await ctx.mcpReq.notify({
                     method: 'notifications/message',
                     params: { level: 'debug', data: loggingMessage }
                 });

test/integration/test/taskResumability.test.ts

@@ -70,7 +70,7 @@ describe.each(zodTestMatrix)('$zodVersionLabel', (entry: ZodMatrixEntry) => {
                 },
                 async ({ message }, ctx) => {
                     // Send notification immediately
-                    await ctx.notification.send({
+                    await ctx.mcpReq.notify({
                         method: 'notifications/message',
                         params: {
                             level: 'info',
@@ -97,7 +97,7 @@ describe.each(zodTestMatrix)('$zodVersionLabel', (entry: ZodMatrixEntry) => {
                 async ({ count, interval }, ctx) => {
                     // Send notifications at specified intervals
                     for (let i = 0; i < count; i++) {
-                        await ctx.notification.send({
+                        await ctx.mcpReq.notify({
                             method: 'notifications/message',
                             params: {
                                 level: 'info',