refactor: replace RequestHandlerExtra with structured context types (#1467)

Author: felixweinberger

CLAUDE.md

@@ -144,37 +144,51 @@ 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 `BaseContext` with `signal`, `sessionId`, `sendNotification`, `sendRequest`, etc.
+    - Calls `buildContext()` to let subclasses enrich the context (e.g., Server adds `requestInfo`)
     - Invokes handler, sends JSON-RPC response back via transport
 4. **Handler** was registered via `setRequestHandler('method', handler)`
 
 ### Handler Registration
 
 ```typescript
 // In Client (for server→client requests like sampling, elicitation)
-client.setRequestHandler('sampling/createMessage', async (request, extra) => {
+client.setRequestHandler('sampling/createMessage', async (request, ctx) => {
   // Handle sampling request from server
   return { role: "assistant", content: {...}, model: "..." };
 });
 
 // In Server (for client→server requests like tools/call)
-server.setRequestHandler('tools/call', async (request, extra) => {
+server.setRequestHandler('tools/call', async (request, ctx) => {
   // Handle tool call from client
   return { content: [...] };
 });
 ```
 
-### Request Handler Extra
+### Request Handler Context
+
+The `ctx` parameter in handlers provides a structured context:
+
+**`BaseContext`** (common to both Server and Client), fields organized into nested groups:
+
+- `sessionId?`: Transport session identifier
+- `mcpReq`: Request-level concerns
+  - `id`: JSON-RPC message ID
+  - `method`: Request method string (e.g., 'tools/call')
+  - `_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
+
+**`ServerContext`** extends `BaseContext.mcpReq` and `BaseContext.http?` via type intersection:
 
-The `extra` parameter in handlers (`RequestHandlerExtra`) provides:
+- `mcpReq` adds: `log(level, data, logger?)`, `elicitInput(params, options?)`, `requestSampling(params, options?)`
+- `http?` adds: `req?` (HTTP request info), `closeSSE?`, `closeStandaloneSSE?`
 
-- `signal`: AbortSignal for cancellation
-- `sessionId`: Transport session identifier
-- `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)
+**`ClientContext`** is currently identical to `BaseContext`.
 
 ### Capability Checking
 

docs/migration-SKILL.md

@@ -297,7 +297,7 @@ extra.requestInfo?.headers['mcp-session-id']
 
 // v2: Headers object, .get() access
 headers: new Headers({ 'Authorization': 'Bearer token' })
-extra.requestInfo?.headers.get('mcp-session-id')
+ctx.http?.req?.headers.get('mcp-session-id')
 ```
 
 ## 8. Removed Server Features
@@ -366,11 +366,41 @@ Schema to method string mapping:
 
 Request/notification params remain fully typed. Remove unused schema imports after migration.
 
-## 10. Client Behavioral Changes
+## 10. Request Handler Context Types
+
+`RequestHandlerExtra` → structured context types with nested groups. Rename `extra` → `ctx` in all handler callbacks.
+
+| v1 | v2 |
+|----|-----|
+| `RequestHandlerExtra` | `ServerContext` (server) / `ClientContext` (client) / `BaseContext` (base) |
+| `extra` (param name) | `ctx` |
+| `extra.signal` | `ctx.mcpReq.signal` |
+| `extra.requestId` | `ctx.mcpReq.id` |
+| `extra._meta` | `ctx.mcpReq._meta` |
+| `extra.sendRequest(...)` | `ctx.mcpReq.send(...)` |
+| `extra.sendNotification(...)` | `ctx.mcpReq.notify(...)` |
+| `extra.authInfo` | `ctx.http?.authInfo` |
+| `extra.sessionId` | `ctx.sessionId` |
+| `extra.requestInfo` | `ctx.http?.req` (only `ServerContext`) |
+| `extra.closeSSEStream` | `ctx.http?.closeSSE` (only `ServerContext`) |
+| `extra.closeStandaloneSSEStream` | `ctx.http?.closeStandaloneSSE` (only `ServerContext`) |
+| `extra.taskStore` | `ctx.task?.store` |
+| `extra.taskId` | `ctx.task?.id` |
+| `extra.taskRequestedTtl` | `ctx.task?.requestedTtl` |
+
+`ServerContext` convenience methods (new in v2, no v1 equivalent):
+
+| Method | Description | Replaces |
+|--------|-------------|----------|
+| `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)
@@ -390,7 +420,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

@@ -156,7 +156,7 @@ const transport = new StreamableHTTPClientTransport(url, {
 });
 
 // Reading headers in a request handler
-const sessionId = extra.requestInfo?.headers.get('mcp-session-id');
+const sessionId = ctx.http?.req?.headers.get('mcp-session-id');
 ```
 
 ### `McpServer.tool()`, `.prompt()`, `.resource()` removed
@@ -381,6 +381,83 @@ import { JSONRPCError, ResourceReference, isJSONRPCError } from '@modelcontextpr
 import { JSONRPCErrorResponse, ResourceTemplateReference, isJSONRPCErrorResponse } from '@modelcontextprotocol/core';
 ```
 
+### Request handler context types
+
+The `RequestHandlerExtra` type has been replaced with a structured context type hierarchy using nested groups:
+
+| v1 | v2 |
+|----|-----|
+| `RequestHandlerExtra` (flat, all fields) | `ServerContext` (server handlers) or `ClientContext` (client handlers) |
+| `extra` parameter name | `ctx` parameter name |
+| `extra.signal` | `ctx.mcpReq.signal` |
+| `extra.requestId` | `ctx.mcpReq.id` |
+| `extra._meta` | `ctx.mcpReq._meta` |
+| `extra.sendRequest(...)` | `ctx.mcpReq.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`) |
+| `extra.closeStandaloneSSEStream` | `ctx.http?.closeStandaloneSSE` (only on `ServerContext`) |
+| `extra.sessionId` | `ctx.sessionId` |
+| `extra.taskStore` | `ctx.task?.store` |
+| `extra.taskId` | `ctx.task?.id` |
+| `extra.taskRequestedTtl` | `ctx.task?.requestedTtl` |
+
+**Before (v1):**
+
+```typescript
+server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+  const headers = extra.requestInfo?.headers;
+  const taskStore = extra.taskStore;
+  await extra.sendNotification({ method: 'notifications/progress', params: { progressToken: 'abc', progress: 50, total: 100 } });
+  return { content: [{ type: 'text', text: 'result' }] };
+});
+```
+
+**After (v2):**
+
+```typescript
+server.setRequestHandler('tools/call', async (request, ctx) => {
+  const headers = ctx.http?.req?.headers;
+  const taskStore = ctx.task?.store;
+  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()`, `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`
+
+`BaseContext` is the common base type shared by both `ServerContext` and `ClientContext`. `ServerContext` extends each group with server-specific additions via type intersection.
+
+`ServerContext` also provides convenience methods for common server→client operations:
+
+```typescript
+server.setRequestHandler('tools/call', async (request, ctx) => {
+  // Send a log message (respects client's log level filter)
+  await ctx.mcpReq.log('info', 'Processing tool call', 'my-logger');
+
+  // Request client to sample an LLM
+  const samplingResult = await ctx.mcpReq.requestSampling({
+    messages: [{ role: 'user', content: { type: 'text', text: 'Hello' } }],
+    maxTokens: 100,
+  });
+
+  // Elicit user input via a form
+  const elicitResult = await ctx.mcpReq.elicitInput({
+    message: 'Please provide details',
+    requestedSchema: { type: 'object', properties: { name: { type: 'string' } } },
+  });
+
+  return { content: [{ type: 'text', text: 'done' }] };
+});
+```
+
+These replace the pattern of calling `server.sendLoggingMessage()`, `server.createMessage()`, and `server.elicitInput()` from within handlers.
+
 ### Error hierarchy refactoring
 
 The SDK now distinguishes between two types of errors:

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.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.http?.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.sessionId;
             if (!sessionId) {
                 throw new Error('Expected a Session ID');
             }

examples/server/src/jsonResponseStreamableHttp.ts

@@ -51,36 +51,18 @@ 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
-            );
+            await ctx.mcpReq.log('debug', `Starting multi-greet for ${name}`);
 
             await sleep(1000); // Wait 1 second before first greeting
 
-            await server.sendLoggingMessage(
-                {
-                    level: 'info',
-                    data: `Sending first greeting to ${name}`
-                },
-                extra.sessionId
-            );
+            await ctx.mcpReq.log('info', `Sending first greeting to ${name}`);
 
             await sleep(1000); // Wait another second before second greeting
 
-            await server.sendLoggingMessage(
-                {
-                    level: 'info',
-                    data: `Sending second greeting to ${name}`
-                },
-                extra.sessionId
-            );
+            await ctx.mcpReq.log('info', `Sending second greeting to ${name}`);
 
             return {
                 content: [

examples/server/src/simpleStatelessStreamableHttp.ts

@@ -49,20 +49,14 @@ 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;
 
             while (count === 0 || counter < count) {
                 counter++;
                 try {
-                    await server.sendLoggingMessage(
-                        {
-                            level: 'info',
-                            data: `Periodic notification #${counter} at ${new Date().toISOString()}`
-                        },
-                        extra.sessionId
-                    );
+                    await ctx.mcpReq.log('info', `Periodic notification #${counter} at ${new Date().toISOString()}`);
                 } catch (error) {
                     console.error('Error sending notification:', error);
                 }