PHP MCP Server

https://github.com/php-mcp/server
Admin
PHP MCP Server is a comprehensive PHP SDK for building Model Context Protocol (MCP) servers,...
Tokens:122,564
Snippets:887
Trust Score:5.6
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Basic Server Configuration

Source: https://github.com/php-mcp/server/blob/main/README.md

Creates a basic MCP server with server info, capabilities, and pagination limit. Use this as a starting point for simple setups.

```php
use PhpMcp\Server\Server;
use PhpMcp\Schema\ServerCapabilities;

$server = Server::make()
    ->withServerInfo('My App Server', '2.1.0')
    ->withCapabilities(ServerCapabilities::make(
        resources: true,
        resourcesSubscribe: true,
        prompts: true,
        tools: true
    ))
    ->withPaginationLimit(100)
    ->build();
```

--------------------------------

### Run an Example Server

Source: https://github.com/php-mcp/server/blob/main/README.md

Commands to navigate to an example directory, make the server executable, and run it. Configure the server in your MCP client if needed.

```bash
# Navigate to an example directory
cd examples/01-discovery-stdio-calculator/

# Make the server executable
chmod +x server.php

# Run the server (or configure it in your MCP client)
./server.php
```

--------------------------------

### Install application and Supervisor on VPS

Source: https://github.com/php-mcp/server/blob/main/README.md

Commands to clone the MCP server repository, install Composer dependencies, install Supervisor, and create the Supervisor configuration file. Run these steps on a VPS before configuring Supervisor.

```bash
# 1. Install your application on VPS
git clone https://github.com/yourorg/your-mcp-server.git /var/www/mcp-server
cd /var/www/mcp-server
composer install --no-dev --optimize-autoloader

# 2. Install Supervisor
sudo apt-get install supervisor

# 3. Create Supervisor configuration
sudo nano /etc/supervisor/conf.d/mcp-server.conf
```

--------------------------------

### BasicContainer usage example

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/defaults.md

Shows how to use BasicContainer: create an instance, set a pre-built singleton binding for an interface, and get a service that is auto-wired with the interface.

```php
use PhpMcp\Server\Defaults\BasicContainer;

$container = new BasicContainer();
$container->set(DatabaseInterface::class, new MySqlDatabase($dsn));

$service = $container->get(MyHandler::class); // auto-wired with DatabaseInterface
```

--------------------------------

### Install dependencies

Source: https://github.com/php-mcp/server/blob/main/CONTRIBUTING.md

Install runtime and development dependencies using Composer.

```bash
composer install
```

--------------------------------

### Start Supervisor and Nginx services

Source: https://github.com/php-mcp/server/blob/main/README.md

Commands to enable and start Supervisor and Nginx, and check the status of the MCP server process.

```bash
# Enable and start supervisor
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start mcp-server:*

# Enable and start nginx
sudo systemctl enable nginx
sudo systemctl restart nginx

# Check status
sudo supervisorctl status
```

--------------------------------

### Server::make() usage example

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/server.md

Example of using Server::make() to build a server. Note that withServerInfo() is still required.

```php
use PhpMcp\Server\Server;

$server = Server::make()->build(); // still needs withServerInfo()
```

--------------------------------

### Install development dependencies

Source: https://github.com/php-mcp/server/blob/main/README.md

Run composer install with the --dev flag to install development dependencies required for testing and code style checks.

```bash
composer install --dev
```

--------------------------------

### Streamable HTTP Transport Server Setup (Recommended)

Source: https://github.com/php-mcp/server/blob/main/README.md

Sets up an MCP server using the recommended StreamableHttpServerTransport for production. Requires a cache for resumability, and the host must not be 0.0.0.0.

```php
use PhpMcp\Server\Transports\StreamableHttpServerTransport;

$server = Server::make()
    ->withServerInfo('Streamable Server', '1.0.0')
    ->withLogger($logger)
    ->withCache($cache)     // Required for resumability
    ->build();

$server->discover(__DIR__, ['src']);

// Create streamable transport with resumability
$transport = new StreamableHttpServerTransport(
    host: '127.0.0.1',      // MCP protocol prohibits 0.0.0.0
    port: 8080,
    mcpPathPrefix: 'mcp',
    enableJsonResponse: false,  // Use SSE streaming (default)
    stateless: false            // Enable stateless mode for session-less clients
);

$server->listen($transport);
```

--------------------------------

### SSL/TLS setup with Certbot

Source: https://github.com/php-mcp/server/blob/main/README.md

Commands to install Certbot and generate an SSL certificate for the MCP server domain using Nginx.

```bash
# Install Certbot for Let's Encrypt
sudo apt install certbot python3-certbot-nginx

# Generate SSL certificate
sudo certbot --nginx -d mcp.yourdomain.com
```

--------------------------------

### listen() framework integration example

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/server.md

Shows how to integrate with a framework by not running the loop and binding manually. Discovery should be run first, then listen with runLoop: false and manage the loop yourself.

```php
// Framework integration: do not run the loop, bind manually
$protocol = $server->getProtocol();           // e.g. React\Http\HttpServer handler
$server->discover(__DIR__, ['src']);          // discovery first
// $server->listen($transport, runLoop: false) then run your own loop
```

--------------------------------

### discover() usage example

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/server.md

Shows how to build a server with server info and call discover with a base path, scan directory, and force flag. Discovery skips if already run unless force is true.

```php
$server = Server::make()->withServerInfo('Calc', '1.0.0')->build();
$server->discover(basePath: __DIR__, scanDirs: ['src/Handlers'], force: true);
```

--------------------------------

### Install php-mcp/server via Composer

Source: https://github.com/php-mcp/server/blob/main/README.md

Install the php-mcp/server package using Composer. Requires PHP >= 8.1 and extensions json, mbstring, pcre.

```bash
composer require php-mcp/server
```

--------------------------------

### Session manager usage example

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/session.md

Shows how to create a session manager with an array handler, create a session, set data, save it, listen for session deletion, and use SubscriptionManager to subscribe and get subscribers.

```php
use PhpMcp\Server\Defaults\SystemClock;
use PhpMcp\Server\Session\{ArraySessionHandler, Session, SessionManager, SubscriptionManager};

$handler = new ArraySessionHandler(ttl: 3600, clock: new SystemClock());
$manager = new SessionManager($handler, $logger, ttl: 3600, gcInterval: 300);
$manager->startGcTimer();

$session = $manager->createSession('abc123');
$session->set('client_info.name', 'cursor');
$session->save();

$manager->on('session_deleted', function (string $id) {
    // cleanup dependent state
});

$subs = new SubscriptionManager($logger);
$subs->subscribe('abc123', 'file://config.json');
$subscribers = $subs->getSubscribers('file://config.json'); // ['abc123']
```

--------------------------------

### Production Dockerfile for MCP server

Source: https://github.com/php-mcp/server/blob/main/README.md

Dockerfile based on php:8.3-fpm-alpine that installs Nginx, Supervisor, and PHP extensions, copies application code and configuration files, installs Composer dependencies, and starts Supervisor.

```dockerfile
FROM php:8.3-fpm-alpine

# Install system dependencies
RUN apk --no-cache add \
    nginx \
    supervisor \
    && docker-php-ext-enable opcache

# Install PHP extensions for MCP
RUN docker-php-ext-install pdo_mysql pdo_sqlite opcache

# Create application directory
WORKDIR /var/www/mcp

# Copy application code
COPY . /var/www/mcp
COPY docker/nginx.conf /etc/nginx/nginx.conf
COPY docker/supervisord.conf /etc/supervisord.conf
COPY docker/php.ini /usr/local/etc/php/conf.d/production.ini

# Install Composer dependencies
RUN composer install --no-dev --optimize-autoloader --no-interaction

# Set permissions
RUN chown -R www-data:www-data /var/www/mcp

# Expose port
EXPOSE 80

# Start supervisor
CMD ["/usr/bin/supervisord", "-c", "/etc/supervisord.conf"]
```

--------------------------------

### Server builder usage example

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/server-builder.md

Shows how to configure and build a Server using Server::make() with server info, session, container, tool, resource, and prompt registrations. Requires a BasicContainer with a PDO instance and the OrderHandler class. The build() call returns the fully wired Server.

```php
use PhpMcp\Server\Server;
use PhpMcp\Server\Defaults\BasicContainer;

$basicContainer = new BasicContainer();
$basicContainer->set(\PDO::class, new \PDO('sqlite::memory:'));

$server = Server::make()
    ->withServerInfo('Dev Server', '0.1.0')
    ->withSession('array', 1800)
    ->withContainer($basicContainer)
    ->withTool(
        [OrderHandler::class, 'ship'],
        name: 'ship_order',
        description: 'Ship an order'
    )
    ->withResource(
        function (): array { return ['health' => 'ok']; },
        uri: 'config://runtime/status',
        mimeType: 'application/json'
    )
    ->withPrompt(
        function (string $topic): array {
            return [['role' => 'user', 'content' => "Write about $topic"]];
        },
        name: 'writing_prompt'
    )
    ->build();
```

--------------------------------

### listen()

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/transports-http-sse.md

Starts the HTTP server by creating a React socket server and HTTP server. Emits a 'ready' event after the socket is bound.

```APIDOC
## listen()

### Description
Creates a `React\Socket\SocketServer` + `React\Http\HttpServer` whose handler chain is `middlewares + createRequestHandler()`. Emits `ready` after the socket is bound.

### Signature
```php
public function listen(): void
```

### Throws
- `TransportException` when already listening, closing/closed, or socket binding fails.
```

--------------------------------

### Usage example for HttpServerTransport

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/transports-http-sse.md

Shows how to create a server with HttpServerTransport, including middleware and server discovery.

```php
use PhpMcp\Server\Server;
use PhpMcp\Server\Transports\HttpServerTransport;

$server = Server::make()
    ->withServerInfo('HTTP Server', '1.0.0')
    ->withLogger($logger)
    ->build();
$server->discover(__DIR__, ['src']);

$transport = new HttpServerTransport(
    host: '127.0.0.1',
    port: 8080,
    mcpPathPrefix: 'mcp',
    middlewares: [$authMiddleware],
);
$server->listen($transport);
```

--------------------------------

### Registry usage example

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/registry.md

Shows how to instantiate the registry, register a tool with a handler, listen for list changes, retrieve tools, and persist or clear discovered elements. The `on('list_changed')` callback is notified on subsequent changes to the 'tools' list.

```php
use PhpMcp\Server\Registry;
use PhpMcp\Schema\Tool;

$registry = new Registry($logger, $cache);
$registry->registerTool(
    Tool::make('add', ['type' => 'object', 'properties' => [], 'required' => []]),
    function (int $a, int $b): int { return $a + $b; },
    isManual: true
);

$registry->on('list_changed', function (string $listType) {
    // notified on subsequent changes to 'tools'
});

$tool = $registry->getTool('add');           // ?RegisteredTool
$allTools = $registry->getTools();          // array<string, Tool> schemas
$saved = $registry->save();                 // persist discovered elements to cache
$registry->clear();                          // drop discovered elements
```

--------------------------------

### listen() method

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/transports-http-sse.md

Starts the HTTP server. Throws TransportException if already listening, closing/closed, or socket binding fails.

```php
public function listen(): void
```

--------------------------------

### Attribute-Based Discovery Example

Source: https://github.com/php-mcp/server/blob/main/README.md

Defines MCP elements (tool, resource, resource template, prompt) using PHP 8 attributes on a class. The server discovers these via filesystem scanning.

```php
use PhpMcp\Server\Attributes\{McpTool, McpResource, McpResourceTemplate, McpPrompt};

class UserManager
{
    /**
     * Creates a new user account.
     */
    #[McpTool(name: 'create_user')]
    public function createUser(string $email, string $password, string $role = 'user'): array
    {
        // Create user logic
        return ['id' => 123, 'email' => $email, 'role' => $role];
    }

    /**
     * Get user configuration.
     */
    #[McpResource(
        uri: 'config://user/settings',
        mimeType: 'application/json'
    )]
    public function getUserConfig(): array
    {
        return ['theme' => 'dark', 'notifications' => true];
    }

    /**
     * Get user profile by ID.
     */
    #[McpResourceTemplate(
        uriTemplate: 'user://{userId}/profile',
        mimeType: 'application/json'
    )]
    public function getUserProfile(string $userId): array
    {
        return ['id' => $userId, 'name' => 'John Doe'];
    }

    /**
     * Generate welcome message prompt.
     */
    #[McpPrompt(name: 'welcome_user')]
    public function welcomeUserPrompt(string $username, string $role): array
    {
        return [
            ['role' => 'user', 'content' => "Create a welcome message for {$username} with role {$role}"]
        ];
    }
}
```

--------------------------------

### Usage example with McpPrompt and CompletionProvider

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/attributes.md

Shows how to apply CompletionProvider to prompt method parameters using static values or an enum class. Note the source caveat: for discovered elements, use provider with a class-string instead of providerClass.

```php
use PhpMcp\Server\Attributes\{McpPrompt, CompletionProvider};
use PhpMcp\Server\Defaults\EnumCompletionProvider;

enum Priority: string { case LOW = 'low'; case HIGH = 'high'; }

#[McpPrompt(name: 'task_prompt')]
public function generate(
    #[CompletionProvider(values: ['blog', 'article', 'guide'])]
    string $contentType,
    #[CompletionProvider(enum: Priority::class)]
    string $priority,
): array {
    return [['role' => 'user', 'content' => "Create a {$priority} {$contentType}"]];
}
```

--------------------------------

### HTTP + SSE Transport Server Setup (Deprecated)

Source: https://github.com/php-mcp/server/blob/main/README.md

Sets up an MCP server using the deprecated HttpServerTransport for legacy applications. The host must not be 0.0.0.0 per MCP protocol, and a logger is recommended.

```php
use PhpMcp\Server\Transports\HttpServerTransport;

$server = Server::make()
    ->withServerInfo('HTTP Server', '1.0.0')
    ->withLogger($logger)  // Recommended for HTTP
    ->build();

$server->discover(__DIR__, ['src']);

// Create HTTP transport
$transport = new HttpServerTransport(
    host: '127.0.0.1',      // MCP protocol prohibits 0.0.0.0
    port: 8080,             // Port number
    mcpPathPrefix: 'mcp'    // URL prefix (/mcp/sse, /mcp/message)
);

$server->listen($transport);
```

--------------------------------

### EnumCompletionProvider usage example

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/defaults.md

Shows how to instantiate EnumCompletionProvider with a backed string enum and call getCompletions. Backed string enums contribute their backing value; other cases contribute case name. Prefix filtering works as in ListCompletionProvider.

```php
use PhpMcp\Server\Defaults\EnumCompletionProvider;

enum Tier: string { case BASIC = 'basic'; case PRO = 'pro'; }

$provider = new EnumCompletionProvider(Tier::class);
$completions = $provider->getCompletions('b', $session); // ['basic']
```

--------------------------------

### get() method signature

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/elements.md

Invokes the handler and formats the raw result into PromptMessage[] for GetPromptResult. The description comes from the prompt schema.

```php
public function get(ContainerInterface $container, array $arguments, Context $context): array
```

--------------------------------

### Complete server setup with StreamableHttpServerTransport

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/server.md

Initializes a PHP MCP server with server info and session, discovers elements from the 'src/Elements' directory, and listens on 127.0.0.1:8080 using the streamable HTTP transport. Requires Composer autoload and the PhpMcp\Server package.

```php
<?php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';

use PhpMcp\Server\Server;
use PhpMcp\Server\Transports\StreamableHttpServerTransport;

$server = Server::make()
    ->withServerInfo('Order Service', '2.1.0')
    ->withSession('cache', 7200)
    ->build();

$server->discover(basePath: __DIR__, scanDirs: ['src/Elements']);

$transport = new StreamableHttpServerTransport('127.0.0.1', 8080);
$server->listen($transport);
```

--------------------------------

### Stdio Transport Server Setup

Source: https://github.com/php-mcp/server/blob/main/README.md

Sets up an MCP server using the StdioServerTransport, which uses STDIN/STDOUT for JSON-RPC communication. This is a blocking call, and you must never write to STDOUT in handlers; use STDERR for debugging.

```php
use PhpMcp\Server\Transports\StdioServerTransport;

$server = Server::make()
    ->withServerInfo('Stdio Server', '1.0.0')
    ->build();

$server->discover(__DIR__, ['src']);

// Create stdio transport (uses STDIN/STDOUT by default)
$transport = new StdioServerTransport();

// Start listening (blocking call)
$server->listen($transport);
```

--------------------------------

### McpPrompt usage example

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/attributes.md

Shows how to apply the McpPrompt attribute to a method. The name is set to 'writing_prompt' and the method accepts a topic and an optional tone parameter. The method returns an array with a user message containing the topic and tone.

```php
use PhpMcp\Server\Attributes\McpPrompt;

#[McpPrompt(name: 'writing_prompt')]
public function write(string $topic, string $tone = 'professional'): array
{
    return [['role' => 'user', 'content' => "Write about {$topic} in a {$tone} tone"]];
}
```

--------------------------------

### Pre-configured completion provider instances

Source: https://github.com/php-mcp/server/blob/main/README.md

Shows passing pre-configured provider instances to #[CompletionProvider] for prompt arguments, including a new instance and one from a property.

```php
class DocumentService  
{
    #[McpPrompt(name: 'document_prompt')]
    public function generatePrompt(
        #[CompletionProvider(provider: new UserIdCompletionProvider($database))]  // Pre-configured instance
        string $userId,
        
        #[CompletionProvider(provider: $this->categoryProvider)]  // Instance from property
        string $category
    ): array {
        return [['role' => 'user', 'content' => "Generate document for user {$userId} in {$category}"]];
    }
}
```

--------------------------------

### McpResource usage example

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/attributes.md

Example of using the McpResource attribute on a method. The attribute specifies a URI and MIME type; the method returns an array.

```php
use PhpMcp\Server\Attributes\McpResource;

#[McpResource(uri: 'config://user/settings', mimeType: 'application/json')]
public function getSettings(): array
{
    return ['theme' => 'dark'];
}
```

--------------------------------

### Run the test suite

Source: https://github.com/php-mcp/server/blob/main/README.md

Execute the test suite using the composer test command.

```bash
composer test
```

--------------------------------

### listen()

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/transports-streamable-http.md

Starts listening for incoming connections and requests. Throws a TransportException if the transport is already listening, closing/closed, or if binding fails, and emits a 'ready' event upon successful start.

```APIDOC
## listen()

### Description
Starts listening for incoming connections and requests. Throws a TransportException if the transport is already listening, closing/closed, or if binding fails, and emits a 'ready' event upon successful start.

### Method
listen

### Signature
```php
public function listen(): void
```

### Throws
- **TransportException** - When already listening, closing/closed, or binding fails.

### Events
- **ready** - Emitted when the transport is ready to accept connections.
```

--------------------------------

### McpTool usage example

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/attributes.md

Example of using the McpTool attribute on a method. The attribute specifies a custom name and description; the method's DocBlock summary is used as default description if not provided.

```php
use PhpMcp\Server\Attributes\McpTool;

class MathService
{
    /** Adds two numbers. */
    #[McpTool(name: 'add_numbers', description: 'Add two numbers')]
    public function add(int $a, int $b): int
    {
        return $a + $b;
    }
}
```

--------------------------------

### Manual Registration with Completion Providers

Source: https://github.com/php-mcp/server/blob/main/README.md

Shows how to register prompts with completion providers using a provider class and a closure with inline attributes. Completion providers are auto-discovered from method attributes for class-based handlers. Users can still input any value, so validate parameters in handlers.

```php
$server = Server::make()
    ->withServerInfo('Completion Demo', '1.0.0')
    
    // Using provider class (resolved from container)
    ->withPrompt(
        [DocumentHandler::class, 'generateReport'],
        name: 'document_report'
        // Completion providers are auto-discovered from method attributes
    )
    
    // Using closure with inline completion providers
    ->withPrompt(
        function(
            #[CompletionProvider(values: ['json', 'xml', 'csv', 'yaml'])]
            string $format,
            
            #[CompletionProvider(enum: Priority::class)]
            string $priority
        ): array {
            return [['role' => 'user', 'content' => "Export data in {$format} format with {$priority} priority"]];
        },
        name: 'export_data'
    )
    
    ->build();
```

--------------------------------

### Discovery Process Configuration

Source: https://github.com/php-mcp/server/blob/main/README.md

Builds a server and then discovers MCP elements from specified directories, with options to exclude directories and cache results. Use after defining attribute-based elements.

```php
// Build server first
$server = Server::make()
    ->withServerInfo('My App Server', '1.0.0')
    ->build();

// Then discover elements
$server->discover(
    basePath: __DIR__,
    scanDirs: ['src/Handlers', 'src/Services'],  // Directories to scan
    excludeDirs: ['src/Tests'],                  // Directories to skip
    saveToCache: true                            // Cache results (default: true)
);
```

--------------------------------

### BasicContainer public methods

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/defaults.md

Defines the public API of BasicContainer: get, has, and set. get returns cached instances or auto-wires via reflection; has checks if an instance is set or the class/interface exists; set registers a pre-built singleton binding.

```php
public function get(string $id): mixed
public function has(string $id): bool
public function set(string $id, object $instance): void
```

--------------------------------

### Run tests with coverage

Source: https://github.com/php-mcp/server/blob/main/README.md

Run tests with coverage using composer test:coverage. Requires Xdebug to be installed and enabled.

```bash
composer test:coverage
```

--------------------------------

### Create Server Script (mcp-server.php)

Source: https://github.com/php-mcp/server/blob/main/README.md

Create mcp-server.php to build the server, discover MCP elements from src, and listen via stdio transport. On error, writes a critical error to STDERR and exits with code 1.

```php
#!/usr/bin/env php
<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use PhpMcp\Server\Server;
use PhpMcp\Server\Transports\StdioServerTransport;

try {
    // Build server configuration
    $server = Server::make()
        ->withServerInfo('PHP Calculator Server', '1.0.0') 
        ->build();

    // Discover MCP elements via attributes
    $server->discover(
        basePath: __DIR__,
        scanDirs: ['src']
    );

    // Start listening via stdio transport
    $transport = new StdioServerTransport();
    $server->listen($transport);

} catch (\Throwable $e) {
    fwrite(STDERR, "[CRITICAL ERROR] " . $e->getMessage() . "\n");
    exit(1);
}
```

--------------------------------

### ServerTransportInterface

Source: https://github.com/php-mcp/server/blob/main/_autodocs/types.md

Contract for server transports. Defines methods to start listening, send messages, and close the transport.

```APIDOC
## ServerTransportInterface

### Description
Contract for server transports. Defines methods to start listening, send messages, and close the transport.

### Methods

#### listen()
- **Return Type**: `void`
- **Description**: Starts the listener (does not run the loop). Throws `TransportException` on setup failure.

#### sendMessage(Message $message, string $sessionId, array $context = [])
- **Parameters**:
  - `$message` (Message) - Required - The JSON-RPC message to send.
  - `$sessionId` (string) - Required - The session identifier.
  - `$context` (array) - Optional - Additional context.
- **Return Type**: `PromiseInterface<void>`
- **Description**: Queues/sends a JSON-RPC message; rejects on send errors.

#### close()
- **Return Type**: `void`
- **Description**: Graceful shutdown; must emit `'close'`.

### Events Emitted
- `'ready'` (optional, `()`)
- `'client_connected'` (`string $sessionId`)
- `'message'` (`Message $message, string $sessionId, array $context`)
- `'client_disconnected'` (`string $sessionId, ?string $reason`)
- `'error'` (`Throwable $error, ?string $sessionId`)
- `'close'` (`?string $reason`)

### Implementations
- `StdioServerTransport`
- `HttpServerTransport`
- `StreamableHttpServerTransport`
```

--------------------------------

### Client configuration JSON

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/transports-http-sse.md

Example client configuration for connecting to the HTTP+SSE server.

```json
{ "mcpServers": { "my-http-server": { "url": "http://localhost:8080/mcp/sse" } } }
```

--------------------------------

### Resource Subscriptions with ServerCapabilities

Source: https://github.com/php-mcp/server/blob/main/README.md

Shows how to enable resource subscriptions and notify clients of changes. The withCapabilities method enables resourcesSubscribe, prompts, and tools. In the resource handler, notifyResourceChange is called to alert subscribers when the resource changes.

```php
use PhpMcp\Schema\ServerCapabilities;

$server = Server::make()
    ->withCapabilities(ServerCapabilities::make(
        resourcesSubscribe: true,  // Enable resource subscriptions
        prompts: true,
        tools: true
    ))
    ->build();

// In your resource handler, you can notify clients of changes:
#[McpResource(uri: 'file://config.json')]
public function getConfig(): array
{
    // When config changes, notify subscribers
    $this->notifyResourceChange('file://config.json');
    return ['setting' => 'value'];
}
```

--------------------------------

### SessionManager::startGcTimer

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/session.md

Starts a periodic garbage collection timer. No-op if the timer is already running.

```APIDOC
## SessionManager::startGcTimer

### Description
Starts a periodic garbage collection timer. No-op if the timer is already running.

### Method
`startGcTimer`

### Parameters
None

### Return Value
`void`
```

--------------------------------

### Manual registration with ServerBuilder using withTool, withResource, withResourceTemplate, withPrompt

Source: https://github.com/php-mcp/server/blob/main/README.md

Registers tools, resources, resource templates, and prompts programmatically before build(). Supports class method handlers, invokable classes, and closures. Closures generate minimal JSON schemas from PHP type hints only; use #[Schema] attribute or custom $inputSchema for detailed schemas. Manual registrations are never cached and override discovered elements.

```php
use App\Handlers\{EmailHandler, ConfigHandler, UserHandler, PromptHandler};
use PhpMcp\Schema\{ToolAnnotations, Annotations};

$server = Server::make()
    ->withServerInfo('Manual Registration Server', '1.0.0')
    
    // Register a tool with handler method
    ->withTool(
        [EmailHandler::class, 'sendEmail'],     // Handler: [class, method]
        name: 'send_email',                     // Tool name (optional)
        description: 'Send email to user',     // Description (optional)
        annotations: ToolAnnotations::make(     // Annotations (optional)
            title: 'Send Email Tool'
        )
    )
    
    // Register invokable class as tool
    ->withTool(UserHandler::class)             // Handler: Invokable class
    
    // Register a closure as tool
    ->withTool(
        function(int $a, int $b): int {         // Handler: Closure
            return $a + $b;
        },
        name: 'add_numbers',
        description: 'Add two numbers together'
    )
    
    // Register a resource with closure
    ->withResource(
        function(): array {                     // Handler: Closure
            return ['timestamp' => time(), 'server' => 'php-mcp'];
        },
        uri: 'config://runtime/status',         // URI (required)
        mimeType: 'application/json'           // MIME type (optional)
    )
    
    // Register a resource template
    ->withResourceTemplate(
        [UserHandler::class, 'getUserProfile'],
        uriTemplate: 'user://{userId}/profile'  // URI template (required)
    )
    
    // Register a prompt with closure
    ->withPrompt(
        function(string $topic, string $tone = 'professional'): array {
            return [
                ['role' => 'user', 'content' => "Write about {$topic} in a {$tone} tone"]
            ];
        },
        name: 'writing_prompt'                  // Prompt name (optional)
    )
    
    ->build();
```

--------------------------------

### Discovery process with discover() method

Source: https://github.com/php-mcp/server/blob/main/README.md

Scans specified directories for elements, excluding given ones. Caches discovered elements unless force is true. Manual registrations are never cached and always override discovered elements. Cache is loaded automatically during build() if available.

```php
$server->discover(
    basePath: __DIR__,
    scanDirs: ['src/Handlers', 'src/Services'],  // Scan these directories
    excludeDirs: ['tests', 'vendor'],            // Skip these directories
    force: false,                                // Force re-scan (default: false)
    saveToCache: true                            // Save to cache (default: true)
);
```

--------------------------------

### listen()

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/transports-stdio.md

Starts listening on the input stream, parsing newline-delimited JSON-RPC messages. Emits lifecycle events and handles stream errors.

```APIDOC
## listen()

### Description
Starts listening on the input stream, parsing newline-delimited JSON-RPC messages. Emits lifecycle events and handles stream errors.

### Method
listen

### Throws
- `TransportException` - If already listening, or when the transport is closing/closed, or when stream opening fails.

### Behavior
- Wraps input/output resources in React streams.
- Buffers input until `\n`, trims, and parses each line via `PhpMcp\Schema\JsonRpc\Parser::parse()`.
- On parse failure, sends `Error::forParseError(...)` back over STDOUT and continues.
- STDOUT never receives non-serialized output; debug traffic must go to STDERR.
- Stream errors and `close` emit `error`/`client_disconnected` events.
- Registers `SIGTERM`/`SIGINT` handlers on the loop (best-effort).
- Emits `ready`, then `client_connected` with the fixed client id `'stdio'`.

### Returns
void
```

--------------------------------

### Session attribute methods

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/session.md

Methods to access and manipulate session attributes, including get, set, has, forget, clear, pull, all, and hydrate.

```APIDOC
## Session attribute methods

### Description
Methods to access and manipulate session attributes, including get, set, has, forget, clear, pull, all, and hydrate.

### Methods

#### getId
```php
public function getId(): string
```
Returns the session ID.

#### getHandler
```php
public function getHandler(): SessionHandlerInterface
```
Returns the storage handler.

#### generateId
```php
public function generateId(): string
```
Generates a new session ID using `bin2hex(random_bytes(16))`.

#### save
```php
public function save(): void
```
Writes the session data to the handler as JSON.

#### get
```php
public function get(string $key, mixed $default = null): mixed
```
Gets an attribute by key, supporting dot notation for nested access.

#### set
```php
public function set(string $key, mixed $value, bool $overwrite = true): void
```
Sets an attribute by key, supporting dot notation. Creates intermediate arrays; `overwrite=false` keeps existing values.

#### has
```php
public function has(string $key): bool
```
Checks if an attribute exists.

#### forget
```php
public function forget(string $key): void
```
Removes an attribute.

#### clear
```php
public function clear(): void
```
Clears all attributes.

#### pull
```php
public function pull(string $key, mixed $default = null): mixed
```
Gets and removes an attribute.

#### all
```php
public function all(): array
```
Returns all attributes.

#### hydrate
```php
public function hydrate(array $attributes): void
```
Merges attributes onto defaults, stripping any `id` key.

```

--------------------------------

### Server::discover()

Source: https://github.com/php-mcp/server/blob/main/_autodocs/configuration.md

Runtime call to discover MCP elements (tools, resources, prompts) from specified directories. Configures scan paths, exclusions, caching, and optional custom discoverer.

```APIDOC
## Server::discover()

### Description
Runtime call to discover MCP elements (tools, resources, prompts) from specified directories. Configures scan paths, exclusions, caching, and optional custom discoverer.

### Method
`Server::discover()`

### Parameters
- **$basePath** (string) - Required - Root for scan directories (must be a real directory).
- **$scanDirs** (array<string>) - Optional - Directories to scan. Default: `['.', 'src']`.
- **$excludeDirs** (array<string>) - Optional - Extra excludes (defaults always added: `vendor`, `tests`, `test`, `storage`, `cache`, `samples`, `docs`, `node_modules`, `.git`, `.svn`). Default: `[]`.
- **$force** (bool) - Optional - Bypass the discovery-already-ran guard. Default: `false`.
- **$saveToCache** (bool) - Optional - Persist discovered elements (needs `withCache()`). Default: `true`.
- **$discoverer** (?Discoverer) - Optional - Custom discoverer. Default: `null`.
```

--------------------------------

### bindTransport()

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/protocol.md

Attaches listeners to the transport for message, client connection, disconnection, and error events. If a transport is already bound, it unbinds first. Does not start listening.

```APIDOC
## bindTransport()

### Description
Attaches listeners (`message`, `client_connected`, `client_disconnected`, `error`) to the transport. If a transport is already bound, `unbindTransport()` is called first. Does **not** start listening.

### Method
bindTransport

### Parameters
- `$transport` (ServerTransportInterface) - Required - The transport to bind.

### Return
void
```

--------------------------------

### GET /mcp

Source: https://github.com/php-mcp/server/blob/main/_autodocs/endpoints.md

Opens a resumable SSE stream for server-to-client communication. Requires Accept: text/event-stream and Mcp-Session-Id headers. Optionally replays stored events after Last-Event-ID.

```APIDOC
## [GET] /mcp

### Description
Opens a resumable SSE stream for server-to-client communication. Requires Accept: text/event-stream and Mcp-Session-Id headers. Optionally replays stored events after Last-Event-ID.

### Method
GET

### Endpoint
/mcp

### Parameters
#### Headers
- **Accept** (string) - Required - Must be `text/event-stream`.
- **Mcp-Session-Id** (string) - Required - Session identifier.
- **Last-Event-ID** (string) - Optional - Last event ID for replay.

### Response
#### Success Response (200)
- **Content-Type**: `text/event-stream`
- **Cache-Control**: `no-cache`
- **Connection**: `keep-alive`
- **X-Accel-Buffering**: `no`

#### Error Responses
- **405** - Stateless mode (GET not supported).
- **406** - Accept does not include `text/event-stream`.
- **400** - Missing `Mcp-Session-Id`.

#### Response Example
SSE stream with `message` events and optional `id` fields.
```

--------------------------------

### Advanced Server Configuration with Dependencies

Source: https://github.com/php-mcp/server/blob/main/README.md

Configures a server with PSR-3 logger, PSR-16 cache, PSR-11 container, cache-backed sessions with 2-hour TTL, and pagination limit. Use when integrating with existing PSR dependencies.

```php
use Psr\Log\Logger;
use Psr\SimpleCache\CacheInterface;
use Psr\Container\ContainerInterface;

$server = Server::make()
    ->withServerInfo('Production Server', '1.0.0')
    ->withLogger($myPsrLogger)                    // PSR-3 Logger
    ->withCache($myPsrCache)                      // PSR-16 Cache  
    ->withContainer($myPsrContainer)              // PSR-11 Container
    ->withSession('cache', 7200)                  // Cache-backed sessions, 2hr TTL
    ->withPaginationLimit(50)                     // Limit list responses
    ->build();
```

--------------------------------

### handleInitialize() method signature

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/dispatcher.md

Echoes the client's protocol version if supported, otherwise returns the latest protocol version. Stores client info and protocol version on the session.

```php
public function handleInitialize(InitializeRequest $request, SessionInterface $session): InitializeResult
```

--------------------------------

### GET /{prefix}/sse

Source: https://github.com/php-mcp/server/blob/main/_autodocs/endpoints.md

Opens an SSE stream for the client to receive server events. The server assigns a session and returns an endpoint event with the message URL.

```APIDOC
## [GET] /{prefix}/sse

### Description
Opens an SSE stream for the client to receive server events. The server assigns a session and returns an endpoint event with the message URL.

### Method
GET

### Endpoint
/{prefix}/sse

### Parameters
#### Path Parameters
- **prefix** (string) - Required - The MCP path prefix (default: 'mcp').

### Response
#### Success Response (200)
- **Content-Type**: text/event-stream
- **Cache-Control**: no-cache
- **Connection**: keep-alive
- **X-Accel-Buffering**: no
- **Access-Control-Allow-Origin**: *

#### Response Example
```
event: endpoint
id: init-{sessionId}
data: http://host:port/{prefix}/message?clientId={sessionId}
```

After the endpoint event, the server emits `client_connected` and subsequent responses are SSE `message` events carrying JSON-RPC frames.
```

--------------------------------

### close()

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/transports-streamable-http.md

Closes the transport, including the socket, SSE streams, and GET stream, and rejects all pending JSON requests with a TransportException. Emits a 'close' event and is idempotent.

```APIDOC
## close()

### Description
Closes the transport, including the socket, SSE streams, and GET stream, and rejects all pending JSON requests with a TransportException. Emits a 'close' event and is idempotent.

### Method
close

### Signature
```php
public function close(): void
```

### Behavior
- Closes socket, SSE streams, GET stream.
- Rejects all pending JSON requests with `TransportException('Transport is closing.')`.
- Emits `'close'` with `['Transport closed.']`.
- Idempotent.
```

--------------------------------

### Server::build() method signature

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/server-builder.md

Declares the public build() method that returns a fully wired Server. It takes no parameters and throws ConfigurationException if withServerInfo() was never called or manual element registration fails.

```php
public function build(): Server
```

--------------------------------

### SSE endpoint event frame

Source: https://github.com/php-mcp/server/blob/main/_autodocs/endpoints.md

Sent by the server when a client opens the SSE stream at GET /{prefix}/sse. The event provides the session ID and the message endpoint URL.

```text
event: endpoint
id: init-{sessionId}
data: http://host:port/{prefix}/message?clientId={sessionId}
```

--------------------------------

### ArrayCache

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/defaults.md

Minimal in-memory PSR-16 cache implementing CacheInterface. Provides get, set, delete, clear, getMultiple, setMultiple, deleteMultiple, and has methods with TTL support.

```APIDOC
## ArrayCache

### Description
Minimal in-memory PSR-16 cache (not for production). Implements the full `CacheInterface`.

### Methods
- `get($key, $default = null)` - Retrieve an item from the cache.
- `set($key, $value, $ttl = null)` - Store an item in the cache.
- `delete($key)` - Delete an item from the cache.
- `clear()` - Clear all cache entries.
- `getMultiple($keys, $default = null)` - Retrieve multiple items.
- `setMultiple($values, $ttl = null)` - Store multiple items.
- `deleteMultiple($keys)` - Delete multiple items.
- `has($key)` - Check if an item exists.

### Parameters
- `$key` (string) - Required - Cache key.
- `$value` (mixed) - Required - Value to store.
- `$ttl` (int|DateInterval|null) - Optional - Time-to-live in seconds or DateInterval. Expired entries are dropped on access.

### Notes
- TTLs are `int` seconds or `DateInterval`.
- Expired entries are dropped on access.
```

--------------------------------

### build()

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/server-builder.md

Builds and returns a fully wired Server instance. It creates the Configuration, resolves the session handler, builds the SessionManager, Registry, and Protocol, and disables registry change notifications during manual element registration.

```APIDOC
## build()

### Description
Builds and returns a fully wired Server instance. It creates the Configuration, resolves the session handler, builds the SessionManager, Registry, and Protocol, and disables registry change notifications during manual element registration.

### Method
build

### Signature
public function build(): Server

### Parameters
None

### Return
- **Server** - A fully wired Server (Configuration + Registry + Protocol + SessionManager).

### Throws
- **ConfigurationException** - If `withServerInfo()` was never called, or any manual element registration fails during metadata derivation.
- **ConfigurationException** (from `createCacheSessionHandler()`) - When the `'cache'` session driver is selected without a configured cache.

### Usage Example
```php
use PhpMcp\Server\Server;
use PhpMcp\Server\Defaults\BasicContainer;

$basicContainer = new BasicContainer();
$basicContainer->set(\PDO::class, new \PDO('sqlite::memory:'));

$server = Server::make()
    ->withServerInfo('Dev Server', '0.1.0')
    ->withSession('array', 1800)
    ->withContainer($basicContainer)
    ->withTool(
        [OrderHandler::class, 'ship'],
        name: 'ship_order',
        description: 'Ship an order'
    )
    ->withResource(
        function (): array { return ['health' => 'ok']; },
        uri: 'config://runtime/status',
        mimeType: 'application/json'
    )
    ->withPrompt(
        function (string $topic): array {
            return [['role' => 'user', 'content' => "Write about $topic"]];
        },
        name: 'writing_prompt'
    )
    ->build();
```
```

--------------------------------

### Simple list completions with values parameter

Source: https://github.com/php-mcp/server/blob/main/README.md

Uses the #[CompletionProvider] attribute with the 'values' parameter to provide static completion lists for prompt arguments.

```php
use PhpMcp\Server\Attributes\{McpPrompt, CompletionProvider};

class ContentService
{
    #[McpPrompt(name: 'content_generator')]
    public function generateContent(
        #[CompletionProvider(values: ['blog', 'article', 'tutorial', 'guide', 'documentation'])]
        string $contentType,
        
        #[CompletionProvider(values: ['beginner', 'intermediate', 'advanced', 'expert'])]
        string $difficulty
    ): array {
        return [['role' => 'user', 'content' => "Create a {$difficulty} level {$contentType}"]];
    }
}
```

--------------------------------

### Using Schema attribute on method parameters

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/attributes.md

Shows how to apply Schema constraints to method parameters with the McpTool attribute. The example uses format for email and numeric constraints for age.

```php
use PhpMcp\Server\Attributes\{McpTool, Schema};

#[McpTool(name: 'create_user')]
public function createUser(
    #[Schema(format: 'email')] string $email,
    #[Schema(minimum: 18, maximum: 120)] int $age,
): bool {
    return $age >= 18;
}
```

--------------------------------

### Configure MCP Client (mcp.json)

Source: https://github.com/php-mcp/server/blob/main/README.md

Add this configuration to your client configuration (e.g., .cursor/mcp.json) to connect to the PHP calculator server. Replace the path with the absolute path to your mcp-server.php.

```json
{
    "mcpServers": {
        "php-calculator": {
            "command": "php",
            "args": ["/absolute/path/to/your/mcp-server.php"]
        }
    }
}
```

--------------------------------

### handlePing() method signature

Source: https://github.com/php-mcp/server/blob/main/_autodocs/api-reference/dispatcher.md

Always returns an empty result.

```php
public function handlePing(PingRequest $request): EmptyResult
```
Tokens:
Raw