abd0facf4e
- Implement MCP server with async/sync support and builder pattern configuration - Add Server stdio/SSE transport layers with robust error handling - Convert McpClient and McpServer to interfaces for better extensibility - Add sampling capabilities for LLM interactions (text/image) - Implement dynamic root management and runtime tool management - Add comprehensive prompt and resource capabilities - Add support for dynamic root management (add/remove roots at runtime) Architecture Changes - Introduce registration records for tools, resources, and prompts - Improve thread safety with concurrent collections - Enhance resource template handling - Implement builder patterns for Server/Client capabilities - Add support for server capabilities and implementation info Transport Layer: - Implement SseServerTransport with SSE endpoints - Add StdioServerTransport for process-based communication - Reorganize transport packages for better organization - Improve transport error handling and shutdown processes Documentation: - Add detailed MCP reference documentation - Include architecture diagrams and API documentation - Add comprehensive test coverage for all components - Include sample projects demonstrating stdio/SSE transports BREAKING CHANGES: Transport Package Reorganization - Move StdioClientTransport to o.s.ai.mcp.client.transport - Move SseClientTransport to o.s.ai.mcp.client.transport - Move ServerParameters to o.s.ai.mcp.client.transport - StdioClientTransport.errorHandler changed to private with setter method Migration: Use setErrorHandler() method instead of direct field access API Changes - Replace static factory methods with builder pattern - Update ServerCapabilities to use builder pattern - Make StdioClientTransport.errorHandler private with setter - Replace rootsListProvider with direct root management - Remove deprecated static factory methods Resolves #27,#25,#24,#11 Related to #12
116 lines
3.6 KiB
Markdown
116 lines
3.6 KiB
Markdown
# MCP Session Reference
|
|
|
|
## McpSession Interface
|
|
|
|
`org.springframework.ai.mcp.spec.McpSession`
|
|
|
|
The MCP (Model Context Protocol) session components implement the [MCP specification](https://spec.modelcontextprotocol.io/) for managing bidirectional JSON-RPC communication between clients and model servers.
|
|
The implementation provides a foundation for request-response patterns and notification handling, as well as managing the session lifecycle.
|
|
|
|
### Overview
|
|
|
|
The session operates asynchronously using Project Reactor's `Mono` type for non-blocking operations. It supports both request-response patterns and one-way notifications.
|
|
|
|
### Methods
|
|
|
|
#### Request-Response
|
|
|
|
```java
|
|
<T> Mono<T> sendRequest(String method, Object requestParams, TypeReference<T> typeRef)
|
|
```
|
|
|
|
Sends a request to the model server and expects a response of type T.
|
|
|
|
**Parameters:**
|
|
- `method`: The name of the method to be called on the server
|
|
- `requestParams`: The parameters to be sent with the request
|
|
- `typeRef`: The TypeReference describing the expected response type
|
|
|
|
**Returns:**
|
|
- A `Mono` that will emit the response when received
|
|
|
|
#### Notification
|
|
|
|
```java
|
|
Mono<Void> sendNotification(String method, Map<String, Object> params)
|
|
```
|
|
|
|
Sends a notification to the model server with parameters.
|
|
|
|
**Parameters:**
|
|
- `method`: The name of the notification method to be called on the server
|
|
- `params`: A map of parameters to be sent with the notification
|
|
|
|
**Returns:**
|
|
- A `Mono` that completes when the notification has been sent
|
|
|
|
#### Close Gracefully
|
|
```java
|
|
Mono<Void> closeGracefully()
|
|
```
|
|
|
|
Closes the session and releases any associated resources asynchronously.
|
|
|
|
**Returns:**
|
|
- A `Mono` that completes when the session has been closed
|
|
|
|
#### Close
|
|
```java
|
|
void close()
|
|
```
|
|
|
|
Closes the session and releases any associated resources synchronously.
|
|
|
|
### DefaultMcpSession Implementation
|
|
|
|
The `DefaultMcpSession` provides the concrete implementation of the MCP session with the following key features:
|
|
|
|
#### 1. Message Correlation
|
|
- Uses unique request IDs combining session UUID prefix and atomic counter
|
|
- Maintains thread-safe tracking of pending responses
|
|
- Implements timeout management for requests
|
|
|
|
#### 2. Handler Registration
|
|
```java
|
|
public interface RequestHandler {
|
|
Mono<Object> handle(Object params);
|
|
}
|
|
|
|
public interface NotificationHandler {
|
|
Mono<Void> handle(Object params);
|
|
}
|
|
```
|
|
|
|
|
|
### Usage Example
|
|
|
|
```java
|
|
McpSession session = // obtain session instance
|
|
|
|
// Send a request
|
|
TypeReference<ResponseType> typeRef = new TypeReference<ResponseType>() {};
|
|
Mono<ResponseType> response = session.sendRequest("method.name", requestParams, typeRef);
|
|
|
|
// Send a notification without parameters
|
|
Mono<Void> notificationResult = session.sendNotification("notification.method");
|
|
|
|
// Send a notification with parameters
|
|
Map<String, Object> params = new HashMap<>();
|
|
params.put("key", "value");
|
|
Mono<Void> paramNotificationResult = session.sendNotification("notification.method", params);
|
|
|
|
// Close the session gracefully
|
|
session.closeGracefully()
|
|
.subscribe(
|
|
null,
|
|
error -> System.err.println("Error closing session: " + error),
|
|
() -> System.out.println("Session closed successfully")
|
|
);
|
|
```
|
|
|
|
### Implementation Notes
|
|
|
|
- The interface is designed to be transport-agnostic, allowing different transport implementations (SSE, STDIO) to be used.
|
|
- All operations except `close()` are non-blocking and return `Mono` instances.
|
|
- The `sendRequest` method uses Jackson's `TypeReference` for type-safe deserialization of responses.
|
|
- The default implementation of `sendNotification(String)` delegates to `sendNotification(String, Map)` with null parameters.
|