Added auto-refreshing tool list notification handler to client

[johnjjung]

Added handler for server's notifications/tools/list_changed notification
Implemented auto-refresh for tools list when notification is received
Added onToolListChanged callback property to provide updated tools to clients
Added setToolListChangedCallback convenience method for callback registration
Added capability validation to ensure tools support before refreshing
Fixed type definitions for proper TypeScript compliance
Added error handling for failed refreshes

Motivation and Context

• Improves the client's handling of tool list updates from the server.
• Previously, the client had no built-in mechanism to refresh its local tools when the server sent a tools/list_changed notification.
• Now, the client automatically fetches the updated tools when notified.
• Applications can register a callback to receive the updated tools, simplifying integration.

Related Issues and discussions:

#205

https://github.com/orgs/modelcontextprotocol/discussions/76

How Has This Been Tested?

• Tested by simulating server notifications in a development environment.
• Verified that the callback receives the updated tools list.
• Confirmed error handling correctly triggers on failed refresh attempts.
• Checked capability validation blocks refresh on unsupported clients.

Breaking Changes

• No breaking changes. This is a purely additive feature.
• Existing code will continue to work.
• Applications can optionally implement the new callback to receive tool updates.

Types of changes

[ ] Bug fix (non-breaking change which fixes an issue)
[x] New feature (non-breaking change which adds functionality)
[ ] Breaking change (fix or feature that would cause existing functionality to change)
[ ] Documentation update

Checklist

[x] I have read the MCP Documentation
[x] My code follows the repository's style guidelines
[x] New and existing tests pass locally
[x] I have added appropriate error handling
[x] I have added or updated documentation as needed

Additional context

• Implementation follows the same pattern as other notification handlers in the codebase.
• Adds automatic refreshing to reduce boilerplate in client applications.
• Error handling ensures that applications are notified of tool list changes even if the refresh fails.
• Clients can implement custom fallback strategies if necessary.

[jspahrsummers]

Automatically refreshing every time this notification is received could accidentally cause a lot of chattiness between client and server. The logic needs to be more nuanced—e.g., including debouncing, and some way to configure the behavior.

Please also do not include unrelated changes, like the reformatted lines, as this makes your PR harder to review.

[johnjjung]

I've implemented the requested improvements for the tool list refresh feature:

1. Added configurability via toolRefreshOptions:

   • autoRefresh: Controls whether tools list is automatically refreshed (default: true)
   • debounceMs: Controls debounce time between refresh operations (default: 500ms)

2. Implemented debouncing to prevent excessive refresh requests when multiple notifications arrive in quick succession

3. Added helper methods:

   • setToolRefreshOptions(): For changing refresh behavior at runtime
   • getToolRefreshOptions(): For checking current configuration
   • refreshToolsList(): For manually triggering a refresh when needed

4. Error callback in configuration options:

   • Added onError callback option to toolRefreshOptions in ClientOptions
   • This callback receives the error that occurred during tools list refresh

@jspahrsummers These changes should address your concerns. The debouncing mechanism ensures that even if multiple change notifications are received within the debounce window, only one refresh will occur with a configurable debounce.

I've considered rate-limiting as well but it seems excessive given that other areas of the code don't have these options yet.