php-transport-implementation

PHP MCP Transport Implementation Guide

Transport Interface

All transports must implement the base Transport interface:

namespace MCP\Shared;

use React\Promise\PromiseInterface;

interface Transport {
    /**
     * Start the transport connection
     */
    public function start(): PromiseInterface;

    /**
     * Send a message through the transport
     */
    public function send(array $message): PromiseInterface;

    /**
     * Close the transport connection
     */
    public function close(): PromiseInterface;

    /**
     * Set handler for incoming messages
     */
    public function setMessageHandler(callable $handler): void;

    /**
     * Set handler for transport closure
     */
    public function setCloseHandler(callable $handler): void;

    /**
     * Set handler for transport errors
     */
    public function setErrorHandler(callable $handler): void;
}

STDIO Transport

Server STDIO Transport

namespace MCP\Server\Transport;

use MCP\Shared\Transport;
use React\EventLoop\LoopInterface;
use React\Stream\ReadableResourceStream;
use React\Stream\WritableResourceStream;
use React\Promise\Promise;
use React\Promise\PromiseInterface;

class StdioServerTransport implements Transport {
    private ReadableResourceStream $stdin;
    private WritableResourceStream $stdout;
    private LoopInterface $loop;
    private ?callable $messageHandler = null;
    private string $buffer = '';

    public function __construct(?LoopInterface $loop = null) {
        $this->loop = $loop ?? Loop::get();
    }

    public function start(): PromiseInterface {
        return new Promise(function ($resolve) {
            // Set up streams
            $this->stdin = new ReadableResourceStream(STDIN, $this->loop);
            $this->stdout = new WritableResourceStream(STDOUT, $this->loop);

            // Handle incoming data
            $this->stdin->on('data', [$this, 'handleData']);
            $this->stdin->on('close', [$this, 'handleClose']);
            $this->stdin->on('error', [$this, 'handleError']);

            $resolve();
        });
    }

    private function handleData(string $chunk): void {
        $this->buffer .= $chunk;

        // Parse messages from buffer
        while (($pos = strpos($this->buffer, "\n")) !== false) {
            $line = substr($this->buffer, 0, $pos);
            $this->buffer = substr($this->buffer, $pos + 1);

            if (trim($line) === '') {
                continue;
            }

            try {
                $message = json_decode($line, true, 512, JSON_THROW_ON_ERROR);
                if ($this->messageHandler) {
                    ($this->messageHandler)($message);
                }
            } catch (\JsonException $e) {
                $this->handleError(new \RuntimeException("Invalid JSON: " . $e->getMessage()));
            }
        }
    }

    public function send(array $message): PromiseInterface {
        return new Promise(function ($resolve, $reject) use ($message) {
            try {
                $json = json_encode($message, JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES);
                $this->stdout->write($json . "\n");
                $resolve();
            } catch (\JsonException $e) {
                $reject(new \RuntimeException("Failed to encode message: " . $e->getMessage()));
            }
        });
    }
}