Class AsyncModernMcpToolCallbackProvider
- All Implemented Interfaces:
AsyncModernMcpChangeListener,ToolCallbackProvider,org.springframework.core.Ordered
ToolCallbacks.
Each call to getToolCallbacks() asks every AsyncModernMcpConnection
for the client that serves the current request, lists that client's tools, and returns
callbacks bound to that client. A ChatClient calls this method once for each
request, so register the provider with defaultToolCallbacks(provider) rather
than the callbacks it returns.
The server decides how long a tool listing may be kept and who may share it, with the
ttlMs and cacheScope of the listing:
- A listing with a
ttlMsof zero is never kept, and every call togetToolCallbacks()lists the tools again. Servers send zero unless configured otherwise. - A
publiclisting is the same for every caller. The provider keeps it for itsttlMsand uses it for all requests, whichever client serves them. - A
privatelisting may differ from caller to caller, so the provider does not keep it. It is only kept by a client that outlives a request, as the client of asharedconnection does, or the client that ascopedconnection keeps for a user. Use a shared connection when the application calls the server under a single identity.
A kept listing is used until its ttlMs has passed. To drop it as soon as the
server reports that its tools changed, register the provider as a listener of an
AsyncModernMcpChangeSubscriber, which keeps a listen stream open to the server.
The tools are listed through the asynchronous client, and the call blocks until the
listings are there, as the ToolCallbackProvider contract requires. So it must
not be made on a thread that may not block, such as an event loop. The caller of a
listing is the transport context of
its connection, which is read on the calling thread.
A server that cannot be reached does not fail the call: its tools are left out and a
warning is logged, so the tools of the other connections stay usable. A server counts
as unreachable when the connection cannot be established, the exchange times out or
breaks, or the server answers with a 5xx, 408 or 429 status.
Every other failure is thrown, in particular an authorization failure, so that the
application can ask the user to log in again.
A server that could not be reached is not asked again until a cool-down time has passed (30 seconds unless set otherwise). Otherwise a server that accepts connections but does not answer would hold up every request for the whole timeout of the listing.
- Since:
- 2.1.0
- Author:
- Christian Tzolov
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final classBuilder forAsyncModernMcpToolCallbackProvider. -
Field Summary
Fields inherited from interface org.springframework.core.Ordered
HIGHEST_PRECEDENCE, LOWEST_PRECEDENCE -
Method Summary
Modifier and TypeMethodDescriptionbuilder()Creates a builder for aAsyncModernMcpToolCallbackProvider.reactor.core.publisher.Mono<Void>changed(McpModernConnectionInfo connectionInfo, io.modelcontextprotocol.modern.client.SubscriptionEvent event) Drops the kept tool listing of the connection when its server reports that its tools changed.reactor.core.publisher.Mono<Void>changesMayBeMissed(McpModernConnectionInfo connectionInfo) Drops the kept tool listing of the connection, because a change of its tools may have gone unreported.intgetOrder()The provider hears about a change before the other listeners of anAsyncModernMcpChangeSubscriber, so that a listener that asks it for the tools finds the kept listing dropped.Returns a callback for each tool of every connection that the filter accepts.voidinvalidateToolListing(String connectionName) Drops the kept tool listing of a connection, so that the next call togetToolCallbacks()lists its tools again.reactor.core.publisher.Mono<Void>streamEstablished(McpModernConnectionInfo connectionInfo) Ends the cool-down of the connection, if its server could not be reached before: a listen stream that was established shows that it can be reached again.
-
Method Details
-
builder
Creates a builder for aAsyncModernMcpToolCallbackProvider.- Returns:
- the builder
-
getToolCallbacks
Returns a callback for each tool of every connection that the filter accepts. The tools of a connection are listed unless a public listing of them is still kept. The callbacks of a connection are bound to the client that connection returned for this call. The tools of a connection whose server cannot be reached are left out, and that server is not asked again until the cool-down time has passed.- Specified by:
getToolCallbacksin interfaceToolCallbackProvider- Returns:
- the tool callbacks
- Throws:
IllegalStateException- if two tools end up with the same name
-
invalidateToolListing
Drops the kept tool listing of a connection, so that the next call togetToolCallbacks()lists its tools again. Use it when the tools of the server are known to have changed before thettlMsof the listing has passed. A client that keeps a listing itself, as a shared client or a client that aAsyncModernMcpClientScopekeeps for a user does, asks the server the next time it lists the tools.- Parameters:
connectionName- the name of the connection
-
getOrder
public int getOrder()The provider hears about a change before the other listeners of anAsyncModernMcpChangeSubscriber, so that a listener that asks it for the tools finds the kept listing dropped.- Specified by:
getOrderin interfaceorg.springframework.core.Ordered- Returns:
- the highest precedence
-
streamEstablished
Ends the cool-down of the connection, if its server could not be reached before: a listen stream that was established shows that it can be reached again.- Specified by:
streamEstablishedin interfaceAsyncModernMcpChangeListener- Parameters:
connectionInfo- the connection whose server accepted the stream- Returns:
- completes when the listener has dealt with it
-
changed
public reactor.core.publisher.Mono<Void> changed(McpModernConnectionInfo connectionInfo, io.modelcontextprotocol.modern.client.SubscriptionEvent event) Drops the kept tool listing of the connection when its server reports that its tools changed.- Specified by:
changedin interfaceAsyncModernMcpChangeListener- Parameters:
connectionInfo- the connection whose server changedevent- what changed: aSubscriptionEvent.ToolsListChanged, aSubscriptionEvent.PromptsListChanged, aSubscriptionEvent.ResourcesListChangedor aSubscriptionEvent.ResourceUpdated- Returns:
- completes when the listener has dealt with the change
-
changesMayBeMissed
Drops the kept tool listing of the connection, because a change of its tools may have gone unreported.- Specified by:
changesMayBeMissedin interfaceAsyncModernMcpChangeListener- Parameters:
connectionInfo- the connection whose server may have changed- Returns:
- completes when the listener has dealt with it
-