test: add capability checks for listChanged handlers

Add tests verifying that listChanged handlers are only activated when the server advertises the corresponding capability. Tests cover:
- Handler not activated when server lacks listChanged capability
- Handler activated when server advertises capability
- No handlers activated when server has no listChanged capabilities
- Partial capability support with some handlers activated

Also defer handler setup until after initialization when server capabilities are known,

Author: mattzcarey

src/client/index.test.ts

@@ -12,6 +12,7 @@ import {
     ListResourcesRequestSchema,
     ListToolsRequestSchema,
     ListToolsResultSchema,
+    ListPromptsRequestSchema,
     CallToolRequestSchema,
     CallToolResultSchema,
     CreateMessageRequestSchema,
@@ -1558,6 +1559,225 @@ test('should handle multiple list changed handlers configured together', async (
     expect(promptNotifications[0][1]).toHaveLength(2);
 });
 
+/***
+ * Test: Handler not activated when server doesn't advertise listChanged capability
+ */
+test('should not activate listChanged handler when server does not advertise capability', async () => {
+    const notifications: [Error | null, Tool[] | null][] = [];
+
+    // Server with tools capability but WITHOUT listChanged
+    const server = new Server({ name: 'test-server', version: '1.0.0' }, { capabilities: { tools: {} } });
+
+    server.setRequestHandler(InitializeRequestSchema, async request => ({
+        protocolVersion: request.params.protocolVersion,
+        capabilities: { tools: {} }, // No listChanged: true
+        serverInfo: { name: 'test-server', version: '1.0.0' }
+    }));
+
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [{ name: 'test-tool', inputSchema: { type: 'object' } }]
+    }));
+
+    // Configure listChanged handler that should NOT be activated
+    const client = new Client(
+        { name: 'test-client', version: '1.0.0' },
+        {
+            listChanged: {
+                tools: {
+                    debounceMs: 0,
+                    onChanged: (err, tools) => {
+                        notifications.push([err, tools]);
+                    }
+                }
+            }
+        }
+    );
+
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+
+    await Promise.all([client.connect(clientTransport), server.connect(serverTransport)]);
+
+    // Verify server doesn't have tools.listChanged capability
+    expect(client.getServerCapabilities()?.tools?.listChanged).toBeFalsy();
+
+    // Send a tool list changed notification manually
+    await server.notification({ method: 'notifications/tools/list_changed' });
+    await new Promise(resolve => setTimeout(resolve, 100));
+
+    // Handler should NOT have been activated because server didn't advertise listChanged
+    expect(notifications).toHaveLength(0);
+});
+
+/***
+ * Test: Handler activated when server advertises listChanged capability
+ */
+test('should activate listChanged handler when server advertises capability', async () => {
+    const notifications: [Error | null, Tool[] | null][] = [];
+
+    // Server with tools.listChanged: true capability
+    const server = new Server({ name: 'test-server', version: '1.0.0' }, { capabilities: { tools: { listChanged: true } } });
+
+    server.setRequestHandler(InitializeRequestSchema, async request => ({
+        protocolVersion: request.params.protocolVersion,
+        capabilities: { tools: { listChanged: true } },
+        serverInfo: { name: 'test-server', version: '1.0.0' }
+    }));
+
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [{ name: 'test-tool', inputSchema: { type: 'object' } }]
+    }));
+
+    // Configure listChanged handler that SHOULD be activated
+    const client = new Client(
+        { name: 'test-client', version: '1.0.0' },
+        {
+            listChanged: {
+                tools: {
+                    debounceMs: 0,
+                    onChanged: (err, tools) => {
+                        notifications.push([err, tools]);
+                    }
+                }
+            }
+        }
+    );
+
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+
+    await Promise.all([client.connect(clientTransport), server.connect(serverTransport)]);
+
+    // Verify server has tools.listChanged capability
+    expect(client.getServerCapabilities()?.tools?.listChanged).toBe(true);
+
+    // Send a tool list changed notification
+    await server.notification({ method: 'notifications/tools/list_changed' });
+    await new Promise(resolve => setTimeout(resolve, 100));
+
+    // Handler SHOULD have been called
+    expect(notifications).toHaveLength(1);
+    expect(notifications[0][0]).toBeNull();
+    expect(notifications[0][1]).toHaveLength(1);
+});
+
+/***
+ * Test: No handlers activated when server has no listChanged capabilities
+ */
+test('should not activate any handlers when server has no listChanged capabilities', async () => {
+    const toolNotifications: [Error | null, Tool[] | null][] = [];
+    const promptNotifications: [Error | null, Prompt[] | null][] = [];
+    const resourceNotifications: [Error | null, Resource[] | null][] = [];
+
+    // Server with capabilities but NO listChanged for any
+    const server = new Server({ name: 'test-server', version: '1.0.0' }, { capabilities: { tools: {}, prompts: {}, resources: {} } });
+
+    server.setRequestHandler(InitializeRequestSchema, async request => ({
+        protocolVersion: request.params.protocolVersion,
+        capabilities: { tools: {}, prompts: {}, resources: {} },
+        serverInfo: { name: 'test-server', version: '1.0.0' }
+    }));
+
+    // Configure listChanged handlers for all three types
+    const client = new Client(
+        { name: 'test-client', version: '1.0.0' },
+        {
+            listChanged: {
+                tools: {
+                    debounceMs: 0,
+                    onChanged: (err, tools) => toolNotifications.push([err, tools])
+                },
+                prompts: {
+                    debounceMs: 0,
+                    onChanged: (err, prompts) => promptNotifications.push([err, prompts])
+                },
+                resources: {
+                    debounceMs: 0,
+                    onChanged: (err, resources) => resourceNotifications.push([err, resources])
+                }
+            }
+        }
+    );
+
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+
+    await Promise.all([client.connect(clientTransport), server.connect(serverTransport)]);
+
+    // Verify server has no listChanged capabilities
+    const caps = client.getServerCapabilities();
+    expect(caps?.tools?.listChanged).toBeFalsy();
+    expect(caps?.prompts?.listChanged).toBeFalsy();
+    expect(caps?.resources?.listChanged).toBeFalsy();
+
+    // Send notifications for all three types
+    await server.notification({ method: 'notifications/tools/list_changed' });
+    await server.notification({ method: 'notifications/prompts/list_changed' });
+    await server.notification({ method: 'notifications/resources/list_changed' });
+    await new Promise(resolve => setTimeout(resolve, 100));
+
+    // No handlers should have been activated
+    expect(toolNotifications).toHaveLength(0);
+    expect(promptNotifications).toHaveLength(0);
+    expect(resourceNotifications).toHaveLength(0);
+});
+
+/***
+ * Test: Partial capability support - some handlers activated, others not
+ */
+test('should handle partial listChanged capability support', async () => {
+    const toolNotifications: [Error | null, Tool[] | null][] = [];
+    const promptNotifications: [Error | null, Prompt[] | null][] = [];
+
+    // Server with tools.listChanged: true but prompts without listChanged
+    const server = new Server({ name: 'test-server', version: '1.0.0' }, { capabilities: { tools: { listChanged: true }, prompts: {} } });
+
+    server.setRequestHandler(InitializeRequestSchema, async request => ({
+        protocolVersion: request.params.protocolVersion,
+        capabilities: { tools: { listChanged: true }, prompts: {} },
+        serverInfo: { name: 'test-server', version: '1.0.0' }
+    }));
+
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [{ name: 'tool-1', inputSchema: { type: 'object' } }]
+    }));
+
+    server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+        prompts: [{ name: 'prompt-1' }]
+    }));
+
+    const client = new Client(
+        { name: 'test-client', version: '1.0.0' },
+        {
+            listChanged: {
+                tools: {
+                    debounceMs: 0,
+                    onChanged: (err, tools) => toolNotifications.push([err, tools])
+                },
+                prompts: {
+                    debounceMs: 0,
+                    onChanged: (err, prompts) => promptNotifications.push([err, prompts])
+                }
+            }
+        }
+    );
+
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+
+    await Promise.all([client.connect(clientTransport), server.connect(serverTransport)]);
+
+    // Verify capability state
+    expect(client.getServerCapabilities()?.tools?.listChanged).toBe(true);
+    expect(client.getServerCapabilities()?.prompts?.listChanged).toBeFalsy();
+
+    // Send notifications for both
+    await server.notification({ method: 'notifications/tools/list_changed' });
+    await server.notification({ method: 'notifications/prompts/list_changed' });
+    await new Promise(resolve => setTimeout(resolve, 100));
+
+    // Tools handler should have been called
+    expect(toolNotifications).toHaveLength(1);
+    // Prompts handler should NOT have been called (no prompts.listChanged)
+    expect(promptNotifications).toHaveLength(0);
+});
+
 describe('outputSchema validation', () => {
     /***
      * Test: Validate structuredContent Against outputSchema

src/client/index.ts

@@ -239,6 +239,7 @@ export class Client<
     private _cachedRequiredTaskTools: Set<string> = new Set();
     private _experimental?: { tasks: ExperimentalClientTasks<RequestT, NotificationT, ResultT> };
     private _listChangedDebounceTimers: Map<string, ReturnType<typeof setTimeout>> = new Map();
+    private _pendingListChangedConfig?: ListChangedHandlers;
 
     /**
      * Initializes this client with the given name and version information.
@@ -251,32 +252,34 @@ export class Client<
         this._capabilities = options?.capabilities ?? {};
         this._jsonSchemaValidator = options?.jsonSchemaValidator ?? new AjvJsonSchemaValidator();
 
-        // Set up list changed handlers if configured
+        // Store list changed config for setup after connection (when we know server capabilities)
         if (options?.listChanged) {
-            this._setupListChangedHandlers(options.listChanged);
+            this._pendingListChangedConfig = options.listChanged;
         }
     }
 
     /**
-     * Set up handlers for list changed notifications based on config.
+     * Set up handlers for list changed notifications based on config and server capabilities.
+     * This should only be called after initialization when server capabilities are known.
+     * Handlers are silently skipped if the server doesn't advertise the corresponding listChanged capability.
      * @internal
      */
     private _setupListChangedHandlers(config: ListChangedHandlers): void {
-        if (config.tools) {
+        if (config.tools && this._serverCapabilities?.tools?.listChanged) {
             this._setupListChangedHandler('tools', ToolListChangedNotificationSchema, config.tools, async () => {
                 const result = await this.listTools();
                 return result.tools;
             });
         }
 
-        if (config.prompts) {
+        if (config.prompts && this._serverCapabilities?.prompts?.listChanged) {
             this._setupListChangedHandler('prompts', PromptListChangedNotificationSchema, config.prompts, async () => {
                 const result = await this.listPrompts();
                 return result.prompts;
             });
         }
 
-        if (config.resources) {
+        if (config.resources && this._serverCapabilities?.resources?.listChanged) {
             this._setupListChangedHandler('resources', ResourceListChangedNotificationSchema, config.resources, async () => {
                 const result = await this.listResources();
                 return result.resources;
@@ -509,6 +512,12 @@ export class Client<
             await this.notification({
                 method: 'notifications/initialized'
             });
+
+            // Set up list changed handlers now that we know server capabilities
+            if (this._pendingListChangedConfig) {
+                this._setupListChangedHandlers(this._pendingListChangedConfig);
+                this._pendingListChangedConfig = undefined;
+            }
         } catch (error) {
             // Disconnect if initialization fails.
             void this.close();

src/types.ts

@@ -1490,6 +1490,10 @@ export type ListChangedOptions<T> = {
  *
  * Use this to configure handlers for tools, prompts, and resources list changes
  * when creating a client.
+ *
+ * Note: Handlers are only activated if the server advertises the corresponding
+ * `listChanged` capability (e.g., `tools.listChanged: true`). If the server
+ * doesn't advertise this capability, the handler will not be set up.
  */
 export type ListChangedHandlers = {
     /**