Skip to content

Commit b58d21c

Browse files
committed
Polish the modern client's tool listing, failures and HTTP hooks
- listTools() asked the server for every page on each call. The client now keeps the listing for its ttlMs and returns it while it's fresh. listTools() returns a spec: list() serves the kept listing, and skipCache() always asks the server. A listen stream that reports tool changes drops the kept listing. - The client's own failures (missing input handler, too many input rounds, invalid result, lost response, timeout, lost listen stream, HTTP error status) now extend McpClientException. Errors the server answered remain McpException, so catching the two covers every failure of a call. - McpHttpRequestCustomizer.fromSync ran the customizer on whichever thread sent the request, sometimes the caller's and sometimes an HTTP client thread. It now runs on boundedElastic, as the authorization error handler's fromSync does, so a customizer may block, for example to fetch a token. Hooks get the call's identity only from the McpTransportContext, on every attempt. - McpHttpRequest and McpHttpResponseInfo can now be created outside the SDK, with McpHttpRequest.builder(...) and McpHttpResponseInfo.of(...), so a custom HTTP transport can call the request customizers and the authorization error handler. Signed-off-by: Dariusz Jedrzejczyk <2554306+chemicL@users.noreply.github.com>
1 parent 637d995 commit b58d21c

32 files changed

Lines changed: 859 additions & 117 deletions

‎conformance-tests/client-modern/src/main/java/io/modelcontextprotocol/conformance/client/modern/ModernConformanceClient.java‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ public static void main(String[] args) {
6565
case "http-standard-headers" -> standardHeaders(client);
6666
case "http-custom-headers" -> customHeaders(client);
6767
case "http-invalid-tool-headers" -> invalidToolHeaders(client);
68-
case "json-schema-ref-no-deref" -> client.listTools();
68+
case "json-schema-ref-no-deref" -> client.listTools().list();
6969
case "json-schema-2020-12-preservation" -> schemaPreservation(client);
7070
default -> {
7171
System.err.println("Unknown scenario: " + scenario);
@@ -105,7 +105,7 @@ private static ElicitResult acceptWithDefaults(ElicitFormRequest request) {
105105
}
106106

107107
private static void toolsCall(McpSyncClient client) {
108-
Tool tool = client.listTools().tools().get(0);
108+
Tool tool = client.listTools().list().tools().get(0);
109109
CallToolResult result = client.tool(tool.name()).arguments(Map.of("a", 5, "b", 3)).call();
110110
System.out.println(tool.name() + ": " + result.content());
111111
}
@@ -117,7 +117,7 @@ private static void toolsCall(McpSyncClient client) {
117117
*/
118118
private static void requestMetadata(McpSyncClient client) {
119119
System.out.println("Server: " + client.discover().supportedVersions());
120-
client.listTools();
120+
client.listTools().list();
121121
}
122122

123123
/**
@@ -126,7 +126,7 @@ private static void requestMetadata(McpSyncClient client) {
126126
* between), and in one call that answers them with the client's elicitation handler.
127127
*/
128128
private static void multiRoundTrip(McpSyncClient client) {
129-
client.listTools();
129+
client.listTools().list();
130130

131131
McpSyncClient.ToolSpec echoState = client.tool("test_mrtr_echo_state").arguments(Map.of());
132132
CallToolOutcome first = echoState.callOnce();
@@ -146,7 +146,7 @@ private static void multiRoundTrip(McpSyncClient client) {
146146
* standard headers.
147147
*/
148148
private static void standardHeaders(McpSyncClient client) {
149-
for (Tool tool : client.listTools().tools()) {
149+
for (Tool tool : client.listTools().list().tools()) {
150150
client.tool(tool.name()).arguments(Map.of()).call();
151151
}
152152
for (Resource resource : client.resources().list().resources()) {
@@ -174,7 +174,7 @@ private static void customHeaders(McpSyncClient client) throws IOException {
174174
* annotations are left out of the listing.
175175
*/
176176
private static void invalidToolHeaders(McpSyncClient client) {
177-
for (Tool tool : client.listTools().tools()) {
177+
for (Tool tool : client.listTools().list().tools()) {
178178
client.tool(tool).arguments(sampleArguments(tool)).call();
179179
}
180180
}
@@ -184,6 +184,7 @@ private static void invalidToolHeaders(McpSyncClient client) {
184184
*/
185185
private static void schemaPreservation(McpSyncClient client) {
186186
Tool focal = client.listTools()
187+
.list()
187188
.tools()
188189
.stream()
189190
.filter(tool -> tool.name().equals("json_schema_2020_12_tool"))

‎mcp-core/src/main/java/io/modelcontextprotocol/modern/client/AsyncClientRequester.java‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66

77
import java.time.Duration;
88
import java.util.Map;
9+
import java.util.function.Function;
910
import java.util.function.Supplier;
1011

1112
import io.modelcontextprotocol.modern.McpSchema;
@@ -104,6 +105,23 @@ ListToolsResult listedTools(ListToolsResult page) {
104105
return this.requests.listedTools(page);
105106
}
106107

108+
/**
109+
* The client's kept listing of all tools, or {@code null} if there is none or it is
110+
* stale.
111+
*/
112+
@Nullable ListToolsResult keptTools() {
113+
return this.requests.keptTools();
114+
}
115+
116+
/**
117+
* Lists all tools and keeps the result.
118+
* @param lister lists the page at a cursor as the server sent it, {@code null} for
119+
* the first page
120+
*/
121+
Mono<ListToolsResult> listAllTools(Function<String, Mono<ListToolsResult>> lister) {
122+
return this.requests.listAllTools(lister);
123+
}
124+
107125
private <R extends Result> Mono<R> run(Supplier<MultiRoundTripRequest<R>> requestSupplier,
108126
CallSettings<Mono<?>> settings, String method) {
109127
Mono<R> call = Mono.defer(() -> {

‎mcp-core/src/main/java/io/modelcontextprotocol/modern/client/ClientRequestFactory.java‎

Lines changed: 23 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
package io.modelcontextprotocol.modern.client;
66

77
import java.util.Map;
8+
import java.util.function.Function;
89

910
import io.modelcontextprotocol.modern.McpSchema;
1011
import io.modelcontextprotocol.modern.McpSchema.CallToolResult;
@@ -13,6 +14,7 @@
1314
import io.modelcontextprotocol.modern.McpSchema.Result;
1415
import io.modelcontextprotocol.modern.McpSchema.Tool;
1516
import org.jspecify.annotations.Nullable;
17+
import reactor.core.publisher.Mono;
1618

1719
/**
1820
* Creates the requests and listen streams of a client over what all of them share: the
@@ -24,15 +26,13 @@ final class ClientRequestFactory {
2426

2527
private final JsonRpcRequestSender sender;
2628

27-
// Present exactly when the transport mirrors tool params into headers.
28-
@Nullable private final ToolCatalog catalog;
29+
private final ToolCatalog catalog;
2930

3031
private final int maxInputRounds;
3132

3233
private final int maxListPages;
3334

34-
ClientRequestFactory(JsonRpcRequestSender sender, @Nullable ToolCatalog catalog, int maxInputRounds,
35-
int maxListPages) {
35+
ClientRequestFactory(JsonRpcRequestSender sender, ToolCatalog catalog, int maxInputRounds, int maxListPages) {
3636
this.sender = sender;
3737
this.catalog = catalog;
3838
this.maxInputRounds = maxInputRounds;
@@ -72,7 +72,7 @@ <R extends Result> MultiRoundTripRequest<R> request(String method, @Nullable Str
7272
*/
7373
MultiRoundTripRequest<CallToolResult> toolCall(String name, Object params, CallSettings<?> settings,
7474
@Nullable Tool tool) {
75-
if (this.catalog == null) {
75+
if (!this.catalog.mirrorsToolParams()) {
7676
return request(McpSchema.METHOD_TOOLS_CALL, name, params, settings, CallToolResult.class);
7777
}
7878
return request(McpSchema.METHOD_TOOLS_CALL, params, settings, CallToolResult.class,
@@ -84,7 +84,24 @@ MultiRoundTripRequest<CallToolResult> toolCall(String name, Object params, CallS
8484
* transport mirrors tool params.
8585
*/
8686
ListToolsResult listedTools(ListToolsResult page) {
87-
return this.catalog == null ? page : this.catalog.accept(page);
87+
return this.catalog.accept(page);
88+
}
89+
90+
/**
91+
* The client's kept listing of all tools, or {@code null} if there is none or it is
92+
* stale.
93+
*/
94+
@Nullable ListToolsResult keptTools() {
95+
return this.catalog.listing();
96+
}
97+
98+
/**
99+
* Lists all tools and keeps the result.
100+
* @param lister lists the page at a cursor as the server sent it, {@code null} for
101+
* the first page
102+
*/
103+
Mono<ListToolsResult> listAllTools(Function<String, Mono<ListToolsResult>> lister) {
104+
return this.catalog.listAll(lister);
88105
}
89106

90107
private <R extends Result> MultiRoundTripRequest<R> request(String method, Object params, CallSettings<?> settings,

‎mcp-core/src/main/java/io/modelcontextprotocol/modern/client/McpAsyncClient.java‎

Lines changed: 94 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -194,20 +194,11 @@ public Mono<DiscoverResult> discover() {
194194
}
195195

196196
/**
197-
* All the server's tools: every page of {@code tools().list()}, as one result that
198-
* may be kept for the shortest {@code ttlMs} of its pages, and is private if any page
199-
* is. A listing longer than {@link McpClient.Builder#maxListPages maxListPages} fails
200-
* with {@link McpInvalidResultException}.
201-
* <p>
202-
* When the transport mirrors tool arguments into headers, tools whose
203-
* {@code x-mcp-header} annotations are invalid are left out of every listing, and
204-
* logged.
197+
* All the server's tools, as one result: the listing the client keeps, or every page
198+
* of {@code tools().list()} when it keeps none; see {@link ListToolsSpec}.
205199
*/
206-
public Mono<ListToolsResult> listTools() {
207-
return Listings
208-
.pages(McpSchema.METHOD_TOOLS_LIST, cursor -> tools().cursor(cursor).list(), ListToolsResult::nextCursor,
209-
this.requester.maxListPages())
210-
.map(Listings::allTools);
200+
public ListToolsSpec listTools() {
201+
return new ListToolsSpec(this.requester, false, this.requester.settings());
211202
}
212203

213204
@Nullable private static <V> Map<String, V> copy(@Nullable Map<String, V> map) {
@@ -304,6 +295,96 @@ private ListSpec<R> with(CallSettings<Mono<?>> settings) {
304295

305296
}
306297

298+
/**
299+
* Lists all the server's tools as one result, kept for the shortest {@code ttlMs} of
300+
* its pages and private if any page is. Immutable.
301+
* <p>
302+
* The client keeps the last such listing until its {@code ttlMs} has passed, and
303+
* returns it instead of asking the server again. A client stands for one identity, so
304+
* a private listing is kept as well. The kept listing is replaced by every listing of
305+
* all tools, including the one a call by name makes, and dropped when a listen stream
306+
* reports that the tools may have changed. A listing with a {@code ttlMs} of
307+
* {@code 0} isn't kept.
308+
* <p>
309+
* A listing longer than {@link McpClient.Builder#maxListPages maxListPages} fails
310+
* with {@link McpInvalidResultException}. When the transport mirrors tool arguments
311+
* into headers, tools whose {@code x-mcp-header} annotations are invalid are left
312+
* out, and logged.
313+
*/
314+
public static final class ListToolsSpec {
315+
316+
private final AsyncClientRequester requester;
317+
318+
private final boolean skipCache;
319+
320+
private final CallSettings<Mono<?>> settings;
321+
322+
private ListToolsSpec(AsyncClientRequester requester, boolean skipCache, CallSettings<Mono<?>> settings) {
323+
this.requester = requester;
324+
this.skipCache = skipCache;
325+
this.settings = settings;
326+
}
327+
328+
/**
329+
* Asks the server even when the client keeps a listing, and keeps the new one.
330+
*/
331+
public ListToolsSpec skipCache() {
332+
return new ListToolsSpec(this.requester, true, this.settings);
333+
}
334+
335+
/**
336+
* The timeout of each exchange, instead of the client's.
337+
*/
338+
public ListToolsSpec roundTimeout(Duration roundTimeout) {
339+
return with(this.settings.withRoundTimeout(roundTimeout));
340+
}
341+
342+
/**
343+
* The bound on each page's call, instead of the client's.
344+
*/
345+
public ListToolsSpec callTimeout(Duration callTimeout) {
346+
return with(this.settings.withCallTimeout(callTimeout));
347+
}
348+
349+
/**
350+
* Receives the progress of each page's call, instead of the client's listener.
351+
* The next notification, and the result, wait for the {@code Mono} it returns.
352+
*/
353+
public ListToolsSpec progress(Function<ProgressParams, Mono<Void>> listener) {
354+
return with(this.settings.withProgress(listener));
355+
}
356+
357+
/**
358+
* Entries added to the {@code _meta} of each page's request, replacing those set
359+
* before.
360+
* @throws IllegalArgumentException for {@code progressToken} and keys with the
361+
* {@code io.modelcontextprotocol/} prefix, which the client sets itself
362+
*/
363+
public ListToolsSpec meta(Map<String, ?> meta) {
364+
return with(this.settings.withMeta(meta));
365+
}
366+
367+
/**
368+
* Lists the tools, or returns the kept listing.
369+
*/
370+
public Mono<ListToolsResult> list() {
371+
return Mono.defer(() -> {
372+
ListToolsResult kept = this.skipCache ? null : this.requester.keptTools();
373+
if (kept != null) {
374+
return Mono.just(kept);
375+
}
376+
ListSpec<ListToolsResult> pages = new ListSpec<>(this.requester, McpSchema.METHOD_TOOLS_LIST,
377+
ListToolsResult.class, UnaryOperator.identity(), null, this.settings);
378+
return this.requester.listAllTools(cursor -> pages.cursor(cursor).list());
379+
});
380+
}
381+
382+
private ListToolsSpec with(CallSettings<Mono<?>> settings) {
383+
return new ListToolsSpec(this.requester, this.skipCache, settings);
384+
}
385+
386+
}
387+
307388
/**
308389
* A call of one tool. Immutable.
309390
*/

‎mcp-core/src/main/java/io/modelcontextprotocol/modern/client/McpClient.java‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -178,7 +178,7 @@ ClientRequestFactory requests() {
178178
JsonRpcRequestSender sender = new JsonRpcRequestSender(this.transport, mapper, this.clientInfo,
179179
this.protocolVersions);
180180
return new ClientRequestFactory(sender,
181-
this.transport.mirrorsToolParams() ? new ToolCatalog(this.maxListPages) : null, this.maxInputRounds,
181+
new ToolCatalog(this.transport.mirrorsToolParams(), this.maxListPages), this.maxInputRounds,
182182
this.maxListPages);
183183
}
184184

@@ -263,8 +263,9 @@ private SyncBuilder(McpClientTransport transport) {
263263
/**
264264
* Supplies the {@link McpTransportContext} of a call, for example the identity of
265265
* the current user. It is called on the calling thread when a call starts or a
266-
* listen stream opens, so it may read thread-locals, and its result is used for
267-
* every request of that call, also on other threads. Defaults to
266+
* listen stream opens, so it may read thread-locals. Its result is the only
267+
* identity the transport's hooks receive, for every request and retry of that
268+
* call, which may run on other threads. Defaults to
268269
* {@link McpTransportContext#EMPTY}.
269270
*/
270271
public SyncBuilder transportContextProvider(Supplier<McpTransportContext> provider) {
Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
/*
2+
* Copyright 2026-2026 the original author or authors.
3+
*/
4+
5+
package io.modelcontextprotocol.modern.client;
6+
7+
import io.modelcontextprotocol.modern.McpException;
8+
import org.jspecify.annotations.Nullable;
9+
10+
/**
11+
* A call failed in the client or on the way to the server, rather than with an error the
12+
* server answered, which is an {@link McpException}. Exceptions thrown by the transport's
13+
* hooks reach the caller as they are, not as this type.
14+
*
15+
* @author Dariusz Jędrzejczyk
16+
*/
17+
public abstract class McpClientException extends RuntimeException {
18+
19+
protected McpClientException(String message) {
20+
super(message);
21+
}
22+
23+
protected McpClientException(String message, @Nullable Throwable cause) {
24+
super(message, cause);
25+
}
26+
27+
}

‎mcp-core/src/main/java/io/modelcontextprotocol/modern/client/McpInputHandlerMissingException.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
*
1515
* @author Dariusz Jędrzejczyk
1616
*/
17-
public class McpInputHandlerMissingException extends RuntimeException {
17+
public class McpInputHandlerMissingException extends McpClientException {
1818

1919
private final String inputKey;
2020

‎mcp-core/src/main/java/io/modelcontextprotocol/modern/client/McpInputRoundsExceededException.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
*
1010
* @author Dariusz Jędrzejczyk
1111
*/
12-
public class McpInputRoundsExceededException extends RuntimeException {
12+
public class McpInputRoundsExceededException extends McpClientException {
1313

1414
private final String method;
1515

‎mcp-core/src/main/java/io/modelcontextprotocol/modern/client/McpInvalidResultException.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
*
1414
* @author Dariusz Jędrzejczyk
1515
*/
16-
public class McpInvalidResultException extends RuntimeException {
16+
public class McpInvalidResultException extends McpClientException {
1717

1818
private final String method;
1919

‎mcp-core/src/main/java/io/modelcontextprotocol/modern/client/McpResponseLostException.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
*
1111
* @author Dariusz Jędrzejczyk
1212
*/
13-
public class McpResponseLostException extends RuntimeException {
13+
public class McpResponseLostException extends McpClientException {
1414

1515
private final String method;
1616

0 commit comments

Comments
 (0)