82c64f5ad3
- Add roots list capability to allow servers to understand filesystem boundaries - Move architecture diagram and add detailed documentation for transports and sessions - Enhance client capabilities with roots and sampling features - Rename withRequestTimeout to requestTimeout for better API consistency - Add tests for roots list functionality Resolves #8
144 lines
4.2 KiB
Markdown
144 lines
4.2 KiB
Markdown
# SSE Server Transport Implementation for MCP
|
|
|
|
## Overview
|
|
|
|
The `SseClientTransport` class implements the Model Context Protocol (MCP) HTTP with SSE transport specification, providing a bidirectional communication channel between clients and servers. This implementation is part of the Spring AI MCP Core library and follows the [MCP HTTP with SSE Transport Specification](https://spec.modelcontextprotocol.io/specification/basic/transports/#http-with-sse).
|
|
|
|
## Key Features
|
|
|
|
- **Bidirectional Communication**:
|
|
- Inbound: Receives messages through SSE connection
|
|
- Outbound: Sends messages via HTTP POST requests
|
|
|
|
- **Error Handling**:
|
|
- Automatic reconnection for transient failures
|
|
- Graceful shutdown capabilities
|
|
- Comprehensive error reporting
|
|
|
|
- **Message Flow**:
|
|
1. Client establishes SSE connection to `/sse` endpoint
|
|
2. Server sends 'endpoint' event with message URI
|
|
3. Client uses provided URI for outbound messages
|
|
|
|
## Technical Details
|
|
|
|
### Transport Architecture
|
|
|
|
The transport consists of two main processing pipelines:
|
|
|
|
1. **Inbound Processing**:
|
|
- Establishes SSE connection to `/sse` endpoint
|
|
- Handles two types of events:
|
|
- `message`: JSON-RPC protocol messages
|
|
- `endpoint`: Server-provided URI for outbound messages
|
|
- Implements automatic retry logic for connection failures
|
|
|
|
2. **Outbound Processing**:
|
|
- Sends messages via HTTP POST to server-provided endpoint
|
|
- Uses dedicated scheduler for sequential message processing
|
|
- Handles JSON serialization and HTTP communication
|
|
|
|
### Key Components
|
|
|
|
- **WebClient**: Handles HTTP communications for both SSE and POST requests
|
|
- **ObjectMapper**: Manages JSON serialization/deserialization
|
|
- **Scheduler**: Ensures sequential outbound message processing
|
|
- **Message Endpoint Sink**: Manages server-provided endpoint URI
|
|
|
|
## Usage Example
|
|
|
|
```java
|
|
// Create WebClient builder with base URL
|
|
WebClient.Builder webClientBuilder = WebClient.builder()
|
|
.baseUrl("http://localhost:3001");
|
|
|
|
// Initialize transport
|
|
SseClientTransport transport = new SseClientTransport(webClientBuilder);
|
|
|
|
// Create a JSON-RPC request
|
|
JSONRPCRequest request = new JSONRPCRequest(
|
|
McpSchema.JSONRPC_VERSION,
|
|
"method-name",
|
|
"request-id",
|
|
Map.of("key", "value")
|
|
);
|
|
|
|
// Send message
|
|
transport.sendMessage(request)
|
|
.subscribe(
|
|
success -> System.out.println("Message sent successfully"),
|
|
error -> System.err.println("Error sending message: " + error)
|
|
);
|
|
|
|
// Graceful shutdown when done
|
|
transport.closeGracefully()
|
|
.subscribe();
|
|
```
|
|
|
|
## Implementation Details
|
|
|
|
### Message Processing
|
|
|
|
1. **Inbound Messages**:
|
|
- Received through SSE connection
|
|
- Automatically deserialized from JSON
|
|
- Routed to appropriate handlers based on event type
|
|
|
|
2. **Outbound Messages**:
|
|
- Serialized to JSON
|
|
- Sent via HTTP POST
|
|
- Processed sequentially on dedicated thread
|
|
|
|
### Error Handling
|
|
|
|
- **Connection Failures**:
|
|
- Automatic retry for transient failures
|
|
- Configurable retry policies
|
|
- Graceful handling of permanent failures
|
|
|
|
- **Message Processing Errors**:
|
|
- Comprehensive error reporting
|
|
- Clean failure handling
|
|
- Maintains system stability
|
|
|
|
### Shutdown Process
|
|
|
|
The transport implements a graceful shutdown mechanism that:
|
|
1. Marks transport as closing
|
|
2. Disposes of all subscriptions
|
|
3. Cleans up schedulers
|
|
4. Completes message endpoint sink
|
|
|
|
## Technical Specifications
|
|
|
|
- **Protocol**: HTTP with Server-Sent Events (SSE)
|
|
- **Message Format**: JSON-RPC 2.0
|
|
- **Content Type**: application/json for outbound, text/event-stream for inbound
|
|
- **Endpoints**:
|
|
- SSE Connection: `/sse`
|
|
- Message Endpoint: Dynamically provided by server
|
|
|
|
## Dependencies
|
|
|
|
- Spring WebFlux for reactive HTTP client
|
|
- Jackson for JSON processing
|
|
- Project Reactor for reactive streams
|
|
- SLF4J for logging
|
|
|
|
## Thread Safety
|
|
|
|
The implementation is thread-safe and designed for concurrent use:
|
|
- Inbound processing uses SSE event loop
|
|
- Outbound processing uses dedicated single-threaded scheduler
|
|
- State management uses thread-safe constructs
|
|
|
|
## Testing
|
|
|
|
The implementation includes comprehensive tests covering:
|
|
- Message processing
|
|
- Error handling
|
|
- Connection management
|
|
- Shutdown procedures
|
|
- Edge cases and failure scenarios
|
|
|
|
For detailed test examples, see `SseClientTransportTests.java`.
|