Package com.tnsai.mcp.client

Class StdioTransport

java.lang.Object
com.tnsai.mcp.client.StdioTransport
All Implemented Interfaces:
McpTransport
public class StdioTransport extends Object implements McpTransport
Stdio-based MCP transport that communicates with an external process.

Features:

  • Automatic reconnection with exponential backoff
  • Connection health monitoring
  • Configurable timeouts and retry parameters
  • Process lifecycle management
  • Thread-safe message handling

Example usage: 


 StdioTransport transport = StdioTransport.builder()
     .command("npx", "-y", "@modelcontextprotocol/server-filesystem", "/path")
     .maxRetries(5)
     .initialRetryDelay(Duration.ofMillis(500))
     .maxRetryDelay(Duration.ofSeconds(30))
     .healthCheckInterval(Duration.ofSeconds(30))
     .processStartTimeout(Duration.ofSeconds(10))
     .build();

 transport.setOnMessage(message -> System.out.println("Received: " + message));
 transport.setOnError(error -> System.err.println("Error: " + error));
 transport.connect();

  • Method Details

    • builder

      public static StdioTransport.Builder builder()
      Creates a new builder for StdioTransport.
      Returns:
      a new Builder instance

    • create

      public static StdioTransport create(String... command)
      Creates a simple StdioTransport with default settings.
      Parameters:
      command - the command and arguments to execute
      Returns:
      a new StdioTransport instance

    • connect

      public void connect() throws IOException
      Description copied from interface: McpTransport
      Connects to the MCP server.
      Specified by:
      connect in interface McpTransport
      Throws:
      IOException - if connection fails

    • send

      public void send(String message) throws IOException
      Description copied from interface: McpTransport
      Sends a message to the MCP server.
      Specified by:
      send in interface McpTransport
      Parameters:
      message - the message to send (JSON-RPC request)
      Throws:
      IOException - if sending fails

    • setOnMessage

      public void setOnMessage(Consumer<String> messageConsumer)
      Description copied from interface: McpTransport
      Sets a consumer for incoming messages from the MCP server.
      Specified by:
      setOnMessage in interface McpTransport
      Parameters:
      messageConsumer - the consumer for incoming messages (JSON-RPC response/notification)

    • setOnError

      public void setOnError(Consumer<Throwable> errorConsumer)
      Description copied from interface: McpTransport
      Sets a consumer for transport errors.
      Specified by:
      setOnError in interface McpTransport
      Parameters:
      errorConsumer - the consumer for transport errors

    • setOnReconnect

      public void setOnReconnect(Runnable onReconnect)
      Sets a callback to be invoked when reconnection succeeds.
      Parameters:
      onReconnect - the callback to invoke on successful reconnection

    • setOnDisconnect

      public void setOnDisconnect(Runnable onDisconnect)
      Sets a callback to be invoked when disconnection is detected.
      Parameters:
      onDisconnect - the callback to invoke on disconnection

    • setOnCrashDetected

      public void setOnCrashDetected(Consumer<StdioTransport.DisconnectReason> onCrashDetected)
      Sets a callback for subprocess crash detection with structured reason.

      Unlike setOnDisconnect(java.lang.Runnable), this callback receives a StdioTransport.DisconnectReason with exit code and crash details.

      Parameters:
      onCrashDetected - the callback to invoke when a crash is detected

    • disconnect

      public void disconnect() throws IOException
      Description copied from interface: McpTransport
      Disconnects from the MCP server.
      Specified by:
      disconnect in interface McpTransport
      Throws:
      IOException - if disconnection fails

    • isConnected

      public boolean isConnected()
      Description copied from interface: McpTransport
      Checks if the transport is currently connected.
      Specified by:
      isConnected in interface McpTransport
      Returns:
      true if connected, false otherwise

    • getReconnectAttempts

      public int getReconnectAttempts()
      Returns the number of reconnection attempts made.
      Returns:
      the current reconnection attempt count

    • getIdleTimeMillis

      public long getIdleTimeMillis()
      Returns the time since last activity in milliseconds.
      Returns:
      milliseconds since last message was sent or received

    • getCommand

      public String[] getCommand()
      Returns the command used to start the process.
      Returns:
      a copy of the command array

    • getExitCode

      public int getExitCode()
      Returns the process exit code if available.
      Returns:
      the exit code, or -1 if the process is still running or hasn't been started