docs: enhance MCP documentation with customization details and examples

- Expand client customization documentation with detailed sections
- Add comprehensive descriptions of MCP components and capabilities
- Improve code examples and explanations
- Add example applications sections for both client and server
- Fix typos and enhance overall documentation structure

Signed-off-by: Christian Tzolov <[email protected]>

Author: tzolov

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/mcp/mcp-client-boot-starter-docs.adoc

@@ -203,9 +203,26 @@ The starter supports two types of clients:
 
 === Client Customization
 
-The auto-configuration supports client spec customization.
-Implement the `McpSyncClientCustomizer` callback interface to customize the `McpClient.SyncSpec` spec for a named server connection.
-Similarly, the `McpAsyncClientCustomizer` interface allows customizing the `McpClient.AsyncSpec` spec for asynchronous clients.
+The auto-configuration provides extensive client spec customization capabilities through callback interfaces. These customizers allow you to configure various aspects of the MCP client behavior, from request timeouts to event handling and message processing.
+
+==== Customization Types
+
+The following customization options are available:
+
+* *Request Configuration* - Set custom request timeouts
+* link:https://spec.modelcontextprotocol.io/specification/2024-11-05/client/sampling/[*Custom Sampling Handlers*] - standardized way for servers to request LLM sampling (`completions` or `generations`) from LLMs via clients. This flow allows clients to maintain control over model access, selection, and permissions while enabling servers to leverage AI capabilities — with no server API keys necessary. 
+* link:https://spec.modelcontextprotocol.io/specification/2024-11-05/client/roots/[*File system (Roots) Access*] - standardized way for clients to expose filesystem `roots` to servers. 
+Roots define the boundaries of where servers can operate within the filesystem, allowing them to understand which directories and files they have access to. 
+Servers can request the list of roots from supporting clients and receive notifications when that list changes.
+* *Event Handlers*  - client's handler to be notified when a certain server event occurs:
+  - Tools change notifications - when the list of available server tools changes
+  - Resources change notifications - when the list of available server resources changes.
+  - Prompts change notifications - when the list of available server prompts changes.
+* link:https://spec.modelcontextprotocol.io/specification/2024-11-05/server/utilities/logging/[*Logging Handlers*] - standardized way for servers to send structured log messages to clients. 
+Clients can control logging verbosity by setting minimum log levels
+
+
+You can implement either `McpSyncClientCustomizer` for synchronous clients or `McpAsyncClientCustomizer` for asynchronous clients, depending on your application's needs.
 
 [tabs]
 ======
@@ -216,27 +233,34 @@ Sync::
 @Component
 public class CustomMcpSyncClientCustomizer implements McpSyncClientCustomizer {
     @Override
-    public void customize(String name, McpClient.SyncSpec spec) {
+    public void customize(String serverConfiurationName, McpClient.SyncSpec spec) {
 
-        // Customize the sync client configuration
+        // Customize the request configuration
         spec.requestTimeout(Duration.ofSeconds(30));
 
-        // Adds a consumer to be notified when the available tools change. This allows the
-		    // client to react to changes in the server's tool capabilities, such as tools
-		    // being added or removed.
+        // Sets the root URIs that the server connecto this client can access. 
+        spec.roots(roots);
+
+        // Sets a custom sampling handler for processing message creation requests.
+        spec.sampling((CreateMessageRequest messageRequest) -> {
+            // Handle sampling
+            CreateMessageResult result = ...
+            return result;
+        });
+
+        // Adds a consumer to be notified when the available tools change, such as tools
+        // being added or removed.
         spec.toolsChangeConsumer((List<McpSchema.Tool> tools) -> {
             // Handle tools change
         });
 
-        // Adds a consumer to be notified when the available resources change. This allows the
-        // client to react to changes in the server's resource capabilities, such as resources
+        // Adds a consumer to be notified when the available resources change, such as resources
         // being added or removed.
         spec.resourcesChangeConsumer((List<McpSchema.Resource> resources) -> {
             // Handle resources change
         });
 
-        // Adds a consumer to be notified when the available prompts change. This allows the
-        // client to react to changes in the server's prompt capabilities, such as prompts
+        // Adds a consumer to be notified when the available prompts change, such as prompts
         // being added or removed.
         spec.promptsChangeConsumer((List<McpSchema.Prompt> prompts) -> {
             // Handle prompts change
@@ -246,18 +270,6 @@ public class CustomMcpSyncClientCustomizer implements McpSyncClientCustomizer {
         spec.loggingConsumer((McpSchema.LoggingMessageNotification log) -> {
             // Handle log messages
         });
-
-        // Sets a custom sampling handler for processing message creation requests.
-        spec.sampling((CreateMessageRequest messageRequest) -> {
-            // Handle sampling
-            CreateMessageResult result = ...
-            return result;
-        });
-
-        // Sets the root URIs that the server connecto this client can access. 
-        // Roots define the base URIs for resources that the server can request.
-        // For example, a root might be "file://workspace" for accessing workspace files.
-        spec.roots(roots);
     }
 }
 ----
@@ -269,13 +281,14 @@ Async::
 @Component
 public class CustomMcpAsyncClientCustomizer implements McpAsyncClientCustomizer {
     @Override
-    public void customize(String name, McpClient.AsyncSpec spec) {
+    public void customize(String serverConfiurationName, McpClient.AsyncSpec spec) {
         // Customize the async client configuration
         spec.requestTimeout(Duration.ofSeconds(30));
     }
 }
 ----
 ======
+The `serverConfiurationName` parameter is the name of the server configuration that the customizer is being applied to and the the MCP Client is created for.
 
 The MCP client auto-configuration automatically detects and applies any customizers found in the application context.
 
@@ -346,6 +359,12 @@ Additionally, the registered MCP Tools with all MCP clients are provided as a li
 private List<ToolCallback> toolCallbacks;
 ----
 
+== Example Applications
+
+- link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/web-search/brave-chatbot[Brave Wet Search Chatbot] - A chatbot that uses the Model Context Protocol to interact with a web search server.
+- link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/client-starter/starter-default-client[Default MCP Client Starter] - A simple example of using the the default `spring-ai-mcp-client-spring-boot-starter` MCP Client Boot Starter.
+- link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/client-starter/starter-webflux-client[WebFlux MCP Client Starter] - A simple example of using the `spring-ai-mcp-client-webflux-spring-boot-starter` the MCP Client Boot Starter.
+
 == Additional Resources
 
 * link:https://docs.spring.io/spring-ai/reference/[Spring AI Documentation]

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/mcp/mcp-overview.adoc

@@ -1,29 +1,24 @@
 = Model Context Protocol (MCP)
 
 The link:https://modelcontextprotocol.org/docs/concepts/architecture[Model Context Protocol] (MCP) is a standardized protocol that enables AI models to interact with external tools and resources in a structured way. 
-It supports multiple transport mechanisms for flexibility in different environments.
-
-The link:https://modelcontextprotocol.github.io/sdk/java[Java MCP] provides a Java SDK implementation of the Model Context Protocol, enabling standardized interaction with AI models and tools through both synchronous and asynchronous communication.
+It supports multiple transport mechanisms to provide flexibility across different environments.
 
 == MCP Java SDK
 
+The link:https://modelcontextprotocol.github.io/sdk/java[MCP Java SDK] provides a Java implementation of the Model Context Protocol, enabling standardized interaction with AI models and tools through both synchronous and asynchronous communication patterns.
+
 The Java MCP implementation follows a three-layer architecture:
 
-// [cols="2,10"]
 |===
 |  |
 ^a| image::mcp/mcp-stack.svg[MCP Stack Architecture]
-a| * *Client/Server Layer*: The McpClient handles client-side and the McpServer manages server-side protocol operations.
-Both utilize McpSession for operations
-* *Session Layer (McpSession)*: Manages communication patterns and state.
-Uses the DefaultMcpSession implementation.
-* *Transport Layer (McpTransport)*: Handles JSON-RPC message serialization/deserialization.
-Supports multiple transport implementations.
+a| * *Client/Server Layer*: The McpClient handles client-side operations while the McpServer manages server-side protocol operations. Both utilize McpSession for communication management.
+* *Session Layer (McpSession)*: Manages communication patterns and state through the DefaultMcpSession implementation.
+* *Transport Layer (McpTransport)*: Handles JSON-RPC message serialization and deserialization with support for multiple transport implementations.
 |===
 
-// [cols="10,2"]
 |===
-| MCP Client |
+| link:https://modelcontextprotocol.io//sdk/java/mcp-client[MCP Client] |
 
 a| The MCP Client is a key component in the Model Context Protocol (MCP) architecture, responsible for establishing and managing connections with MCP servers. It implements the client-side of the protocol, handling:
 
@@ -33,31 +28,32 @@ a| The MCP Client is a key component in the Model Context Protocol (MCP) archite
 * Tool discovery and execution
 * Resource access and management
 * Prompt system interactions
-* Optional features like roots management and sampling support
+* Optional features:
+** Roots management
+** Sampling support
 * Synchronous and asynchronous operations
-* Multiple transport options:
+* Transport options:
 ** Stdio-based transport for process-based communication
 ** Java HttpClient-based SSE client transport
 ** WebFlux SSE client transport for reactive HTTP streaming
 
 ^a| image::mcp/java-mcp-client-architecture.jpg[Java MCP Client Architecture, width=500]
 |===
 
-// [cols="10,2"]
 |===
-| MCP Server |
+| link:https://modelcontextprotocol.io//sdk/java/mcp-server[MCP Server] |
 
 a| The MCP Server is a foundational component in the Model Context Protocol (MCP) architecture that provides tools, resources, and capabilities to clients. It implements the server-side of the protocol, responsible for:
 
-* Exposing tools that clients can discover and execute
-* Managing resources with URI-based access patterns
-* Providing prompt templates and handling prompt requests
-* Supporting capability negotiation with clients
-* Implementing server-side protocol operations
-* Managing concurrent client connections
-* Providing structured logging and notifications
-* Supporting both synchronous and asynchronous APIs for flexible integration
-* Multiple transport options:
+* Server-side protocol operations implementation
+** Tool exposure and discovery
+** Resource management with URI-based access
+** Prompt template provision and handling
+** Capability negotiation with clients
+** Structured logging and notifications
+* Concurrent client connection management
+* Synchronous and Asynchronous API support
+* Transport implementations:
 ** Stdio-based transport for process-based communication
 ** Servlet-based SSE server transport
 ** WebFlux SSE server transport for reactive HTTP streaming
@@ -66,21 +62,21 @@ a| The MCP Server is a foundational component in the Model Context Protocol (MCP
 ^a| image::mcp/java-mcp-server-architecture.jpg[Java MCP Server Architecture, width=600]
 |===
 
-For manual SDK implementation, refer to the link:https://modelcontextprotocol.github.io/sdk/java[MCP Java SDK documentation]. 
-For simplified setup, use the Spring AI MCP Boot Starters below.
+For detailed implementation guidance, using the low-level MCP Client/Server APIs, refer to the link:https://modelcontextprotocol.github.io/sdk/java[MCP Java SDK documentation].
+For simplified setup using Spring Boot, use the MCP Boot Starters described below.
 
 == Spring AI MCP Integration
 
-The Spring AI MCP integration is provided through Spring Boot starters:
+Spring AI provides MCP integration through the following Spring Boot starters:
 
 === link:mcp-client-boot-starter-docs.html[Client Starters]
-* `spring-ai-mcp-client-spring-boot-starter` - Core starter with STDIO and HTTP-based SSE support
-* `spring-ai-mcp-client-webflux-spring-boot-starter` - WebFlux-based SSE transport
+* `spring-ai-mcp-client-spring-boot-starter` - Core starter providing STDIO and HTTP-based SSE support
+* `spring-ai-mcp-client-webflux-spring-boot-starter` - WebFlux-based SSE transport implementation
 
 === link:mcp-server-boot-starter-docs.html[Server Starters]
-* `spring-ai-mcp-server-spring-boot-starter` - Core server with STDIO transport
-* `spring-ai-mcp-server-webmvc-spring-boot-starter` - Spring MVC-based SSE transport
-* `spring-ai-mcp-server-webflux-spring-boot-starter` - WebFlux-based SSE transport
+* `spring-ai-mcp-server-spring-boot-starter` - Core server with STDIO transport support
+* `spring-ai-mcp-server-webmvc-spring-boot-starter` - Spring MVC-based SSE transport implementation
+* `spring-ai-mcp-server-webflux-spring-boot-starter` - WebFlux-based SSE transport implementation
 
 == Additional Resources
 

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/mcp/mcp-server-boot-starter-docs.adoc

@@ -211,6 +211,12 @@ public class McpServerApplication {
 The auto-configuration will automatically register the toolcallbacs as MCP tools.
 You can have multiple beans producing list of ToolCallbacks. The autoconfiguration will merge them.
 
+== Example Applicaitons
+* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/weather/starter-webflux-server[Weather Server (WebFlux)] - Spring AI MCP Server Boot Starter with WebFlux transport.
+* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/weather/starter-stdio-server[Weather Server (STDIO)] - Spring AI MCP Server Boot Starter with STDIO transport.
+* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/book-library/starter-webflux-server[Book Library Server (WebFlux)] - Spring AI MCP Server Boot Starter with WebFlux transport.
+* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/weather/manual-webflux-server[Weather Server Manual Configuraiton] - Spring AI MCP Server Boot Starter that doesn't use autoconfiguration but the Java SDK to configure the server manually.
+
 == Additional Resources
 
 * link:https://docs.spring.io/spring-ai/reference/[Spring AI Documentation]