Skip to content

Commit 2de1d63

Browse files
tzolovtzolov
committed
Fix javadoc issues
1 parent f755183 commit 2de1d63

7 files changed

Lines changed: 111 additions & 41 deletions

File tree

‎mcp/src/main/java/org/springframework/ai/mcp/client/McpAsyncClient.java‎

Lines changed: 54 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -84,8 +84,8 @@ public class McpAsyncClient {
8484
private final ConcurrentHashMap<String, Root> roots;
8585

8686
/**
87-
* MCP provides a standardized way for servers to request LLM sampling (“completions”
88-
* or “generations”) from language models via clients. This flow allows clients to
87+
* MCP provides a standardized way for servers to request LLM sampling ("completions"
88+
* or "generations") from language models via clients. This flow allows clients to
8989
* maintain control over model access, selection, and permissions while enabling
9090
* servers to leverage AI capabilities—with no server API keys necessary. Servers can
9191
* request text or image-based interactions and optionally include context from MCP
@@ -108,10 +108,13 @@ public class McpAsyncClient {
108108
* timeout.
109109
* @param transport the transport to use.
110110
* @param requestTimeout the session request-response timeout.
111-
* @param rootsListProviders the list of suppliers that provide the list of roots
112-
* backing the roots list request.
113-
* @param rootsListChangedNotification whether the client supports roots/list_changed
114-
* notification.
111+
* @param clientInfo the client implementation information.
112+
* @param clientCapabilities the client capabilities.
113+
* @param roots the roots.
114+
* @param toolsChangeConsumers the tools change consumers.
115+
* @param resourcesChangeConsumers the resources change consumers.
116+
* @param promptsChangeConsumers the prompts change consumers.
117+
* @param samplingHandler the sampling handler.
115118
*/
116119
public McpAsyncClient(McpTransport transport, Duration requestTimeout, Implementation clientInfo,
117120
ClientCapabilities clientCapabilities, Map<String, Root> roots,
@@ -215,9 +218,9 @@ public McpAsyncClient(McpTransport transport, Duration requestTimeout, Implement
215218
*/
216219
public Mono<McpSchema.InitializeResult> initialize() {
217220
McpSchema.InitializeRequest initializeRequest = new McpSchema.InitializeRequest(// @formatter:off
218-
McpSchema.LATEST_PROTOCOL_VERSION,
219-
this.clientCapabilities,
220-
this.clientInfo); // @formatter:on
221+
McpSchema.LATEST_PROTOCOL_VERSION,
222+
this.clientCapabilities,
223+
this.clientInfo); // @formatter:on
221224

222225
Mono<McpSchema.InitializeResult> result = this.mcpSession.sendRequest("initialize", initializeRequest,
223226
new TypeReference<McpSchema.InitializeResult>() {
@@ -239,10 +242,17 @@ public Mono<McpSchema.InitializeResult> initialize() {
239242
});
240243
}
241244

245+
/**
246+
* Closes the client connection immediately.
247+
*/
242248
public void close() {
243249
this.mcpSession.close();
244250
}
245251

252+
/**
253+
* Gracefully closes the client connection.
254+
* @return A Mono that completes when the connection is closed
255+
*/
246256
public Mono<Void> closeGracefully() {
247257
return this.mcpSession.closeGracefully();
248258
}
@@ -252,7 +262,8 @@ public Mono<Void> closeGracefully() {
252262
// --------------------------
253263

254264
/**
255-
* Send a synchronous ping request.
265+
* Sends a ping request to the server.
266+
* @return A Mono that completes with the server's ping response
256267
*/
257268
public Mono<Object> ping() {
258269
return this.mcpSession.sendRequest("ping", null, new TypeReference<Object>() {
@@ -262,6 +273,11 @@ public Mono<Object> ping() {
262273
// --------------------------
263274
// Roots
264275
// --------------------------
276+
/**
277+
* Adds a new root to the client's root list.
278+
* @param root The root to add
279+
* @return A Mono that completes when the root is added and notifications are sent
280+
*/
265281
public Mono<Void> addRoot(Root root) {
266282

267283
if (root == null) {
@@ -286,6 +302,11 @@ public Mono<Void> addRoot(Root root) {
286302
return Mono.empty();
287303
}
288304

305+
/**
306+
* Removes a root from the client's root list.
307+
* @param rootUri The URI of the root to remove
308+
* @return A Mono that completes when the root is removed and notifications are sent
309+
*/
289310
public Mono<Void> removeRoot(String rootUri) {
290311

291312
if (rootUri == null) {
@@ -309,8 +330,9 @@ public Mono<Void> removeRoot(String rootUri) {
309330
}
310331

311332
/**
312-
* Manually, send a roots/list_changed notification. The addRoot and removeRoot
333+
* Manually sends a roots/list_changed notification. The addRoot and removeRoot
313334
* methods automatically send the roots/list_changed notification.
335+
* @return A Mono that completes when the notification is sent
314336
*/
315337
public Mono<Void> rootsListChangedNotification() {
316338
return this.mcpSession.sendNotification("notifications/roots/list_changed");
@@ -436,16 +458,16 @@ public Mono<Void> handle(Object params) {
436458

437459
/**
438460
* Send a resources/list request.
439-
* @return the list of resources result.
461+
* @return A Mono that completes with the list of resources result
440462
*/
441463
public Mono<McpSchema.ListResourcesResult> listResources() {
442464
return this.listResources(null);
443465
}
444466

445467
/**
446468
* Send a resources/list request.
447-
* @param cursor the cursor
448-
* @return the list of resources result.
469+
* @param cursor the cursor for pagination
470+
* @return A Mono that completes with the list of resources result
449471
*/
450472
public Mono<McpSchema.ListResourcesResult> listResources(String cursor) {
451473
return this.mcpSession.sendRequest("resources/list", new McpSchema.PaginatedRequest(cursor),
@@ -455,16 +477,16 @@ public Mono<McpSchema.ListResourcesResult> listResources(String cursor) {
455477
/**
456478
* Send a resources/read request.
457479
* @param resource the resource to read
458-
* @return the resource content.
480+
* @return A Mono that completes with the resource content
459481
*/
460482
public Mono<McpSchema.ReadResourceResult> readResource(McpSchema.Resource resource) {
461483
return this.readResource(new McpSchema.ReadResourceRequest(resource.uri()));
462484
}
463485

464486
/**
465487
* Send a resources/read request.
466-
* @param readResourceRequest the read resource request.
467-
* @return the resource content.
488+
* @param readResourceRequest the read resource request
489+
* @return A Mono that completes with the resource content
468490
*/
469491
public Mono<McpSchema.ReadResourceResult> readResource(McpSchema.ReadResourceRequest readResourceRequest) {
470492
return this.mcpSession.sendRequest("resources/read", readResourceRequest, READ_RESOURCE_RESULT_TYPE_REF);
@@ -475,7 +497,7 @@ public Mono<McpSchema.ReadResourceResult> readResource(McpSchema.ReadResourceReq
475497
* templates. Arguments may be auto-completed through the completion API.
476498
*
477499
* Request a list of resource templates the server has.
478-
* @return the list of resource templates result.
500+
* @return A Mono that completes with the list of resource templates result
479501
*/
480502
public Mono<McpSchema.ListResourceTemplatesResult> listResourceTemplates() {
481503
return this.listResourceTemplates(null);
@@ -486,8 +508,8 @@ public Mono<McpSchema.ListResourceTemplatesResult> listResourceTemplates() {
486508
* templates. Arguments may be auto-completed through the completion API.
487509
*
488510
* Request a list of resource templates the server has.
489-
* @param cursor the cursor
490-
* @return the list of resource templates result.
511+
* @param cursor the cursor for pagination
512+
* @return A Mono that completes with the list of resource templates result
491513
*/
492514
public Mono<McpSchema.ListResourceTemplatesResult> listResourceTemplates(String cursor) {
493515
return this.mcpSession.sendRequest("resources/templates/list", new McpSchema.PaginatedRequest(cursor),
@@ -496,7 +518,8 @@ public Mono<McpSchema.ListResourceTemplatesResult> listResourceTemplates(String
496518

497519
/**
498520
* List Changed Notification. When the list of available resources changes, servers
499-
* that declared the listChanged capability SHOULD send a notification:
521+
* that declared the listChanged capability SHOULD send a notification.
522+
* @return A Mono that completes when the notification is sent
500523
*/
501524
public Mono<Void> sendResourcesListChanged() {
502525
return this.mcpSession.sendNotification("notifications/resources/list_changed");
@@ -509,7 +532,8 @@ public Mono<Void> sendResourcesListChanged() {
509532
*
510533
* Send a resources/subscribe request.
511534
* @param subscribeRequest the subscribe request contains the uri of the resource to
512-
* subscribe to.
535+
* subscribe to
536+
* @return A Mono that completes when the subscription is complete
513537
*/
514538
public Mono<Void> subscribeResource(McpSchema.SubscribeRequest subscribeRequest) {
515539
return this.mcpSession.sendRequest("resources/subscribe", subscribeRequest, VOID_TYPE_REFERENCE);
@@ -518,7 +542,8 @@ public Mono<Void> subscribeResource(McpSchema.SubscribeRequest subscribeRequest)
518542
/**
519543
* Send a resources/unsubscribe request.
520544
* @param unsubscribeRequest the unsubscribe request contains the uri of the resource
521-
* to unsubscribe from.
545+
* to unsubscribe from
546+
* @return A Mono that completes when the unsubscription is complete
522547
*/
523548
public Mono<Void> unsubscribeResource(McpSchema.UnsubscribeRequest unsubscribeRequest) {
524549
return this.mcpSession.sendRequest("resources/unsubscribe", unsubscribeRequest, VOID_TYPE_REFERENCE);
@@ -554,25 +579,25 @@ public Mono<Void> handle(Object params) {
554579

555580
/**
556581
* List all available prompts.
557-
* @return the list of prompts result.
582+
* @return A Mono that completes with the list of prompts result
558583
*/
559584
public Mono<ListPromptsResult> listPrompts() {
560585
return this.listPrompts(null);
561586
}
562587

563588
/**
564589
* List all available prompts.
565-
* @param cursor the cursor
566-
* @return the list of prompts result.
590+
* @param cursor the cursor for pagination
591+
* @return A Mono that completes with the list of prompts result
567592
*/
568593
public Mono<ListPromptsResult> listPrompts(String cursor) {
569594
return this.mcpSession.sendRequest("prompts/list", new PaginatedRequest(cursor), LIST_PROMPTS_RESULT_TYPE_REF);
570595
}
571596

572597
/**
573598
* Get a prompt by its id.
574-
* @param getPromptRequest the get prompt request.
575-
* @return the get prompt result.
599+
* @param getPromptRequest the get prompt request
600+
* @return A Mono that completes with the get prompt result
576601
*/
577602
public Mono<GetPromptResult> getPrompt(GetPromptRequest getPromptRequest) {
578603
return this.mcpSession.sendRequest("prompts/get", getPromptRequest, GET_PROMPT_RESULT_TYPE_REF);
@@ -582,6 +607,7 @@ public Mono<GetPromptResult> getPrompt(GetPromptRequest getPromptRequest) {
582607
* (Server) An optional notification from the server to the client, informing it that
583608
* the list of prompts it offers has changed. This may be issued by servers without
584609
* any previous subscription from the client.
610+
* @return A Mono that completes when the notification is sent
585611
*/
586612
public Mono<Void> promptListChangedNotification() {
587613
return this.mcpSession.sendNotification("notifications/prompts/list_changed");

‎mcp/src/main/java/org/springframework/ai/mcp/client/McpSyncClient.java‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,8 @@
2828
import org.springframework.ai.mcp.util.Assert;
2929

3030
/**
31+
* A synchronous client for the Model Context Protocol (MCP).
32+
*
3133
* @author Dariusz Jędrzejczyk
3234
* @author Christian Tzolov
3335
*/

‎mcp/src/main/java/org/springframework/ai/mcp/client/transport/SseClientTransport.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -60,8 +60,8 @@
6060
* <ol>
6161
* <li>The client establishes an SSE connection to the server's /sse endpoint</li>
6262
* <li>The server sends an 'endpoint' event containing the URI for sending messages</li>
63-
*
64-
* <p>
63+
* </ol>
64+
*
6565
* This implementation handles automatic reconnection for transient failures and provides
6666
* graceful shutdown capabilities. It uses {@link WebClient} for HTTP communications and
6767
* supports JSON serialization/deserialization of messages.

‎mcp/src/main/java/org/springframework/ai/mcp/server/McpAsyncServer.java‎

Lines changed: 15 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -61,10 +61,13 @@ public class McpAsyncServer {
6161

6262
/**
6363
* Create a new McpAsyncServer with the given transport and capabilities.
64-
* @param transport The transport to use for communication
65-
* @param tools List of tool registrations
66-
* @param resources Map of resource registrations
67-
* @param prompts Map of prompt registrations
64+
* @param mcpTransport The transport layer implementation for MCP communication
65+
* @param serverInfo The server implementation details
66+
* @param serverCapabilities The server capabilities
67+
* @param tools The list of tool registrations
68+
* @param resources The map of resource registrations
69+
* @param resourceTemplates The list of resource templates
70+
* @param prompts The map of prompt registrations
6871
*/
6972
public McpAsyncServer(McpTransport mcpTransport, McpSchema.Implementation serverInfo,
7073
McpSchema.ServerCapabilities serverCapabilities, List<ToolRegistration> tools,
@@ -407,28 +410,32 @@ private DefaultMcpSession.RequestHandler promptsGetRequestHandler() {
407410
}
408411

409412
/**
410-
* Notify clients that the list of available tools has changed.
413+
* Notifies clients that the list of available tools has changed.
414+
* @return A Mono that completes when all clients have been notified
411415
*/
412416
public Mono<Void> notifyToolsListChanged() {
413417
return this.mcpSession.sendNotification("notifications/tools/list_changed", null);
414418
}
415419

416420
/**
417-
* Notify clients that the list of available resources has changed.
421+
* Notifies clients that the list of available resources has changed.
422+
* @return A Mono that completes when all clients have been notified
418423
*/
419424
public Mono<Void> notifyResourcesListChanged() {
420425
return this.mcpSession.sendNotification("notifications/resources/list_changed", null);
421426
}
422427

423428
/**
424-
* Notify clients that the list of available prompts has changed.
429+
* Notifies clients that the list of available prompts has changed.
430+
* @return A Mono that completes when all clients have been notified
425431
*/
426432
public Mono<Void> notifyPromptsListChanged() {
427433
return this.mcpSession.sendNotification("notifications/prompts/list_changed", null);
428434
}
429435

430436
/**
431-
* Close the server gracefully.
437+
* Gracefully closes the server, allowing any in-progress operations to complete.
438+
* @return A Mono that completes when the server has been closed
432439
*/
433440
public Mono<Void> closeGracefully() {
434441
return this.mcpSession.closeGracefully();

‎mcp/src/main/java/org/springframework/ai/mcp/spec/McpSchema.java‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@
3232

3333
/**
3434
* Based on the <a href="http://www.jsonrpc.org/specification">JSON-RPC 2.0
35-
* specification<a/> and the <a href=
35+
* specification</a> and the <a href=
3636
* "https://github.com/modelcontextprotocol/specification/blob/main/schema/schema.ts">Model
3737
* Context Protocol Schema</a>.
3838
*
@@ -47,16 +47,34 @@ public class McpSchema {
4747
// ---------------------------
4848
// JSON-RPC Error Codes
4949
// ---------------------------
50+
/**
51+
* Standard error codes used in MCP JSON-RPC responses.
52+
*/
5053
public final class ErrorCodes {
5154

55+
/**
56+
* Invalid JSON was received by the server.
57+
*/
5258
public static final int PARSE_ERROR = -32700;
5359

60+
/**
61+
* The JSON sent is not a valid Request object.
62+
*/
5463
public static final int INVALID_REQUEST = -32600;
5564

65+
/**
66+
* The method does not exist / is not available.
67+
*/
5668
public static final int METHOD_NOT_FOUND = -32601;
5769

70+
/**
71+
* Invalid method parameter(s).
72+
*/
5873
public static final int INVALID_PARAMS = -32602;
5974

75+
/**
76+
* Internal JSON-RPC error.
77+
*/
6078
public static final int INTERNAL_ERROR = -32603;
6179

6280
}
@@ -340,6 +358,9 @@ public interface Annotated {
340358
}
341359

342360
/**
361+
* Optional annotations for the client. The client can use annotations to inform how
362+
* objects are used or displayed.
363+
*
343364
* @param audience Describes who the intended customer of this object or data is. It
344365
* can include multiple entries to indicate content useful for multiple audiences
345366
* (e.g., `["user", "assistant"]`).
@@ -544,6 +565,10 @@ public record PromptMessage( // @formatter:off
544565

545566
/**
546567
* The server's response to a prompts/list request from the client.
568+
*
569+
* @param prompts A list of prompts that the server provides.
570+
* @param nextCursor An optional cursor for pagination. If present, indicates there
571+
* are more prompts available.
547572
*/
548573
@JsonInclude(JsonInclude.Include.NON_ABSENT)
549574
public record ListPromptsResult( // @formatter:off
@@ -856,6 +881,9 @@ public record Root( // @formatter:off
856881
* The client's response to a roots/list request from the server. This result contains
857882
* an array of Root objects, each representing a root directory or file that the
858883
* server can operate on.
884+
*
885+
* @param roots An array of Root objects, each representing a root directory or file
886+
* that the server can operate on.
859887
*/
860888
@JsonInclude(JsonInclude.Include.NON_ABSENT)
861889
public record ListRootsResult( // @formatter:off

0 commit comments

Comments
 (0)