Symfony AI - Mate Component

Installation

1

$ composer require --dev symfony/ai-mate

Purpose

Symfony AI Mate is a development tool that creates a local MCP server to enhance your AI assistant (JetBrains AI, Claude, GitHub Copilot, Cursor, etc.) with specific knowledge about your PHP application and development environment.

Important: This is intended for development and debugging only, not for production deployment.

This is the core package that creates and manages your MCP server. It works with any PHP application - while it includes Symfony-specific tools via bridges, the core functionality is framework-agnostic.

Quick Start

Install with composer:

1

$ composer require --dev symfony/ai-mate

Initialize configuration:

1

$ vendor/bin/mate init

This creates:

• .mate/ directory with configuration files
• mate/ directory for custom extensions
• mcp.json for MCP client configuration

It also updates your composer.json with the following configuration:

1
2
3
4
5
6
7
8
9
10
11
12
13

{
    "autoload": {
        "psr-4": {
            "App\\Mate\\": "mate/"
        }
    },
    "extra": {
        "ai-mate": {
            "scan-dirs": ["mate"],
            "includes": ["services.php"]
        }
    }
}

After running mate init, update your autoloader:

1

$ composer dump-autoload

Discover available extensions:

1

$ vendor/bin/mate discover

Start the MCP server:

1

$ vendor/bin/mate serve

Add Custom Tools

The easiest way to add tools is to create a mate folder next to your src and tests directories, then add a class with a method using the #[McpTool] attribute:

1
2
3
4
5
6
7
8
9
10
11
12
13

// mate/MyTool.php
namespace App\Mate;

use Mcp\Capability\Attribute\McpTool;

class MyTool
{
    #[McpTool(name: 'my_tool', description: 'My custom tool')]
    public function execute(string $param): array
    {
        return ['result' => $param];
    }
}

More about attributes and how to configure Prompts, Resources and more can be found at the MCP SDK documentation.

Configuration

The configuration folder is called .mate and is located in your project's root directory. It contains two important files:

• .mate/extensions.php - Enable/disable extensions
• .mate/services.php - Configure settings

1
2
3
4
5
6
7
8

// .mate/extensions.php
// This file is managed by 'mate discover'
// You can manually edit to enable/disable extensions

return [
    'vendor/package-name' => ['enabled' => true],
    'vendor/another-package' => ['enabled' => false],
];

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// .mate/services.php
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $container): void {
    $container->parameters()
        // Override default parameters here
        // ->set('mate.cache_dir', sys_get_temp_dir().'/mate')
        // ->set('mate.env_file', ['.env'])
    ;

    $container->services()
        // Register your custom services here
    ;
};

1
2
3
4
5
6
7
8

use Symfony\AI\Mate\Container\MateHelper;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $container): void {
    MateHelper::disableFeatures($container, [
        'symfony/ai-mate' => ['php-version', 'operating-system'],
    ]);
};

Adding Third-Party Extensions

1. Install the package:

   1

   $ composer require vendor/symfony-tools

2. Discover available tools (auto-generates/updates .mate/extensions.php):

   1

   $ vendor/bin/mate discover

3. Optionally disable specific extensions:

   1
   2
   3
   4
   5

   // .mate/extensions.php
   return [
       'vendor/symfony-tools' => ['enabled' => true],
       'vendor/unwanted-tools' => ['enabled' => false],
   ];

To create a third party extension, see Creating MCP Extensions.

Available Bridges

1
2

$container->parameters()
    ->set('ai_mate_symfony.cache_dir', '%root_dir%/var/cache');

1
2

$container->parameters()
    ->set('ai_mate_monolog.log_dir', '%root_dir%/var/log');

Built-in Tools

The core package provides basic system information tools:

• php-version - Get the PHP version
• operating-system - Get the operating system
• operating-system-family - Get the OS family
• php-extensions - List loaded PHP extensions

Commands

mate init

Initialize AI Mate configuration and create the .mate/ directory.

mate discover

Scan for MCP extensions in installed packages. This command will:

• Scan your vendor directory for packages with extra.ai-mate configuration
• Generate or update .mate/extensions.php with discovered extensions
• Preserve existing enabled/disabled states for known extensions
• Default new extensions to enabled

mate serve

Start the MCP server with stdio transport.

mate clear-cache

Clear the MCP server cache.

Security

For security, no vendor extensions are enabled by default. You must explicitly enable packages in .mate/extensions.php by setting their enabled flag to true.

The local mate/ directory is always enabled for rapid development.

Further Reading