MCP PHP SDK

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
phpstan-import-type

McpFiber from TransportInterface

FiberSuspend from TransportInterface

author

Kyrian Obikwelu koshnawaza@gmail.com

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

$messageCallback

protected callable(string): void|null $messageCallback

$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

$maxBufferSize read-only

private int $maxBufferSize = self::DEFAULT_MAX_BUFFER_SIZE

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

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
throws
RuntimeException

If no initialize listener is registered

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
string

failPending()

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
bool

processStderr()

Read what the server wrote to stderr, keeping its tail to explain a later failure.

private processStderr() : void
On this page

Search results