StdioTransport extends BaseTransport
Client transport that spawns a child process and communicates via stdio.
This transport handles all blocking operations:
- Spawning the server process
- Reading from stdout in a polling loop
- Writing to stdin
- Managing Fibers waiting for responses
Tags
Table of Contents
Constants
- DEFAULT_MAX_BUFFER_SIZE : mixed = 4 * 1024 * 1024
- Default cap on the bytes buffered while waiting for a complete line.
- MAX_STDERR_BUFFER_SIZE : mixed = 8 * 1024
- Bytes of the most recent stderr kept to explain why the server stopped.
- EXIT_GRACE_SECONDS : mixed = 0.1
- How long a server that closed its output is given to exit, so its exit code can be reported.
- MAX_STDERR_READ : mixed = 64 * 1024
- Bytes of stderr read in one go at most: a pipe's usual capacity, so what an exited server left behind is read whole.
Properties
- $closeCallback : callable(string): void|null
- $errorCallback : callable(Throwable): void|null
- $initializeCallback : callable(): mixed|null
- $logger : LoggerInterface
- $messageCallback : callable(string): void|null
- $state : ClientStateInterface|null
- $activeFiber : McpFiber|null
- $activeSuspend : FiberSuspend|null
- $args : array<string|int, mixed>
- $command : string
- $cwd : string|null
- $env : array<string|int, mixed>|null
- $exitReason : string|null
- Why the server's output ended, kept because every later tick sees the end of output again and would wait out the exit grace each time, and because before PHP 8.3 proc_get_status() reports the exit code only on its first call after the exit.
- $inputBuffer : string
- $maxBufferSize : int
- $process : resource|null
- $stderr : resource|null
- $stderrBuffer : string
- $stdin : resource|null
- $stdout : resource|null
Methods
- __construct() : mixed
- close() : void
- Close the transport and clean up resources.
- connect() : void
- Connect to the MCP server and perform initialization handshake.
- onClose() : void
- Register callback for when connection closes.
- onError() : void
- Register callback for transport errors.
- onInitialize() : void
- Register callback for initialization handshake.
- onMessage() : void
- Register callback for incoming messages from server.
- runRequest() : Response<string|int, array<string, mixed>>|Error
- Run a request fiber to completion.
- send() : void
- Send a message to the server immediately.
- setState() : void
- Set the client state for runtime state management.
- handleClose() : void
- Handle connection close.
- handleError() : void
- Handle a transport error.
- handleInitialize() : mixed
- Perform initialization via the registered callback.
- handleMessage() : void
- Handle an incoming message from the server.
- abortInput() : void
- Discard the input buffer and fail any in-flight request.
- awaitExit() : string|null
- Give a server that closed its output a moment to exit, which it usually does next.
- exitReason() : string
- Why the server's output ended: how the process exited, if it did, and the end of its stderr.
- failPending() : void
- hasInput() : bool
- processFiber() : void
- processInput() : void
- processStderr() : void
- Read what the server wrote to stderr, keeping its tail to explain a later failure.
- spawnProcess() : void
- tick() : void
Constants
DEFAULT_MAX_BUFFER_SIZE
Default cap on the bytes buffered while waiting for a complete line.
public
mixed
DEFAULT_MAX_BUFFER_SIZE
= 4 * 1024 * 1024
MAX_STDERR_BUFFER_SIZE
Bytes of the most recent stderr kept to explain why the server stopped.
public
mixed
MAX_STDERR_BUFFER_SIZE
= 8 * 1024
EXIT_GRACE_SECONDS
How long a server that closed its output is given to exit, so its exit code can be reported.
private
mixed
EXIT_GRACE_SECONDS
= 0.1
MAX_STDERR_READ
Bytes of stderr read in one go at most: a pipe's usual capacity, so what an exited server left behind is read whole.
private
mixed
MAX_STDERR_READ
= 64 * 1024
Properties
$closeCallback
protected
callable(string): void|null
$closeCallback
$errorCallback
protected
callable(Throwable): void|null
$errorCallback
$initializeCallback
protected
callable(): mixed|null
$initializeCallback
$logger
protected
LoggerInterface
$logger
$messageCallback
protected
callable(string): void|null
$messageCallback
$state
protected
ClientStateInterface|null
$state
= null
$activeFiber
private
McpFiber|null
$activeFiber
= null
$activeSuspend
private
FiberSuspend|null
$activeSuspend
= null
$args read-only
private
array<string|int, mixed>
$args
= []
$command read-only
private
string
$command
$cwd read-only
private
string|null
$cwd
= null
$env read-only
private
array<string|int, mixed>|null
$env
= null
$exitReason
Why the server's output ended, kept because every later tick sees the end of output again and would wait out the exit grace each time, and because before PHP 8.3 proc_get_status() reports the exit code only on its first call after the exit.
private
string|null
$exitReason
= null
$inputBuffer
private
string
$inputBuffer
= ''
$maxBufferSize read-only
private
int
$maxBufferSize
= self::DEFAULT_MAX_BUFFER_SIZE
$process
private
resource|null
$process
$stderr
private
resource|null
$stderr
$stderrBuffer
private
string
$stderrBuffer
= ''
$stdin
private
resource|null
$stdin
$stdout
private
resource|null
$stdout
Methods
__construct()
public
__construct(string $command[, array<int, string> $args = [] ][, string|null $cwd = null ][, array<string, string>|null $env = null ][, LoggerInterface|null $logger = null ][, int $maxBufferSize = self::DEFAULT_MAX_BUFFER_SIZE ]) : mixed
Parameters
- $command : string
-
The command to run
- $args : array<int, string> = []
-
Command arguments
- $cwd : string|null = null
-
Working directory
- $env : array<string, string>|null = null
-
Environment variables
- $logger : LoggerInterface|null = null
- $maxBufferSize : int = self::DEFAULT_MAX_BUFFER_SIZE
-
Maximum bytes buffered while waiting for a complete line. The buffer is only drained on a "\n"; a spawned server that streams stdout without ever emitting a newline would otherwise grow it without bound and exhaust client memory. Reaching the cap aborts the read instead. Raise it for servers that emit single frames larger than the default.
close()
Close the transport and clean up resources.
public
close() : void
connect()
Connect to the MCP server and perform initialization handshake.
public
connect() : void
This method blocks until:
- Initialization completes successfully
- Connection fails (throws ConnectionException)
onClose()
Register callback for when connection closes.
public
onClose(callable $listener) : void
Parameters
- $listener : callable
onError()
Register callback for transport errors.
public
onError(callable $listener) : void
Parameters
- $listener : callable
onInitialize()
Register callback for initialization handshake.
public
onInitialize(callable $listener) : void
The callback should return a Fiber that performs the initialization.
Parameters
- $listener : callable
onMessage()
Register callback for incoming messages from server.
public
onMessage(callable $listener) : void
Parameters
- $listener : callable
runRequest()
Run a request fiber to completion.
public
runRequest(McpFiber $fiber[, callable(float $progress, Array $total, Array $message): void|null $onProgress = null ]) : Response<string|int, array<string, mixed>>|Error
Parameters
- $fiber : McpFiber
- $onProgress : callable(float $progress, Array $total, Array $message): void|null = null
Return values
Response<string|int, array<string, mixed>>|Error —The response or error
send()
Send a message to the server immediately.
public
send(string $data) : void
Parameters
- $data : string
-
JSON-encoded message
setState()
Set the client state for runtime state management.
public
setState(ClientStateInterface $state) : void
Parameters
- $state : ClientStateInterface
handleClose()
Handle connection close.
protected
handleClose(string $reason) : void
Parameters
- $reason : string
handleError()
Handle a transport error.
protected
handleError(Throwable $error) : void
Parameters
- $error : Throwable
handleInitialize()
Perform initialization via the registered callback.
protected
handleInitialize() : mixed
Tags
Return values
mixed —The result from the initialization callback
handleMessage()
Handle an incoming message from the server.
protected
handleMessage(string $message) : void
Parameters
- $message : string
abortInput()
Discard the input buffer and fail any in-flight request.
private
abortInput(string $reason) : void
The waiting fiber is resolved with an error immediately so the caller fails fast, rather than spinning until the request timeout elapses.
Parameters
- $reason : string
awaitExit()
Give a server that closed its output a moment to exit, which it usually does next.
private
awaitExit() : string|null
Return values
string|null —how the process ended, or null if it is still running
exitReason()
Why the server's output ended: how the process exited, if it did, and the end of its stderr.
private
exitReason() : string
Return values
stringfailPending()
private
failPending(string $reason[, array<string, mixed>|null $data = null ]) : void
Parameters
- $reason : string
- $data : array<string, mixed>|null = null
hasInput()
private
hasInput(resource $stream) : bool
Parameters
- $stream : resource
Return values
boolprocessFiber()
private
processFiber() : void
processInput()
private
processInput() : void
processStderr()
Read what the server wrote to stderr, keeping its tail to explain a later failure.
private
processStderr() : void
spawnProcess()
private
spawnProcess() : void
tick()
private
tick() : void