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
124 lines
3.7 KiB
Markdown
124 lines
3.7 KiB
Markdown
# MCP Transport Reference
|
|
|
|
## McpTransport Interface
|
|
|
|
`org.springframework.ai.mcp.spec.McpTransport`
|
|
|
|
The `McpTransport` interface defines the asynchronous transport layer for the Model Context Protocol (MCP). It provides the foundation for implementing custom transport mechanisms, handling bidirectional communication between client and server components using JSON-RPC format.
|
|
|
|
### Overview
|
|
|
|
The transport layer is designed to be protocol-agnostic, allowing for various implementations such as WebSocket, HTTP, or custom protocols. It manages the lifecycle of connections and handles message exchange between components.
|
|
|
|
### Key Responsibilities
|
|
|
|
- Managing the lifecycle of the transport connection
|
|
- Handling incoming messages and errors from the server
|
|
- Sending outbound messages to the server
|
|
- Message serialization and deserialization
|
|
|
|
### Methods
|
|
|
|
#### Connect
|
|
```java
|
|
Mono<Void> connect(Function<Mono<JSONRPCMessage>, Mono<JSONRPCMessage>> handler)
|
|
```
|
|
|
|
Initializes and starts the transport connection.
|
|
|
|
**Parameters:**
|
|
- `handler`: A function that processes incoming messages and returns response messages
|
|
|
|
**Returns:**
|
|
- A `Mono<Void>` that completes when the connection is established
|
|
|
|
#### Send Message
|
|
```java
|
|
Mono<Void> sendMessage(JSONRPCMessage message)
|
|
```
|
|
|
|
Sends a message to the server asynchronously.
|
|
|
|
**Parameters:**
|
|
- `message`: The JSON-RPC message to be sent to the server
|
|
|
|
**Returns:**
|
|
- A `Mono<Void>` that completes when the message has been sent
|
|
|
|
#### Close Gracefully
|
|
```java
|
|
Mono<Void> closeGracefully()
|
|
```
|
|
|
|
Closes the transport connection and releases any associated resources asynchronously.
|
|
|
|
**Returns:**
|
|
- A `Mono<Void>` that completes when the connection has been closed
|
|
|
|
#### Close
|
|
```java
|
|
default void close()
|
|
```
|
|
|
|
Synchronously closes the transport connection. By default, this method delegates to `closeGracefully()` and subscribes to the result.
|
|
|
|
#### Unmarshal From
|
|
```java
|
|
<T> T unmarshalFrom(Object data, TypeReference<T> typeRef)
|
|
```
|
|
|
|
Deserializes data into the specified type.
|
|
|
|
**Parameters:**
|
|
- `data`: The data to deserialize
|
|
- `typeRef`: The TypeReference describing the target type
|
|
|
|
**Returns:**
|
|
- The deserialized object of type T
|
|
|
|
### Implementation Notes
|
|
|
|
- The transport layer uses Project Reactor's `Mono` type for non-blocking operations
|
|
- Messages are exchanged using the JSON-RPC format as specified by the MCP protocol
|
|
- The interface is designed to be extensible, allowing for different transport implementations
|
|
- Current implementations include:
|
|
- SSE (Server-Sent Events) Transport
|
|
- STDIO Transport (Standard Input/Output)
|
|
|
|
### Usage Example
|
|
|
|
```java
|
|
McpTransport transport = // obtain transport instance
|
|
|
|
// Connect and handle messages
|
|
transport.connect(message -> {
|
|
// Process incoming message
|
|
return processMessage(message);
|
|
}).subscribe();
|
|
|
|
// Send a message
|
|
JSONRPCMessage message = new JSONRPCMessage();
|
|
// ... configure message
|
|
transport.sendMessage(message)
|
|
.subscribe(
|
|
null,
|
|
error -> System.err.println("Error sending message: " + error),
|
|
() -> System.out.println("Message sent successfully")
|
|
);
|
|
|
|
// Close the transport
|
|
transport.closeGracefully()
|
|
.subscribe(
|
|
null,
|
|
error -> System.err.println("Error closing transport: " + error),
|
|
() -> System.out.println("Transport closed successfully")
|
|
);
|
|
```
|
|
|
|
### Transport Implementations
|
|
|
|
#### SSE Transport
|
|
The SSE (Server-Sent Events) transport implementation provides a unidirectional communication channel from the server to the client using HTTP streaming.
|
|
|
|
#### STDIO Transport
|
|
The STDIO transport implementation uses standard input/output streams for communication, making it suitable for command-line applications and process-based communication.
|