feat(server): expose per-request client capabilities and info on the handler context

Author: felixweinberger

packages/server/src/server/server.ts

@@ -164,6 +164,12 @@ export class Server extends Protocol<ServerContext> {
                 elicitInput: (params, options) => this.elicitInput(params, options),
                 requestSampling: (params, options) => this.createMessage(params, options)
             },
+            // Sourced from the handshake state retained at initialize - the only source that exists today.
+            // Before the handshake completes (only `ping` is legal there), capabilities is `{}` and info undefined.
+            client: {
+                capabilities: this._clientCapabilities ?? {},
+                info: this._clientVersion
+            },
             http: hasHttpInfo
                 ? {
                       ...ctx.http,
@@ -442,13 +448,17 @@ export class Server extends Protocol<ServerContext> {
 
     /**
      * After initialization has completed, this will be populated with the client's reported capabilities.
+     *
+     * Inside a request handler, prefer `ctx.client.capabilities`, which reads the same facts per request.
      */
     getClientCapabilities(): ClientCapabilities | undefined {
         return this._clientCapabilities;
     }
 
     /**
      * After initialization has completed, this will be populated with information about the client's name and version.
+     *
+     * Inside a request handler, prefer `ctx.client.info`, which reads the same facts per request.
      */
     getClientVersion(): Implementation | undefined {
         return this._clientVersion;
@@ -459,7 +469,7 @@ export class Server extends Protocol<ServerContext> {
      * with the client (the version the server responded with during the initialize handshake), or
      * `undefined` before initialization.
      */
-    getNegotiatedProtocolVersion(): string | undefined {
+    override getNegotiatedProtocolVersion(): string | undefined {
         return this._negotiatedProtocolVersion;
     }
 

packages/server/test/server/server.test.ts

@@ -1,5 +1,7 @@
 import type { JSONRPCMessage, JSONRPCRequest } from '@modelcontextprotocol/core';
+import type { ClientCapabilities, Implementation, ServerContext } from '@modelcontextprotocol/core';
 import {
+    DEFAULT_NEGOTIATED_PROTOCOL_VERSION,
     InitializeResultSchema,
     InMemoryTransport,
     isJSONRPCResultResponse,
@@ -130,4 +132,117 @@ describe('Server', () => {
             await server.close();
         });
     });
+
+    describe('ctx.client / ctx.mcpReq.protocolVersion on the handler context', () => {
+        /**
+         * Connects the server, registers a ping handler that captures its ServerContext, drives the
+         * initialize handshake (with the given client capabilities/info), then sends a ping so the
+         * handler runs. Returns the captured context.
+         */
+        async function captureContextAfterInitialize(
+            server: Server,
+            requestedVersion: string,
+            clientCapabilities: ClientCapabilities,
+            clientInfo: Implementation
+        ): Promise<ServerContext> {
+            const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+            await server.connect(serverTransport);
+
+            let captured: ServerContext | undefined;
+            server.setRequestHandler('ping', async (_request, ctx) => {
+                captured = ctx;
+                return {};
+            });
+
+            await clientTransport.start();
+
+            const initResponse = new Promise<void>(resolve => {
+                clientTransport.onmessage = () => resolve();
+            });
+            await clientTransport.send({
+                jsonrpc: '2.0',
+                id: 1,
+                method: 'initialize',
+                params: { protocolVersion: requestedVersion, capabilities: clientCapabilities, clientInfo }
+            } as JSONRPCMessage);
+            await initResponse;
+
+            const pingResponse = new Promise<void>(resolve => {
+                clientTransport.onmessage = () => resolve();
+            });
+            await clientTransport.send({ jsonrpc: '2.0', id: 2, method: 'ping', params: {} } as JSONRPCMessage);
+            await pingResponse;
+
+            if (!captured) {
+                throw new Error('ping handler did not run');
+            }
+            return captured;
+        }
+
+        it('exposes the client capabilities and info the client declared at initialize', async () => {
+            const server = new Server({ name: 'test', version: '1.0.0' }, { capabilities: {} });
+            const clientCapabilities: ClientCapabilities = { sampling: {}, roots: { listChanged: true } };
+            const clientInfo: Implementation = { name: 'declaring-client', version: '2.3.4' };
+
+            const ctx = await captureContextAfterInitialize(server, LATEST_PROTOCOL_VERSION, clientCapabilities, clientInfo);
+
+            // The declared capabilities round-trip onto the context.
+            expect(ctx.client.capabilities.sampling).toEqual({});
+            expect(ctx.client.capabilities.roots).toEqual({ listChanged: true });
+            expect(ctx.client.info).toEqual(clientInfo);
+            // The per-request facts match the connection-scoped getters (same source of truth).
+            expect(ctx.client.capabilities).toEqual(server.getClientCapabilities());
+            expect(ctx.client.info).toEqual(server.getClientVersion());
+
+            await server.close();
+        });
+
+        it('exposes the negotiated protocol version, including a pinned older version', async () => {
+            const server = new Server({ name: 'test', version: '1.0.0' }, { capabilities: {} });
+
+            const ctx = await captureContextAfterInitialize(server, OLDER_SUPPORTED_VERSION, {}, { name: 'c', version: '1.0.0' });
+
+            expect(ctx.mcpReq.protocolVersion).toBe(OLDER_SUPPORTED_VERSION);
+            expect(ctx.mcpReq.protocolVersion).toBe(server.getNegotiatedProtocolVersion());
+
+            await server.close();
+        });
+
+        it('yields {}-shaped capabilities (not undefined) when the client declares no optional capabilities', async () => {
+            const server = new Server({ name: 'test', version: '1.0.0' }, { capabilities: {} });
+
+            const ctx = await captureContextAfterInitialize(server, LATEST_PROTOCOL_VERSION, {}, { name: 'c', version: '1.0.0' });
+
+            expect(ctx.client.capabilities).toEqual({});
+            expect(ctx.client.info).toEqual({ name: 'c', version: '1.0.0' });
+
+            await server.close();
+        });
+
+        it('pre-initialize: ping before the handshake gets {} capabilities, undefined info, and the default version', async () => {
+            const server = new Server({ name: 'test', version: '1.0.0' }, { capabilities: {} });
+            const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+            await server.connect(serverTransport);
+
+            let captured: ServerContext | undefined;
+            server.setRequestHandler('ping', async (_request, ctx) => {
+                captured = ctx;
+                return {};
+            });
+
+            await clientTransport.start();
+            const pingResponse = new Promise<void>(resolve => {
+                clientTransport.onmessage = () => resolve();
+            });
+            // No initialize handshake first - only ping is legal pre-initialize.
+            await clientTransport.send({ jsonrpc: '2.0', id: 1, method: 'ping', params: {} } as JSONRPCMessage);
+            await pingResponse;
+
+            expect(captured?.client.capabilities).toEqual({});
+            expect(captured?.client.info).toBeUndefined();
+            expect(captured?.mcpReq.protocolVersion).toBe(DEFAULT_NEGOTIATED_PROTOCOL_VERSION);
+
+            await server.close();
+        });
+    });
 });