mcp

This MCP server provides a flexible implementation for the Spiral Framework, enabling automatic discovery and registration of MCP tools via PHP attributes. It supports multiple transports (HTTP, streaming HTTP, and STDIO) and integrates with Spiral's DI container for dependency injection. Tools are defined as PHP classes with the Tool attribute and optional behavioral attributes to tailor their behavior. Once running, clients can send requests to the configured MCP endpoint and receive validated responses according to the generated JSON schemas.

Prerequisites:

• PHP 8.3 or higher
• Composer
• Spiral Framework project setup

Install the MCP server package:

composer require spiral/mcp-server

Register the MCP server bootloader in your Spiral application (example):

// app/src/Application/Kernel.php
use Spiral\McpServer\Bootloader\McpServerBootloader;

protected const LOAD = [
    // ... other bootloaders
    McpServerBootloader::class,
];

Create and configure tools as PHP classes with the appropriate attributes. Example:

namespace App\Tool;

use Spiral\McpServer\Attribute\Tool;
use Spiral\McpServer\Attribute\IsReadonly;

#[Tool(
    name: 'calculator_add',
    description: 'Adds two numbers together'
)]
#[IsReadonly]
class CalculatorTool
{
    public function __invoke(CalculatorRequest $request): array
    {
        return [
            'result' => $request->a + $request->b,
            'operation' => 'addition'
        ];
    }
}

Define request schemas using the JSON schema generator attributes as shown in the README examples. Then start the server. Example two start options are described in the Quick Start section of the README, typically via the MCP dispatcher or console command, depending on your deployment.

To run with the MCP dispatcher (production-ready):

SAPI=mcp php app.php

Alternatively, start using the console command:

php app.php mcp

Your MCP server should now be available at the configured host/port and ready to handle requests with the discovered tools.

Tips and notes:

• Ensure your environment variables (MCP_TRANSPORT, MCP_HOST, MCP_PORT, MCP_SERVER_NAME, MCP_SERVER_VERSION) are set to reflect your deployment.
• The server relies on Spiral's dependency injection container for tool provisioning; ensure your tools declare and inject dependencies properly.
• JSON schema generation can help validate request payloads; consider annotating fields with the Field attribute for rich metadata.
• If you modify tool attributes or add new tools, re-run any build steps or cache clears as required by your deployment to ensure automatic discovery picks up changes.
• When using docker, choose an image that matches your PHP version and dependencies to avoid runtime mismatches.