update context interface

Author: KKonstantinov

CLAUDE.md

@@ -158,37 +158,40 @@ server.setRequestHandler(CallToolRequestSchema, async (request, ctx) => {
 
 ### Request Handler Context
 
-The `ctx` parameter in handlers provides a structured context with three layers:
-
-**`ctx.mcpCtx`** - MCP-level context:
-
-- `requestId`: JSON-RPC message ID
-- `method`: The method being called
-- `_meta`: Request metadata
-- `sessionId`: Transport session identifier
-
-**`ctx.requestCtx`** - Request-level context:
-
-- `signal`: AbortSignal for cancellation
-- `authInfo`: Validated auth token info (if authenticated)
-- For server: `uri`, `headers`, `stream` (HTTP details)
-
-**`ctx.taskCtx`** - Task context (when tasks are enabled):
-
-- `id`: Current task ID (updates after `store.createTask()`)
-- `store`: Request-scoped task store (`RequestTaskStore`)
-- `requestedTtl`: Requested TTL for the task
-
-**Context methods**:
-
-- `ctx.sendNotification(notification)`: Send notification back
-- `ctx.sendRequest(request, schema)`: Send request (for bidirectional flows)
-
-For server contexts, additional helpers:
-
-- `ctx.loggingNotification(level, data, logger)`: Send logging notification
-- `ctx.requestSampling(params)`: Request sampling from client
-- `ctx.elicitInput(params)`: Request user input from client
+The `ctx` parameter in handlers provides a structured context with grouped fields:
+
+**Common structure (both Client and Server)**:
+
+- `ctx.sessionId`: Transport session identifier (top-level)
+- `ctx.mcpReq`: MCP protocol context
+  - `id`: JSON-RPC message ID
+  - `method`: The method being called
+  - `_meta`: Request metadata
+  - `signal`: AbortSignal for cancellation
+- `ctx.req`: Request context with authentication and send method
+  - `authInfo`: Validated auth token info (if authenticated)
+  - `send(request, schema, options?)`: Send request (for bidirectional flows)
+- `ctx.task`: Task context (when tasks are enabled)
+  - `id`: Current task ID (updates after `store.createTask()`)
+  - `store`: Request-scoped task store (`RequestTaskStore`)
+  - `requestedTtl`: Requested TTL for the task
+- `ctx.notification`: Notification context
+  - `send(notification)`: Send notification back
+
+**Server-specific additions**:
+
+- `ctx.req.raw`: Raw fetch Request object (access to URL, headers, etc.)
+- `ctx.notification`: Extended with logging methods
+  - `log(params)`: Send logging notification
+  - `debug(message, extraLogData?)`: Send debug log
+  - `info(message, extraLogData?)`: Send info log
+  - `warning(message, extraLogData?)`: Send warning log
+  - `error(message, extraLogData?)`: Send error log
+- `ctx.stream`: SSE stream control
+  - `closeSSE?()`: Close SSE stream for polling
+  - `closeStandaloneSSE?()`: Close standalone SSE stream
+- `ctx.requestSampling(params, options?)`: Request sampling from client
+- `ctx.elicitInput(params, options?)`: Request user input from client
 
 ### Capability Checking
 
@@ -231,7 +234,7 @@ client.setRequestHandler(CreateMessageRequestSchema, async (request, ctx) => {
 
 ```typescript
 server.setRequestHandler(SomeRequestSchema, async (request, ctx) => {
-    // ctx provides mcpCtx, requestCtx, taskCtx, sendNotification, sendRequest
+    // ctx provides mcpCtx, requestCtx, task, sendNotification, sendRequest
     return {
         /* result */
     };

examples/client/src/simpleStreamableHttp.ts

@@ -276,7 +276,7 @@ async function connect(url?: string): Promise<void> {
                 throw new McpError(ErrorCode.InvalidParams, `Unsupported elicitation mode: ${request.params.mode}`);
             }
 
-            console.log(`${ctx.mcpCtx.method} elicitation request received`);
+            console.log(`${ctx.mcpReq.method} elicitation request received`);
             console.log('\n🔔 Elicitation (form) Request Received:');
             console.log(`Message: ${request.params.message}`);
             console.log(`Related Task: ${request.params._meta?.[RELATED_TASK_META_KEY]?.taskId}`);

examples/server/src/elicitationUrlExample.ts

@@ -51,7 +51,7 @@ const getServer = () => {
         In a real world scenario, there would be some logic here to check if the user has the provided cartId.
         For the purposes of this example, we'll throw an error (-> elicits the client to open a URL to confirm payment)
         */
-            const sessionId = ctx.mcpCtx.sessionId;
+            const sessionId = ctx.sessionId;
             if (!sessionId) {
                 throw new Error('Expected a Session ID');
             }
@@ -87,7 +87,7 @@ const getServer = () => {
         If we don't, we can throw an ElicitationRequiredError to request the user to authenticate.
         For the purposes of this example, we'll throw an error (-> elicits the client to open a URL to authenticate).
       */
-            const sessionId = ctx.mcpCtx.sessionId;
+            const sessionId = ctx.sessionId;
             if (!sessionId) {
                 throw new Error('Expected a Session ID');
             }

examples/server/src/jsonResponseStreamableHttp.ts

@@ -59,7 +59,7 @@ const getServer = () => {
                     level: 'debug',
                     data: `Starting multi-greet for ${name}`
                 },
-                ctx.mcpCtx.sessionId
+                ctx.sessionId
             );
 
             await sleep(1000); // Wait 1 second before first greeting
@@ -69,7 +69,7 @@ const getServer = () => {
                     level: 'info',
                     data: `Sending first greeting to ${name}`
                 },
-                ctx.mcpCtx.sessionId
+                ctx.sessionId
             );
 
             await sleep(1000); // Wait another second before second greeting
@@ -79,7 +79,7 @@ const getServer = () => {
                     level: 'info',
                     data: `Sending second greeting to ${name}`
                 },
-                ctx.mcpCtx.sessionId
+                ctx.sessionId
             );
 
             return {

examples/server/src/simpleStatelessStreamableHttp.ts

@@ -61,7 +61,7 @@ const getServer = () => {
                             level: 'info',
                             data: `Periodic notification #${counter} at ${new Date().toISOString()}`
                         },
-                        ctx.mcpCtx.sessionId
+                        ctx.sessionId
                     );
                 } catch (error) {
                     console.error('Error sending notification:', error);

examples/server/src/simpleStreamableHttp.ts

@@ -63,12 +63,12 @@ const getServer = () => {
             }
         },
         async ({ name }, ctx): Promise<CallToolResult> => {
-            await ctx.loggingNotification.log(
+            await ctx.notification.log(
                 {
                     level: 'debug',
                     data: `Starting greet for ${name}`
                 },
-                ctx.mcpCtx.sessionId
+                ctx.sessionId
             );
 
             return {
@@ -104,7 +104,7 @@ const getServer = () => {
                     level: 'debug',
                     data: `Starting multi-greet for ${name}`
                 },
-                ctx.mcpCtx.sessionId
+                ctx.sessionId
             );
 
             await sleep(1000); // Wait 1 second before first greeting
@@ -114,7 +114,7 @@ const getServer = () => {
                     level: 'info',
                     data: `Sending first greeting to ${name}`
                 },
-                ctx.mcpCtx.sessionId
+                ctx.sessionId
             );
 
             await sleep(1000); // Wait another second before second greeting
@@ -124,7 +124,7 @@ const getServer = () => {
                     level: 'info',
                     data: `Sending second greeting to ${name}`
                 },
-                ctx.mcpCtx.sessionId
+                ctx.sessionId
             );
 
             return {
@@ -247,7 +247,7 @@ const getServer = () => {
 
             try {
                 // Use sendRequest through the ctx parameter to elicit input
-                const result = await ctx.sendRequest(
+                const result = await ctx.mcpReq.send(
                     {
                         method: 'elicitation/create',
                         params: {
@@ -311,12 +311,12 @@ const getServer = () => {
             }
         },
         async ({ name }, ctx): Promise<GetPromptResult> => {
-            await ctx.loggingNotification.log(
+            await ctx.notification.log(
                 {
                     level: 'debug',
                     data: `Starting greeting template for ${name}`
                 },
-                ctx.mcpCtx.sessionId
+                ctx.sessionId
             );
 
             return {
@@ -355,7 +355,7 @@ const getServer = () => {
                             level: 'info',
                             data: `Periodic notification #${counter} at ${new Date().toISOString()}`
                         },
-                        ctx.mcpCtx.sessionId
+                        ctx.sessionId
                     );
                 } catch (error) {
                     console.error('Error sending notification:', error);
@@ -406,12 +406,12 @@ const getServer = () => {
             mimeType: 'text/plain'
         },
         async (_, ctx): Promise<ReadResourceResult> => {
-            await ctx.loggingNotification.log(
+            await ctx.notification.log(
                 {
                     level: 'debug',
                     data: `Starting example file 1`
                 },
-                ctx.mcpCtx.sessionId
+                ctx.sessionId
             );
 
             return {
@@ -510,10 +510,10 @@ const getServer = () => {
         {
             async createTask({ duration }, ctx) {
                 // Create the task
-                if (!ctx.taskCtx?.store) throw new Error('Task store not found');
-                const taskStore = ctx.taskCtx.store;
+                if (!ctx.task?.store) throw new Error('Task store not found');
+                const taskStore = ctx.task.store;
                 const task = await taskStore.createTask({
-                    ttl: ctx.taskCtx.requestedTtl
+                    ttl: ctx.task.requestedTtl
                 });
 
                 // Simulate out-of-band work
@@ -535,12 +535,12 @@ const getServer = () => {
                 };
             },
             async getTask(_args, ctx) {
-                if (!ctx.taskCtx?.store) throw new Error('Task store not found');
-                return await ctx.taskCtx.store.getTask(ctx.taskCtx.id!);
+                if (!ctx.task?.store) throw new Error('Task store not found');
+                return await ctx.task.store.getTask(ctx.task.id!);
             },
             async getTaskResult(_args, ctx) {
-                if (!ctx.taskCtx?.store) throw new Error('Task store not found');
-                const result = await ctx.taskCtx.store.getTaskResult(ctx.taskCtx.id!);
+                if (!ctx.task?.store) throw new Error('Task store not found');
+                const result = await ctx.task.store.getTaskResult(ctx.task.id!);
                 return result as CallToolResult;
             }
         }

examples/server/src/simpleTaskInteractive.ts

@@ -531,7 +531,7 @@ const createServer = (): Server => {
             pollInterval: taskParams.pollInterval ?? 1000
         };
 
-        const task = await taskStore.createTask(taskOptions, ctx.mcpCtx.requestId, request, ctx.mcpCtx.sessionId);
+        const task = await taskStore.createTask(taskOptions, ctx.mcpReq.id, request, ctx.sessionId);
 
         console.log(`\n[Server] ${name} called, task created: ${task.taskId}`);
 
@@ -609,7 +609,7 @@ const createServer = (): Server => {
         activeTaskExecutions.set(task.taskId, {
             promise: taskExecution,
             server,
-            sessionId: ctx.mcpCtx.sessionId ?? ''
+            sessionId: ctx.sessionId ?? ''
         });
 
         return { task };
@@ -629,7 +629,7 @@ const createServer = (): Server => {
     server.setRequestHandler(GetTaskPayloadRequestSchema, async (request, ctx): Promise<GetTaskPayloadResult> => {
         const { taskId } = request.params;
         console.log(`[Server] tasks/result called for task ${taskId}`);
-        return taskResultHandler.handle(taskId, server, ctx.mcpCtx.sessionId ?? '');
+        return taskResultHandler.handle(taskId, server, ctx.sessionId ?? '');
     });
 
     return server;

examples/server/src/ssePollingExample.ts

@@ -16,7 +16,7 @@ import { randomUUID } from 'node:crypto';
 
 import { createMcpExpressApp } from '@modelcontextprotocol/express';
 import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
-import type { CallToolResult, ServerRequestContext } from '@modelcontextprotocol/server';
+import type { CallToolResult } from '@modelcontextprotocol/server';
 import { McpServer } from '@modelcontextprotocol/server';
 import cors from 'cors';
 import type { Request, Response } from 'express';
@@ -42,8 +42,7 @@ server.registerTool(
     },
     async (ctx): Promise<CallToolResult> => {
         const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
-        const sessionId = ctx.mcpCtx.sessionId;
-        const requestCtx = ctx.requestCtx as ServerRequestContext;
+        const sessionId = ctx.sessionId;
 
         console.log(`[${sessionId}] Starting long-task...`);
 
@@ -69,10 +68,10 @@ server.registerTool(
 
         // Server decides to disconnect the client to free resources
         // Client will reconnect via GET with Last-Event-ID after the transport's retryInterval
-        // Use requestCtx.stream.closeSSEStream callback - available when eventStore is configured
-        if (requestCtx.stream.closeSSEStream) {
+        // Use ctx.stream.closeSSE callback - available when eventStore is configured
+        if (ctx.http?.closeSSE) {
             console.log(`[${sessionId}] Closing SSE stream to trigger client polling...`);
-            requestCtx.stream.closeSSEStream();
+            ctx.http.closeSSE();
         }
 
         // Continue processing while client is disconnected

packages/client/src/client/client.ts

@@ -20,7 +20,6 @@ import type {
     ListResourceTemplatesRequest,
     ListToolsRequest,
     LoggingLevel,
-    McpContext,
     MessageExtraInfo,
     Notification,
     ProtocolOptions,
@@ -76,7 +75,7 @@ import {
 } from '@modelcontextprotocol/core';
 
 import { ExperimentalClientTasks } from '../experimental/tasks/client.js';
-import type { ClientContextInterface, ClientRequestContext } from './context.js';
+import type { ClientContextInterface } from './context.js';
 import { ClientContext } from './context.js';
 
 /**
@@ -505,17 +504,8 @@ export class Client<
         const { request, taskStore, relatedTaskId, taskCreationParams, abortController, capturedTransport, extra } = args;
         const sessionId = capturedTransport?.sessionId;
 
-        // Build the MCP context using the helper from Protocol
-        const mcpContext: McpContext = this.buildMcpContext({ request, sessionId });
-
-        // Build the client request context (minimal, no HTTP details - client-specific)
-        const requestCtx: ClientRequestContext = {
-            signal: abortController.signal,
-            authInfo: extra?.authInfo
-        };
-
         // Build the task context using the helper from Protocol
-        const taskCtx: TaskContext | undefined = this.buildTaskContext({
+        const task: TaskContext | undefined = this.buildTaskContext({
             taskStore,
             request,
             sessionId,
@@ -527,9 +517,19 @@ export class Client<
         return new ClientContext<RequestT, NotificationT, ResultT>({
             client: this,
             request,
-            mcpContext,
-            requestCtx,
-            task: taskCtx
+            sessionId,
+            mcpReq: {
+                id: request.id,
+                method: request.method,
+                _meta: request.params?._meta,
+                signal: abortController.signal
+            },
+            http: extra?.authInfo
+                ? {
+                      authInfo: extra?.authInfo
+                  }
+                : undefined,
+            task: task
         });
     }