feat: add SSE transport and improve documentation

- Add Server-Sent Events (SSE) transport implementation with test coverage
- Add detailed documentation for both SSE and STDIO transports
- Extract common test logic into abstract base classes
- Add testcontainers support for SSE integration tests
- Replace System.out with SLF4J logging
- Externalize dependency versions to properties
- Implement endpoint event handling per MCP spec
- Add message endpoint sink for reliable message routing
- Improve error handling and graceful shutdown
- Update core module README with expanded features and examples
- Add dependency version properties and logging configuration
- Update architecture and class diagrams

Resolves #4

Author: tzolov

README.md

@@ -12,15 +12,17 @@ Spring AI MCP is an experimental project that provides Java and Spring Framework
 
 The project consists of two main modules:
 
-### spring-ai-mcp-core
+### [spring-ai-mcp-core](./spring-ai-mcp-core/README.md)
 
 The core module provides a Java implementation of the Model Context Protocol specification. It includes:
 - Synchronous and asynchronous client implementations
 - Standard MCP operations support (tool discovery, resource management, prompt handling)
 - Stdio-based server transport
 - Reactive programming support using Project Reactor
 
-### spring-ai-mcp-spring
+[find more](./spring-ai-mcp-core/README.md)
+
+### [spring-ai-mcp-spring](./spring-ai-mcp-spring/README.md)
 
 The Spring integration module provides Spring-specific functionality:
 - Integration with Spring AI's function calling system

pom.xml

@@ -70,7 +70,12 @@
 		<assert4j.version>3.26.3</assert4j.version>
 		<junit.version>5.11.3</junit.version>
 		<mockito.version>5.11.0</mockito.version>
+		<testcontainers.version>1.20.4</testcontainers.version>
 
+		<slf4j-api.version>2.0.16</slf4j-api.version>
+		<logback.version>1.5.12</logback.version>
+		<jackson.version>2.18.2</jackson.version>
+		<springframework.version>6.1.13</springframework.version>
 
 		<!-- plugin versions -->
 		<maven-compiler-plugin.version>3.11.0</maven-compiler-plugin.version>
@@ -347,4 +352,4 @@
 		</repository>
 	</repositories>
 
-</project>
+</project>

spring-ai-mcp-architecture.jpg

@@ -10,13 +10,19 @@ This SDK implements the Model Context Protocol, enabling seamless integration wi
 
 - Synchronous and Asynchronous client implementations
 - Standard MCP operations support:
+  - Protocol version compatibility negotiation
+  - Client-server capability exchange
   - Tool discovery and execution
-  - Resource management and templates
-  - Prompt handling and management
+  - Resource management with URI templates
   - Resource subscription system
+  - Prompt handling and management
   - Server initialization and ping
-- Stdio-based server transport
+- Multiple transport implementations:
+  - Stdio-based transport for process-based communication
+  - SSE-based transport for HTTP streaming
 - Reactive programming support using Project Reactor
+- Configurable request timeouts
+- Customizable JSON serialization/deserialization
 
 ## Installation
 
@@ -38,6 +44,41 @@ Detailed UML class diagrams showing the relationships between components can be
 
 ## Usage
 
+### Transport Layer Options
+
+The SDK provides two transport implementations:
+
+#### StdioServerTransport
+Standard I/O based transport for process-based communication with MCP servers:
+
+```java
+ServerParameters params = ServerParameters.builder("npx")
+    .args("-y", "@modelcontextprotocol/server-everything", "dir")
+    .build();
+McpTransport transport = new StdioServerTransport(params);
+```
+
+#### SseServerTransport
+Server-Sent Events (SSE) based transport following the MCP HTTP with SSE transport specification:
+
+```java
+WebClient.Builder webClientBuilder = WebClient.builder()
+    .baseUrl("http://your-mcp-server");
+McpTransport transport = new SseServerTransport(webClientBuilder);
+
+// Or with custom ObjectMapper
+ObjectMapper mapper = new ObjectMapper();
+McpTransport transport = new SseServerTransport(webClientBuilder, mapper);
+```
+
+The SSE transport provides:
+- Bidirectional communication over HTTP
+- Automatic reconnection for transient failures
+- Inbound message streaming via SSE
+- Outbound message delivery via HTTP POST
+- Graceful shutdown handling
+- Configurable JSON serialization
+
 ### Sync Client Example
 
 ```java
@@ -47,139 +88,144 @@ ServerParameters params = ServerParameters.builder("npx")
     .build();
 
 try (McpSyncClient client = McpClient.sync(new StdioServerTransport(params))) {
-    // Initialize connection
+    // Initialize connection with protocol version and capabilities
     McpSchema.InitializeResult initResult = client.initialize();
 
-    // List tools synchronously
-    McpSchema.ListToolsResult tools = client.listTools(null);
+    // List available tools
+    McpSchema.ListToolsResult tools = client.listTools();
 
-    // Call tool synchronously
+    // Execute a tool
     McpSchema.CallToolResult result = client.callTool(
         new McpSchema.CallToolRequest("echo", Map.of("message", "Hello!"))
     );
 
     // Resource management
-    McpSchema.ListResourcesResult resources = client.listResources(null);
+    McpSchema.ListResourcesResult resources = client.listResources();
     McpSchema.ReadResourceResult resource = client.readResource(
         new McpSchema.ReadResourceRequest("resource-uri")
     );
 
-    // Prompt management
-    ListPromptsResult prompts = client.listPrompts(null);
+    // List and retrieve prompts
+    ListPromptsResult prompts = client.listPrompts();
     GetPromptResult prompt = client.getPrompt(
         new McpSchema.GetPromptRequest("prompt-id", Map.of())
     );
 }
 ```
 
-### Async Client Example
+### Async Client Example with Custom Configuration
 
 ```java
 // Create server parameters
 ServerParameters params = ServerParameters.builder("npx")
     .args("-y", "@modelcontextprotocol/server-everything", "dir")
     .build();
 
-// Initialize the async client
+// Initialize async client with custom timeout and object mapper
 McpAsyncClient client = McpClient.async(
-    new StdioServerTransport(params)
+    new StdioServerTransport(params),
+    Duration.ofSeconds(30),
+    new ObjectMapper()
 );
 
-// Initialize the connection
-var promptResult = client.initialize()
-    flatMap(result -> {
-        // Connection initialized
-        return client.listTools(null);
+// Initialize connection and chain operations
+var result = client.initialize()
+    .flatMap(initResult -> {
+        // Connection initialized with protocol version compatibility
+        return client.listTools();
     })
     .flatMap(tools -> {
-        // Process tools
+        // Process available tools
         return client.callTool(new McpSchema.CallToolRequest("echo",
             Map.of("message", "Hello MCP!")));
     })
-    .flatMap(result -> {
-        // Handle tool result
-        return client.listPrompts(null);
+    .flatMap(toolResult -> {
+        // Handle tool execution result
+        return client.listPrompts();
     })
     .flatMap(prompts -> {
         // Process available prompts
         return client.getPrompt(new McpSchema.GetPromptRequest("prompt-id", Map.of()));
     });
 
-// Handle prompt result, e.g. by blocking on it
-McpSchema.GetPromptResult result = promptResult.block();
-
-// Resource management example
-var resourcesResult = client.listResources(null)
+// Subscribe to resource changes
+var subscription = client.listResources()
     .flatMap(resources -> {
-        // Subscribe to resource changes
         return client.subscribeResource(new McpSchema.SubscribeRequest("resource-uri"));
     });
 
-// Handle resources result
-resourcesResult.block();
+// Handle results reactively or block if needed
+McpSchema.GetPromptResult promptResult = result.block();
+subscription.block();
 
 // Cleanup
 client.closeGracefully().block();
 ```
 
 ## Architecture
 
-The SDK follows a layered architecture:
+The SDK follows a layered architecture with clear separation of concerns:
 
 ### Core Components
 
-- **McpClient**: Factory class for creating sync and async clients
-- **McpAsyncClient**: Primary async implementation using Project Reactor
-- **McpSyncClient**: Synchronous wrapper around the async client
+- **McpClient**: Factory class for creating sync and async clients with optional custom configuration
+- **McpAsyncClient**: Primary async implementation using Project Reactor for non-blocking operations
+- **McpSyncClient**: Synchronous wrapper around the async client for blocking operations
 - **McpSession**: Core session interface defining communication patterns
-- **McpTransport**: Transport layer interface
+- **McpTransport**: Transport layer interface for server communication
 - **McpSchema**: Comprehensive protocol schema definitions
-- **AbstractMcpTransport**: Base transport implementation
-- **StdioServerTransport**: Stdio-based server communication
+- **DefaultMcpSession**: Base implementation of the session management
+- **StdioServerTransport**: Standard I/O based server communication
+- **SseServerTransport**: HTTP-based transport using Server-Sent Events for bidirectional communication
 
 <img src="docs/spring-ai-mcp-uml-classdiagram.svg" width="600"/>
 
 ### Key Interactions
 
-1. Client initialization
-   - Transport setup
-   - Server connection establishment
-   - Protocol handshake
+1. Client Initialization
+   - Transport setup and connection establishment
+   - Protocol version compatibility check
+   - Capability negotiation
+   - Implementation details exchange
 
 2. Message Flow
-   - JSON-RPC message creation
+   - JSON-RPC message creation and validation
    - Transport layer handling
-   - Response processing
-   - Error handling
+   - Response processing with type safety
+   - Error handling with specific error codes
 
 3. Resource Management
-   - Resource listing and reading
-   - Template management
-   - Subscription handling
-   - Change notifications
+   - Resource discovery and listing
+   - URI template-based resource access
+   - Subscription system for change notifications
+   - Resource content retrieval
 
 4. Prompt System
-   - Prompt discovery
-   - Prompt retrieval
-   - Change notifications
+   - Prompt discovery and listing
+   - Parameter-based prompt retrieval
+   - Change notifications support
+   - Prompt content management
 
 5. Tool Execution
-   - Tool discovery
-   - Parameter validation
-   - Execution handling
-   - Result processing
+   - Tool discovery and capability checking
+   - Parameter validation and processing
+   - Execution handling with timeout support
+   - Result processing with error handling
 
 ## Error Handling
 
 The SDK provides comprehensive error handling through the McpError class:
 
-- Transport-level errors
-- Protocol violations
+- Protocol version incompatibility
+- Transport-level communication errors
+- JSON-RPC protocol violations
 - Tool execution failures
-- Resource access errors
-- Subscription handling errors
+- Resource access and subscription errors
 - Prompt management errors
-- Timeout handling
+- Request timeout handling
+- Server capability mismatches
+- SSE connection failures and retry handling
+- HTTP request/response errors
 
 ## Contributing