test(e2e): cover the per-request envelope on the handler context

Author: felixweinberger

test/e2e/requirements.ts

@@ -114,6 +114,20 @@ export const REQUIREMENTS: Record<string, Requirement> = {
         transports: STATEFUL_TRANSPORTS,
         note: 'Under stateless hosting each request is served by a new server instance, so state set up earlier in the session cannot be observed.'
     },
+    'protocol:envelope:ctx-version-readable': {
+        source: 'sdk',
+        behavior:
+            'A request handler can read the protocol version governing the current request from its context (ctx.mcpReq.protocolVersion); on a 2025 connection it equals the initialize-negotiated version.',
+        transports: STATEFUL_TRANSPORTS,
+        note: "Groundwork for SEP-2575's per-request envelope. Today the version is sourced from the initialize handshake, so a stateless host (fresh server per request, no retained handshake) would read the pre-initialize default rather than the negotiated version."
+    },
+    'protocol:envelope:ctx-capabilities-readable': {
+        source: 'sdk',
+        behavior:
+            "A server request handler can read the calling client's declared capabilities and implementation info from its context (ctx.client.capabilities / ctx.client.info); on a 2025 connection these equal what the client sent at initialize.",
+        transports: STATEFUL_TRANSPORTS,
+        note: 'Per-request counterpart of Server.getClientCapabilities()/getClientVersion(); under the 2026 revision (no handshake) the per-request form becomes the only way to read these. The structural supersession is recorded when 2026 connections become possible. Stateless hosting serves each request from a fresh server that never processed initialize, so the handshake-sourced facts are not observable there.'
+    },
 
     // Protocol primitives: cancellation, timeout, progress, errors, _meta
 

test/e2e/scenarios/handler-context.test.ts

@@ -10,11 +10,25 @@
  */
 
 import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
-import type { CreateMessageRequest, ElicitRequest, ElicitRequestFormParams, LoggingLevel } from '@modelcontextprotocol/server';
-import { McpServer } from '@modelcontextprotocol/server';
+import type {
+    ClientCapabilities,
+    CreateMessageRequest,
+    ElicitRequest,
+    ElicitRequestFormParams,
+    Implementation,
+    LoggingLevel
+} from '@modelcontextprotocol/server';
+import { LATEST_PROTOCOL_VERSION, McpServer, SUPPORTED_PROTOCOL_VERSIONS } from '@modelcontextprotocol/server';
 import { expect, vi } from 'vitest';
 import { z } from 'zod/v4';
 
+/** A supported protocol version other than the latest, used to prove the version reported is the negotiated one. */
+const OLDER_SUPPORTED_VERSION = (() => {
+    const older = SUPPORTED_PROTOCOL_VERSIONS.find(v => v !== LATEST_PROTOCOL_VERSION);
+    if (older === undefined) throw new Error('expected SUPPORTED_PROTOCOL_VERSIONS to include a version other than the latest');
+    return older;
+})();
+
 import { hostPerSession, wire } from '../helpers/index.js';
 import { verifies } from '../helpers/verifies.js';
 import type { TestArgs } from '../types.js';
@@ -165,3 +179,135 @@ verifies('hosting:context:web-request-headers', async (_args: TestArgs) => {
         await mcpHost.close();
     }
 });
+
+verifies(
+    'protocol:envelope:ctx-version-readable',
+    async ({ transport }: TestArgs) => {
+        let seenVersion: string | undefined;
+        const makeServer = () => {
+            const s = new McpServer({ name: 's', version: '0' });
+            s.registerTool('read-version', { inputSchema: z.object({}) }, (_args, ctx) => {
+                seenVersion = ctx.mcpReq.protocolVersion;
+                return { content: [{ type: 'text', text: ctx.mcpReq.protocolVersion }] };
+            });
+            return s;
+        };
+        const client = new Client({ name: 'c', version: '0' });
+
+        await using _ = await wire(transport, makeServer, client);
+        const result = await client.callTool({ name: 'read-version', arguments: {} });
+
+        // On a 2025 connection the governing version is the one negotiated at initialize.
+        expect(seenVersion).toBe(client.getNegotiatedProtocolVersion());
+        expect(result.content).toEqual([{ type: 'text', text: client.getNegotiatedProtocolVersion() }]);
+    },
+    { title: 'server handler reads negotiated version (default)' }
+);
+
+verifies(
+    'protocol:envelope:ctx-version-readable',
+    async ({ transport }: TestArgs) => {
+        let seenVersion: string | undefined;
+        const makeServer = () => {
+            const s = new McpServer({ name: 's', version: '0' });
+            s.registerTool('read-version', { inputSchema: z.object({}) }, (_args, ctx) => {
+                seenVersion = ctx.mcpReq.protocolVersion;
+                return { content: [{ type: 'text', text: ctx.mcpReq.protocolVersion }] };
+            });
+            return s;
+        };
+        // Pin the client to an older supported version so the governing version differs from the latest,
+        // proving the handler reads the actually-negotiated version rather than a constant.
+        const client = new Client({ name: 'c', version: '0' }, { supportedProtocolVersions: [OLDER_SUPPORTED_VERSION] });
+
+        await using _ = await wire(transport, makeServer, client);
+        await client.callTool({ name: 'read-version', arguments: {} });
+
+        expect(seenVersion).toBe(OLDER_SUPPORTED_VERSION);
+        expect(client.getNegotiatedProtocolVersion()).toBe(OLDER_SUPPORTED_VERSION);
+    },
+    { title: 'server handler reads negotiated version (pinned older)' }
+);
+
+verifies(
+    'protocol:envelope:ctx-version-readable',
+    async ({ transport }: TestArgs) => {
+        // BaseContext is shared by both roles: a client-side handler can read the governing version too.
+        let seenByClientHandler: string | undefined;
+        const makeServer = () => {
+            const s = new McpServer({ name: 's', version: '0' });
+            s.registerTool('ask', { inputSchema: z.object({}) }, async (_args, ctx) => {
+                const r = await ctx.mcpReq.requestSampling({
+                    messages: [{ role: 'user', content: { type: 'text', text: 'hi' } }],
+                    maxTokens: 10
+                });
+                const text = !Array.isArray(r.content) && r.content.type === 'text' ? r.content.text : '<unexpected>';
+                return { content: [{ type: 'text', text }] };
+            });
+            return s;
+        };
+        const client = new Client({ name: 'c', version: '0' }, { capabilities: { sampling: {} } });
+        client.setRequestHandler('sampling/createMessage', async (_req, ctx) => {
+            seenByClientHandler = ctx.mcpReq.protocolVersion;
+            return { model: 'stub', role: 'assistant', stopReason: 'endTurn', content: { type: 'text', text: 'ok' } };
+        });
+
+        await using _ = await wire(transport, makeServer, client);
+        await client.callTool({ name: 'ask', arguments: {} });
+
+        expect(seenByClientHandler).toBe(client.getNegotiatedProtocolVersion());
+    },
+    { title: 'client handler reads governing version' }
+);
+
+verifies(
+    'protocol:envelope:ctx-capabilities-readable',
+    async ({ transport }: TestArgs) => {
+        let seen: { capabilities: ClientCapabilities; info: Implementation | undefined } | undefined;
+        const makeServer = () => {
+            const s = new McpServer({ name: 's', version: '0' });
+            s.registerTool('read-client', { inputSchema: z.object({}) }, (_args, ctx) => {
+                seen = { capabilities: ctx.client.capabilities, info: ctx.client.info };
+                return { content: [{ type: 'text', text: 'ok' }] };
+            });
+            return s;
+        };
+        const declared: ClientCapabilities = { sampling: {}, roots: { listChanged: true } };
+        const clientInfo: Implementation = { name: 'declaring-client', version: '4.5.6' };
+        const client = new Client(clientInfo, { capabilities: declared });
+
+        await using _ = await wire(transport, makeServer, client);
+        await client.callTool({ name: 'read-client', arguments: {} });
+
+        // The handler sees exactly what the client declared at initialize.
+        expect(seen?.capabilities.sampling).toEqual({});
+        expect(seen?.capabilities.roots).toEqual({ listChanged: true });
+        expect(seen?.info).toEqual(clientInfo);
+    },
+    { title: 'declared capabilities and info' }
+);
+
+verifies(
+    'protocol:envelope:ctx-capabilities-readable',
+    async ({ transport }: TestArgs) => {
+        let seen: { capabilities: ClientCapabilities; info: Implementation | undefined } | undefined;
+        const makeServer = () => {
+            const s = new McpServer({ name: 's', version: '0' });
+            s.registerTool('read-client', { inputSchema: z.object({}) }, (_args, ctx) => {
+                seen = { capabilities: ctx.client.capabilities, info: ctx.client.info };
+                return { content: [{ type: 'text', text: 'ok' }] };
+            });
+            return s;
+        };
+        // A client that declares no optional capabilities yields a `{}`-shaped object, not undefined.
+        const clientInfo: Implementation = { name: 'bare-client', version: '0.0.1' };
+        const client = new Client(clientInfo);
+
+        await using _ = await wire(transport, makeServer, client);
+        await client.callTool({ name: 'read-client', arguments: {} });
+
+        expect(seen?.capabilities).toEqual({});
+        expect(seen?.info).toEqual(clientInfo);
+    },
+    { title: 'no optional capabilities yields {} shape' }
+);