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
123 lines
3.1 KiB
Markdown
123 lines
3.1 KiB
Markdown
# StdioClientTransport
|
|
|
|
The `StdioClientTransport` class implements the [MCP Stdio Transport](https://spec.modelcontextprotocol.io/specification/basic/transports/#stdio) specification, providing communication with MCP servers over standard input/output streams.
|
|
|
|
## Overview
|
|
|
|
The Stdio transport uses standard input/output streams for bidirectional communication between the client and server:
|
|
- Messages are sent to the server via stdout
|
|
- Messages are received from the server via stdin
|
|
- Error and debug information is sent via stderr
|
|
|
|
## Message Format
|
|
|
|
Messages are exchanged as newline-delimited JSON-RPC messages:
|
|
- Each message is a single line of JSON text
|
|
- Messages are terminated with a newline character (`\n`)
|
|
- Messages follow the JSON-RPC 2.0 specification
|
|
- UTF-8 encoding is used for all messages
|
|
|
|
### Message Types
|
|
|
|
The transport handles three types of JSON-RPC messages:
|
|
|
|
1. **Requests** - Messages with both `method` and `id` fields:
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": 1,
|
|
"method": "example.method",
|
|
"params": {}
|
|
}
|
|
```
|
|
|
|
2. **Notifications** - Messages with `method` but no `id` field:
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "example.notification",
|
|
"params": {}
|
|
}
|
|
```
|
|
|
|
3. **Responses** - Messages with either `result` or `error` fields:
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": 1,
|
|
"result": {}
|
|
}
|
|
```
|
|
|
|
## Implementation Details
|
|
|
|
### Process Management
|
|
|
|
The transport manages a server process with:
|
|
- Command and arguments specified via `ServerParameters`
|
|
- Environment variables for configuration
|
|
- Proper process cleanup on shutdown
|
|
|
|
### Threading Model
|
|
|
|
The implementation uses three dedicated threads:
|
|
1. **Inbound** - Reads and processes messages from stdin
|
|
2. **Outbound** - Writes messages to stdout
|
|
3. **Error** - Handles stderr messages
|
|
|
|
### Error Handling
|
|
|
|
Errors are handled at multiple levels:
|
|
- Process startup failures
|
|
- Stream I/O errors
|
|
- Message parsing errors
|
|
- Process termination handling
|
|
|
|
## Usage Example
|
|
|
|
```java
|
|
// Create server parameters
|
|
ServerParameters params = ServerParameters.builder()
|
|
.command("path/to/server")
|
|
.args(List.of("--arg1", "value1"))
|
|
.env(Map.of("ENV_VAR", "value"))
|
|
.build();
|
|
|
|
// Create transport
|
|
StdioClientTransport transport = new StdioClientTransport(params);
|
|
|
|
// Start transport
|
|
transport.start();
|
|
|
|
// Send message
|
|
JSONRPCRequest request = new JSONRPCRequest();
|
|
request.setId(1);
|
|
request.setMethod("example.method");
|
|
request.setParams(new HashMap<>());
|
|
transport.send(request);
|
|
|
|
// Close transport
|
|
transport.closeGracefully().block();
|
|
```
|
|
|
|
## Error Messages
|
|
|
|
Error messages from the server process are:
|
|
- Written to stderr
|
|
- Logged at ERROR level
|
|
- Emitted through the error sink for handling
|
|
- UTF-8 encoded
|
|
|
|
## Debugging
|
|
|
|
For debugging purposes:
|
|
1. Enable DEBUG level logging to see detailed message flow
|
|
2. Monitor stderr for server process errors
|
|
3. Check process exit codes for abnormal termination
|
|
|
|
## Implementation Notes
|
|
|
|
- The transport ensures thread safety through dedicated schedulers
|
|
- Messages are processed asynchronously using Project Reactor
|
|
- Resources are properly cleaned up on shutdown
|
|
- The implementation is resilient to various failure modes
|