Watch

Christian Tzolov 82c64f5ad3 feat(core): add roots list support and improve documentation

- 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

2024-12-19 12:12:51 +01:00

3.1 KiB

Raw Blame History

StdioClientTransport

The StdioClientTransport class implements the MCP Stdio Transport 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:

Requests - Messages with both method and id fields:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "example.method",
    "params": {}
}

Notifications - Messages with method but no id field:

{
    "jsonrpc": "2.0",
    "method": "example.notification",
    "params": {}
}

Responses - Messages with either result or error fields:

{
    "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:

Inbound - Reads and processes messages from stdin
Outbound - Writes messages to stdout
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

// 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:

Enable DEBUG level logging to see detailed message flow
Monitor stderr for server process errors
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

3.1 KiB Raw Blame History