diff --git a/mcp/src/main/java/org/springframework/ai/mcp/client/McpClient.java b/mcp/src/main/java/org/springframework/ai/mcp/client/McpClient.java index 9f49924..bea9478 100644 --- a/mcp/src/main/java/org/springframework/ai/mcp/client/McpClient.java +++ b/mcp/src/main/java/org/springframework/ai/mcp/client/McpClient.java @@ -34,33 +34,37 @@ import org.springframework.ai.mcp.spec.McpTransport; import org.springframework.ai.mcp.util.Assert; /** - * Factory class for creating Model Context Protocol (MCP) clients. MCP is a protocol that enables - * AI models to interact with external tools and resources through a standardized interface. - * - *

This class serves as the main entry point for establishing connections with MCP servers, - * implementing the client-side of the MCP specification. The protocol follows a client-server - * architecture where: + * Factory class for creating Model Context Protocol (MCP) clients. MCP is a protocol that + * enables AI models to interact with external tools and resources through a standardized + * interface. + * + *

+ * This class serves as the main entry point for establishing connections with MCP + * servers, implementing the client-side of the MCP specification. The protocol follows a + * client-server architecture where: *

* - *

The class provides factory methods to create either: + *

+ * The class provides factory methods to create either: *

* - *

Example of creating a basic client: - * 

{@code
+ * 

+ * Example of creating a basic client: 
{@code
  * McpClient.using(transport)
  *     .requestTimeout(Duration.ofSeconds(5))
  *     .sync(); // or .async()
  * }

  *
- * 
Example with advanced configuration:
- * 
{@code
+ * 

+ * Example with advanced configuration: 
{@code
  * McpClient.using(transport)
  *     .requestTimeout(Duration.ofSeconds(10))
  *     .capabilities(new ClientCapabilities(...))
@@ -70,7 +74,8 @@ import org.springframework.ai.mcp.util.Assert;
  *     .async();
  * }

  *
- * 
The client supports:
+ * 

+ * The client supports:
  * 

-		 *
-		 * @param serverCapabilities The server capabilities configuration. Must not be null.
+		 * @param serverCapabilities The server capabilities configuration. Must not be
+		 * null.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if serverCapabilities is null
 		 */
@@ -299,20 +299,19 @@ public interface McpServer {
 		}
 
 		/**
-		 * Adds a single tool with its implementation handler to the server. This is
-		 * a convenience method for registering individual tools without creating a
+		 * Adds a single tool with its implementation handler to the server. This is a
+		 * convenience method for registering individual tools without creating a
 		 * {@link ToolRegistration} explicitly.
 		 *
-		 * 
Example usage:
-		 * 
{@code
+		 * 

+		 * Example usage: 
{@code
 		 * .tool(
 		 *     new Tool("calculator", "Performs calculations", schema),
 		 *     args -> new CallToolResult("Result: " + calculate(args))
 		 * )
 		 * }

-		 *
-		 * @param tool The tool definition including name, description, and schema.
-		 *             Must not be null.
+		 * @param tool The tool definition including name, description, and schema. Must
+		 * not be null.
 		 * @param handler The function that implements the tool's logic. Must not be null.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if tool or handler is null
@@ -327,12 +326,11 @@ public interface McpServer {
 		}
 
 		/**
-		 * Adds multiple tools with their handlers to the server using a List.
-		 * This method is useful when tools are dynamically generated or loaded
-		 * from a configuration source.
-		 *
-		 * @param toolRegistrations The list of tool registrations to add.
-		 *                          Must not be null.
+		 * Adds multiple tools with their handlers to the server using a List. This method
+		 * is useful when tools are dynamically generated or loaded from a configuration
+		 * source.
+		 * @param toolRegistrations The list of tool registrations to add. Must not be
+		 * null.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if toolRegistrations is null
 		 * @see #tools(ToolRegistration...)
@@ -344,18 +342,17 @@ public interface McpServer {
 		}
 
 		/**
-		 * Adds multiple tools with their handlers to the server using varargs.
-		 * This method provides a convenient way to register multiple tools inline.
+		 * Adds multiple tools with their handlers to the server using varargs. This
+		 * method provides a convenient way to register multiple tools inline.
 		 *
-		 * 
Example usage:
-		 * 
{@code
+		 * 

+		 * Example usage: 
{@code
 		 * .tools(
 		 *     new ToolRegistration(calculatorTool, calculatorHandler),
 		 *     new ToolRegistration(weatherTool, weatherHandler),
 		 *     new ToolRegistration(fileManagerTool, fileManagerHandler)
 		 * )
 		 * }

-		 *
 		 * @param toolRegistrations The tool registrations to add. Must not be null.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if toolRegistrations is null
@@ -369,12 +366,11 @@ public interface McpServer {
 		}
 
 		/**
-		 * Registers multiple resources with their handlers using a Map.
-		 * This method is useful when resources are dynamically generated
-		 * or loaded from a configuration source.
-		 *
-		 * @param resourceRegsitrations Map of resource name to registration.
-		 *                              Must not be null.
+		 * Registers multiple resources with their handlers using a Map. This method is
+		 * useful when resources are dynamically generated or loaded from a configuration
+		 * source.
+		 * @param resourceRegsitrations Map of resource name to registration. Must not be
+		 * null.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if resourceRegsitrations is null
 		 * @see #resources(ResourceRegistration...)
@@ -386,12 +382,9 @@ public interface McpServer {
 		}
 
 		/**
-		 * Registers multiple resources with their handlers using a List.
-		 * This method is useful when resources need to be added in bulk
-		 * from a collection.
-		 *
-		 * @param resourceRegsitrations List of resource registrations.
-		 *                              Must not be null.
+		 * Registers multiple resources with their handlers using a List. This method is
+		 * useful when resources need to be added in bulk from a collection.
+		 * @param resourceRegsitrations List of resource registrations. Must not be null.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if resourceRegsitrations is null
 		 * @see #resources(ResourceRegistration...)
@@ -405,21 +398,19 @@ public interface McpServer {
 		}
 
 		/**
-		 * Registers multiple resources with their handlers using varargs.
-		 * This method provides a convenient way to register multiple
-		 * resources inline.
+		 * Registers multiple resources with their handlers using varargs. This method
+		 * provides a convenient way to register multiple resources inline.
 		 *
-		 * 
Example usage:
-		 * 
{@code
+		 * 

+		 * Example usage: 
{@code
 		 * .resources(
 		 *     new ResourceRegistration(fileResource, fileHandler),
 		 *     new ResourceRegistration(dbResource, dbHandler),
 		 *     new ResourceRegistration(apiResource, apiHandler)
 		 * )
 		 * }

-		 *
-		 * @param resourceRegistrations The resource registrations to add.
-		 *                             Must not be null.
+		 * @param resourceRegistrations The resource registrations to add. Must not be
+		 * null.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if resourceRegistrations is null
 		 */
@@ -432,20 +423,18 @@ public interface McpServer {
 		}
 
 		/**
-		 * Sets the resource templates that define patterns for dynamic resource
-		 * access. Templates use URI patterns with placeholders that can be
-		 * filled at runtime.
+		 * Sets the resource templates that define patterns for dynamic resource access.
+		 * Templates use URI patterns with placeholders that can be filled at runtime.
 		 *
-		 * 
Example usage:
-		 * 
{@code
+		 * 

+		 * Example usage: 
{@code
 		 * .resourceTemplates(
 		 *     new ResourceTemplate("file://{path}", "Access files by path"),
 		 *     new ResourceTemplate("db://{table}/{id}", "Access database records")
 		 * )
 		 * }

-		 *
-		 * @param resourceTemplates List of resource templates. If null, clears
-		 *                         existing templates.
+		 * @param resourceTemplates List of resource templates. If null, clears existing
+		 * templates.
 		 * @return This builder instance for method chaining
 		 * @see #resourceTemplates(ResourceTemplate...)
 		 */
@@ -455,9 +444,8 @@ public interface McpServer {
 		}
 
 		/**
-		 * Sets the resource templates using varargs for convenience.
-		 * This is an alternative to {@link #resourceTemplates(List)}.
-		 *
+		 * Sets the resource templates using varargs for convenience. This is an
+		 * alternative to {@link #resourceTemplates(List)}.
 		 * @param resourceTemplates The resource templates to set.
 		 * @return This builder instance for method chaining
 		 * @see #resourceTemplates(List)
@@ -470,12 +458,12 @@ public interface McpServer {
 		}
 
 		/**
-		 * Registers multiple prompts with their handlers using a Map.
-		 * This method is useful when prompts are dynamically generated
-		 * or loaded from a configuration source.
+		 * Registers multiple prompts with their handlers using a Map. This method is
+		 * useful when prompts are dynamically generated or loaded from a configuration
+		 * source.
 		 *
-		 * 
Example usage:
-		 * 
{@code
+		 * 

+		 * Example usage: 
{@code
 		 * Map prompts = new HashMap<>();
 		 * prompts.put("analysis", new PromptRegistration(
 		 *     new Prompt("analysis", "Code analysis template"),
@@ -483,7 +471,6 @@ public interface McpServer {
 		 * ));
 		 * .prompts(prompts)
 		 * }

-		 *
 		 * @param prompts Map of prompt name to registration. Must not be null.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if prompts is null
@@ -494,10 +481,8 @@ public interface McpServer {
 		}
 
 		/**
-		 * Registers multiple prompts with their handlers using a List.
-		 * This method is useful when prompts need to be added in bulk
-		 * from a collection.
-		 *
+		 * Registers multiple prompts with their handlers using a List. This method is
+		 * useful when prompts need to be added in bulk from a collection.
 		 * @param prompts List of prompt registrations. Must not be null.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if prompts is null
@@ -511,19 +496,17 @@ public interface McpServer {
 		}
 
 		/**
-		 * Registers multiple prompts with their handlers using varargs.
-		 * This method provides a convenient way to register multiple
-		 * prompts inline.
+		 * Registers multiple prompts with their handlers using varargs. This method
+		 * provides a convenient way to register multiple prompts inline.
 		 *
-		 * 
Example usage:
-		 * 
{@code
+		 * 

+		 * Example usage: 
{@code
 		 * .prompts(
 		 *     new PromptRegistration(analysisPrompt, analysisHandler),
 		 *     new PromptRegistration(summaryPrompt, summaryHandler),
 		 *     new PromptRegistration(reviewPrompt, reviewHandler)
 		 * )
 		 * }

-		 *
 		 * @param prompts The prompt registrations to add. Must not be null.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if prompts is null
@@ -536,13 +519,12 @@ public interface McpServer {
 		}
 
 		/**
-		 * Builds a synchronous MCP server that provides blocking operations.
-		 * Synchronous servers process each request to completion before handling
-		 * the next one, making them simpler to implement but potentially less
-		 * performant for concurrent operations.
-		 *
-		 * @return A new instance of {@link McpSyncServer} configured with this
-		 *         builder's settings
+		 * Builds a synchronous MCP server that provides blocking operations. Synchronous
+		 * servers process each request to completion before handling the next one, making
+		 * them simpler to implement but potentially less performant for concurrent
+		 * operations.
+		 * @return A new instance of {@link McpSyncServer} configured with this builder's
+		 * settings
 		 */
 		public McpSyncServer sync() {
 			return new McpSyncServer(async());
@@ -551,11 +533,10 @@ public interface McpServer {
 		/**
 		 * Builds an asynchronous MCP server that provides non-blocking operations.
 		 * Asynchronous servers can handle multiple requests concurrently using
-		 * CompletableFuture, making them more efficient for high-concurrency
-		 * scenarios but more complex to implement.
-		 *
-		 * @return A new instance of {@link McpAsyncServer} configured with this
-		 *         builder's settings
+		 * CompletableFuture, making them more efficient for high-concurrency scenarios
+		 * but more complex to implement.
+		 * @return A new instance of {@link McpAsyncServer} configured with this builder's
+		 * settings
 		 */
 		public McpAsyncServer async() {
 			if (serverInfo == null) {