docs: improve Java SDK documentation and examples (#145)

- Fix typos and update links in quickstart guides
- Update artifact names and configuration properties
- Add detailed configuration examples and advanced features
- Enhance Java SDK client/server documentation
- Update architecture diagrams and descriptions
- Improve code examples with better comments
- Update Spring Boot version requirements

Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>

sdk/java/mcp-client.mdx

@@ -214,16 +214,16 @@ This capability allows:
 
 ### Tool Execution
 
-Tools are server-side functions that can be discovered and executed by clients. The client provides methods to list available tools and execute them with parameters.
+Tools are server-side functions that clients can discover and execute. The MCP client provides methods to list available tools and execute them with specific parameters. Each tool has a unique name and accepts a map of parameters.
 
 <Tabs>
   <Tab title="Sync API">
 ```java
-// List available tools
+// List available tools and their names
 var tools = client.listTools();
 tools.forEach(tool -> System.out.println(tool.getName()));
 
-// Execute a tool
+// Execute a tool with parameters
 var result = client.callTool("calculator", Map.of(
     "operation", "add",
     "a", 1,
@@ -234,13 +234,13 @@ var result = client.callTool("calculator", Map.of(
 
   <Tab title="Async API">
 ```java
-// List available tools
+// List available tools asynchronously
 client.listTools()
     .doOnNext(tools -> tools.forEach(tool -> 
         System.out.println(tool.getName())))
     .subscribe();
 
-// Execute a tool
+// Execute a tool asynchronously
 client.callTool("calculator", Map.of(
         "operation", "add",
         "a", 1,
@@ -253,16 +253,16 @@ client.callTool("calculator", Map.of(
 
 ### Resource Access
 
-Resources are server-side data sources that can be accessed by clients using URI templates. The client provides methods to list available resources and retrieve their content.
+Resources represent server-side data sources that clients can access using URI templates. The MCP client provides methods to discover available resources and retrieve their contents through a standardized interface.
 
 <Tabs>
   <Tab title="Sync API">
 ```java
-// List available resources
+// List available resources and their names
 var resources = client.listResources();
 resources.forEach(resource -> System.out.println(resource.getName()));
 
-// Get a resource
+// Retrieve resource content using a URI template
 var content = client.getResource("file", Map.of(
     "path", "/path/to/file.txt"
 ));
@@ -271,13 +271,13 @@ var content = client.getResource("file", Map.of(
 
   <Tab title="Async API">
 ```java
-// List available resources
+// List available resources asynchronously
 client.listResources()
     .doOnNext(resources -> resources.forEach(resource -> 
         System.out.println(resource.getName())))
     .subscribe();
 
-// Get a resource
+// Retrieve resource content asynchronously
 client.getResource("file", Map.of(
         "path", "/path/to/file.txt"
     ))
@@ -288,16 +288,16 @@ client.getResource("file", Map.of(
 
 ### Prompt System
 
-The prompt system allows clients to interact with server-side prompt templates. The client provides methods to list available prompts and execute them with parameters.
+The prompt system enables interaction with server-side prompt templates. These templates can be discovered and executed with custom parameters, allowing for dynamic text generation based on predefined patterns.
 
 <Tabs>
   <Tab title="Sync API">
 ```java
-// List available prompts
+// List available prompt templates
 var prompts = client.listPrompts();
 prompts.forEach(prompt -> System.out.println(prompt.getName()));
 
-// Execute a prompt
+// Execute a prompt template with parameters
 var response = client.executePrompt("echo", Map.of(
     "text", "Hello, World!"
 ));
@@ -306,13 +306,13 @@ var response = client.executePrompt("echo", Map.of(
 
   <Tab title="Async API">
 ```java
-// List available prompts
+// List available prompt templates asynchronously
 client.listPrompts()
     .doOnNext(prompts -> prompts.forEach(prompt -> 
         System.out.println(prompt.getName())))
     .subscribe();
 
-// Execute a prompt
+// Execute a prompt template asynchronously
 client.executePrompt("echo", Map.of(
         "text", "Hello, World!"
     ))

sdk/java/mcp-overview.mdx

@@ -8,9 +8,7 @@ enables standardized integration between AI models and tools.
 
 ## Features
 
-- MCP Client and MCP Server implementations
-- Supports Synchronous and Asynchronous programming paradigms
-- Standard MCP operations support:
+- MCP Client and MCP Server implementations supporting:
   - Protocol [version compatibility negotiation](https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/lifecycle/#initialization)
   - [Tool](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/tools/) discovery, execution, list change notifications
   - [Resource](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/resources/) management with URI templates
@@ -18,21 +16,21 @@ enables standardized integration between AI models and tools.
   - [Prompt](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/prompts/) handling and management
   - [Sampling](https://spec.modelcontextprotocol.io/specification/2024-11-05/client/sampling/) support for AI model interactions
 - Multiple transport implementations:
-  - Core transports:
+  - Default transports:
     - Stdio-based transport for process-based communication
     - Java HttpClient-based SSE client transport for HTTP SSE Client-side streaming
     - Servlet-based SSE server transport for HTTP SSE Server streaming
   - Spring-based transports:
-    - WebFlux SSE transport for reactive HTTP streaming
+    - WebFlux SSE client and server transports for reactive HTTP streaming
     - WebMVC SSE transport for servlet-based HTTP streaming
+- Supports Synchronous and Asynchronous programming paradigms
 
 ## Architecture
 
-![Java MCP Client Architecture](/images/java/java-mcp-client-architecture.jpg)
-![Java MCP Server Architecture](/images/java/java-mcp-server-architecture.jpg)
-
 The SDK follows a layered architecture with clear separation of concerns:
 
+![MCP Stack Architecture](/images/java/mcp-stack.svg)
+
 - **Client/Server Layer (McpClient/McpServer)**: Both use McpSession for sync/async operations,
 with McpClient handling client-side protocol operations and McpServer managing server-side protocol operations.
 - **Session Layer (McpSession)**: Manages communication patterns and state using DefaultMcpSession implementation.
@@ -40,13 +38,16 @@ with McpClient handling client-side protocol operations and McpServer managing s
   - StdioTransport (stdin/stdout) in the core module
   - HTTP SSE transports in dedicated transport modules (Java HttpClient, Spring WebFlux, Spring WebMVC)
 
-![MCP Stack Architecture](/images/java/mcp-stack.svg)
 
-The following class diagram illustrates the layered architecture of the MCP SDK, showing
-the relationships between core interfaces (McpTransport, McpSession), their implementations,
-and the client/server components. It highlights how the transport layer connects to sessions, which in turn support both synchronous and asynchronous client/server implementations.
+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.
 
-![MCP SDK Class Diagram](/images/java/java-mcp-uml-classdiagram.svg)
+![Java MCP Client Architecture](/images/java/java-mcp-client-architecture.jpg)
+
+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.
+
+![Java MCP Server Architecture](/images/java/java-mcp-server-architecture.jpg)
 
 Key Interactions: