v2 Context API in callbacks

.changeset/hot-trees-sing.md

@@ -0,0 +1,12 @@
+---
+'@modelcontextprotocol/express': patch
+'@modelcontextprotocol/hono': patch
+'@modelcontextprotocol/node': patch
+'@modelcontextprotocol/eslint-config': patch
+'@modelcontextprotocol/test-integration': patch
+'@modelcontextprotocol/client': patch
+'@modelcontextprotocol/server': patch
+'@modelcontextprotocol/core': patch
+---
+
+add context API to tool, prompt, resource callbacks, linting

CLAUDE.md

@@ -136,37 +136,59 @@ When a request arrives from the remote side:
 2. **`Protocol.connect()`** routes to `_onrequest()`, `_onresponse()`, or `_onnotification()`
 3. **`Protocol._onrequest()`**:
     - Looks up handler in `_requestHandlers` map (keyed by method name)
-    - Creates `RequestHandlerExtra` with `signal`, `sessionId`, `sendNotification`, `sendRequest`
+    - Creates a context object (`ServerContext` or `ClientContext`) via `createRequestContext()`
     - Invokes handler, sends JSON-RPC response back via transport
 4. **Handler** was registered via `setRequestHandler(Schema, handler)`
 
 ### Handler Registration
 
 ```typescript
 // In Client (for server→client requests like sampling, elicitation)
-client.setRequestHandler(CreateMessageRequestSchema, async (request, extra) => {
+client.setRequestHandler(CreateMessageRequestSchema, async (request, ctx) => {
   // Handle sampling request from server
   return { role: "assistant", content: {...}, model: "..." };
 });
 
 // In Server (for client→server requests like tools/call)
-server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+server.setRequestHandler(CallToolRequestSchema, async (request, ctx) => {
   // Handle tool call from client
   return { content: [...] };
 });
 ```
 
-### Request Handler Extra
+### Request Handler Context
 
-The `extra` parameter in handlers (`RequestHandlerExtra`) provides:
+The `ctx` parameter in handlers provides a structured context with three layers:
 
-- `signal`: AbortSignal for cancellation
+**`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)
-- `requestId`: JSON-RPC message ID
-- `sendNotification(notification)`: Send related notification back
-- `sendRequest(request, schema)`: Send related request (for bidirectional flows)
-- `taskStore`: Task storage interface (if tasks enabled)
+- 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
 
 ### Capability Checking
 
@@ -197,7 +219,7 @@ const result = await server.createMessage({
 });
 
 // Client must have registered handler:
-client.setRequestHandler(CreateMessageRequestSchema, async (request, extra) => {
+client.setRequestHandler(CreateMessageRequestSchema, async (request, ctx) => {
   // Client-side LLM call
   return { role: "assistant", content: {...} };
 });
@@ -208,8 +230,8 @@ client.setRequestHandler(CreateMessageRequestSchema, async (request, extra) => {
 ### Request Handler Registration (Low-Level Server)
 
 ```typescript
-server.setRequestHandler(SomeRequestSchema, async (request, extra) => {
-    // extra contains sessionId, authInfo, sendNotification, etc.
+server.setRequestHandler(SomeRequestSchema, async (request, ctx) => {
+    // ctx provides mcpCtx, requestCtx, taskCtx, sendNotification, sendRequest
     return {
         /* result */
     };
@@ -219,7 +241,7 @@ server.setRequestHandler(SomeRequestSchema, async (request, extra) => {
 ### Tool Registration (High-Level McpServer)
 
 ```typescript
-mcpServer.tool('tool-name', { param: z.string() }, async ({ param }, extra) => {
+mcpServer.tool('tool-name', { param: z.string() }, async ({ param }, ctx) => {
     return { content: [{ type: 'text', text: 'result' }] };
 });
 ```

examples/client/src/simpleStreamableHttp.ts

@@ -271,10 +271,12 @@ async function connect(url?: string): Promise<void> {
         };
 
         // Set up elicitation request handler with proper validation
-        client.setRequestHandler(ElicitRequestSchema, async request => {
+        client.setRequestHandler(ElicitRequestSchema, async (request, ctx) => {
             if (request.params.mode !== 'form') {
                 throw new McpError(ErrorCode.InvalidParams, `Unsupported elicitation mode: ${request.params.mode}`);
             }
+
+            console.log(`${ctx.mcpCtx.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

@@ -46,12 +46,12 @@ const getServer = () => {
                 cartId: z.string().describe('The ID of the cart to confirm')
             }
         },
-        async ({ cartId }, extra): Promise<CallToolResult> => {
+        async ({ cartId }, ctx): Promise<CallToolResult> => {
             /*
         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 = extra.sessionId;
+            const sessionId = ctx.mcpCtx.sessionId;
             if (!sessionId) {
                 throw new Error('Expected a Session ID');
             }
@@ -79,15 +79,15 @@ const getServer = () => {
                 param1: z.string().describe('First parameter')
             }
         },
-        async (_, extra): Promise<CallToolResult> => {
+        async (_, ctx): Promise<CallToolResult> => {
             /*
         In a real world scenario, there would be some logic here to check if we already have a valid access token for the user.
-        Auth info (with a subject or `sub` claim) can be typically be found in `extra.authInfo`.
+        Auth info (with a subject or `sub` claim) can be typically be found in `ctx.requestCtx.authInfo`.
         If we do, we can just return the result of the tool call.
         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 = extra.sessionId;
+            const sessionId = ctx.mcpCtx.sessionId;
             if (!sessionId) {
                 throw new Error('Expected a Session ID');
             }

examples/server/src/jsonResponseStreamableHttp.ts

@@ -51,15 +51,15 @@ const getServer = () => {
                 name: z.string().describe('Name to greet')
             }
         },
-        async ({ name }, extra): Promise<CallToolResult> => {
+        async ({ name }, ctx): Promise<CallToolResult> => {
             const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
 
             await server.sendLoggingMessage(
                 {
                     level: 'debug',
                     data: `Starting multi-greet for ${name}`
                 },
-                extra.sessionId
+                ctx.mcpCtx.sessionId
             );
 
             await sleep(1000); // Wait 1 second before first greeting
@@ -69,7 +69,7 @@ const getServer = () => {
                     level: 'info',
                     data: `Sending first greeting to ${name}`
                 },
-                extra.sessionId
+                ctx.mcpCtx.sessionId
             );
 
             await sleep(1000); // Wait another second before second greeting
@@ -79,7 +79,7 @@ const getServer = () => {
                     level: 'info',
                     data: `Sending second greeting to ${name}`
                 },
-                extra.sessionId
+                ctx.mcpCtx.sessionId
             );
 
             return {

examples/server/src/simpleStatelessStreamableHttp.ts

@@ -49,7 +49,7 @@ const getServer = () => {
                 count: z.number().describe('Number of notifications to send (0 for 100)').default(10)
             }
         },
-        async ({ interval, count }, extra): Promise<CallToolResult> => {
+        async ({ interval, count }, ctx): Promise<CallToolResult> => {
             const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
             let counter = 0;
 
@@ -61,7 +61,7 @@ const getServer = () => {
                             level: 'info',
                             data: `Periodic notification #${counter} at ${new Date().toISOString()}`
                         },
-                        extra.sessionId
+                        ctx.mcpCtx.sessionId
                     );
                 } catch (error) {
                     console.error('Error sending notification:', error);

examples/server/src/simpleStreamableHttp.ts

@@ -62,7 +62,15 @@ const getServer = () => {
                 name: z.string().describe('Name to greet')
             }
         },
-        async ({ name }): Promise<CallToolResult> => {
+        async ({ name }, ctx): Promise<CallToolResult> => {
+            await ctx.loggingNotification.log(
+                {
+                    level: 'debug',
+                    data: `Starting greet for ${name}`
+                },
+                ctx.mcpCtx.sessionId
+            );
+
             return {
                 content: [
                     {
@@ -88,15 +96,15 @@ const getServer = () => {
                 openWorldHint: false
             }
         },
-        async ({ name }, extra): Promise<CallToolResult> => {
+        async ({ name }, ctx): Promise<CallToolResult> => {
             const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
 
             await server.sendLoggingMessage(
                 {
                     level: 'debug',
                     data: `Starting multi-greet for ${name}`
                 },
-                extra.sessionId
+                ctx.mcpCtx.sessionId
             );
 
             await sleep(1000); // Wait 1 second before first greeting
@@ -106,7 +114,7 @@ const getServer = () => {
                     level: 'info',
                     data: `Sending first greeting to ${name}`
                 },
-                extra.sessionId
+                ctx.mcpCtx.sessionId
             );
 
             await sleep(1000); // Wait another second before second greeting
@@ -116,7 +124,7 @@ const getServer = () => {
                     level: 'info',
                     data: `Sending second greeting to ${name}`
                 },
-                extra.sessionId
+                ctx.mcpCtx.sessionId
             );
 
             return {
@@ -139,7 +147,7 @@ const getServer = () => {
                 infoType: z.enum(['contact', 'preferences', 'feedback']).describe('Type of information to collect')
             }
         },
-        async ({ infoType }, extra): Promise<CallToolResult> => {
+        async ({ infoType }, ctx): Promise<CallToolResult> => {
             let message: string;
             let requestedSchema: {
                 type: 'object';
@@ -238,8 +246,8 @@ const getServer = () => {
             }
 
             try {
-                // Use sendRequest through the extra parameter to elicit input
-                const result = await extra.sendRequest(
+                // Use sendRequest through the ctx parameter to elicit input
+                const result = await ctx.sendRequest(
                     {
                         method: 'elicitation/create',
                         params: {
@@ -302,7 +310,15 @@ const getServer = () => {
                 name: z.string().describe('Name to include in greeting')
             }
         },
-        async ({ name }): Promise<GetPromptResult> => {
+        async ({ name }, ctx): Promise<GetPromptResult> => {
+            await ctx.loggingNotification.log(
+                {
+                    level: 'debug',
+                    data: `Starting greeting template for ${name}`
+                },
+                ctx.mcpCtx.sessionId
+            );
+
             return {
                 messages: [
                     {
@@ -327,7 +343,7 @@ const getServer = () => {
                 count: z.number().describe('Number of notifications to send (0 for 100)').default(50)
             }
         },
-        async ({ interval, count }, extra): Promise<CallToolResult> => {
+        async ({ interval, count }, ctx): Promise<CallToolResult> => {
             const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
             let counter = 0;
 
@@ -339,7 +355,7 @@ const getServer = () => {
                             level: 'info',
                             data: `Periodic notification #${counter} at ${new Date().toISOString()}`
                         },
-                        extra.sessionId
+                        ctx.mcpCtx.sessionId
                     );
                 } catch (error) {
                     console.error('Error sending notification:', error);
@@ -389,7 +405,15 @@ const getServer = () => {
             description: 'First example file for ResourceLink demonstration',
             mimeType: 'text/plain'
         },
-        async (): Promise<ReadResourceResult> => {
+        async (_, ctx): Promise<ReadResourceResult> => {
+            await ctx.loggingNotification.log(
+                {
+                    level: 'debug',
+                    data: `Starting example file 1`
+                },
+                ctx.mcpCtx.sessionId
+            );
+
             return {
                 contents: [
                     {
@@ -484,10 +508,12 @@ const getServer = () => {
             }
         },
         {
-            async createTask({ duration }, { taskStore, taskRequestedTtl }) {
+            async createTask({ duration }, ctx) {
                 // Create the task
+                if (!ctx.taskCtx?.store) throw new Error('Task store not found');
+                const taskStore = ctx.taskCtx.store;
                 const task = await taskStore.createTask({
-                    ttl: taskRequestedTtl
+                    ttl: ctx.taskCtx.requestedTtl
                 });
 
                 // Simulate out-of-band work
@@ -508,11 +534,13 @@ const getServer = () => {
                     task
                 };
             },
-            async getTask(_args, { taskId, taskStore }) {
-                return await taskStore.getTask(taskId);
+            async getTask(_args, ctx) {
+                if (!ctx.taskCtx?.store) throw new Error('Task store not found');
+                return await ctx.taskCtx.store.getTask(ctx.taskCtx.id!);
             },
-            async getTaskResult(_args, { taskId, taskStore }) {
-                const result = await taskStore.getTaskResult(taskId);
+            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!);
                 return result as CallToolResult;
             }
         }