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/src 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/src"
        }
    },
    "extra": {
        "ai-mate": {
            "scan-dirs": ["mate/src"],
            "includes": ["mate/config.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/src 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/config.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/config.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_symfony.profiler_dir', '%mate.root_dir%/var/cache/dev/profiler');

1
2
3
4
5

$container->parameters()
    ->set('ai_mate_symfony.profiler_dir', [
        'website' => '%mate.root_dir%/var/cache/website/dev/profiler',
        'admin' => '%mate.root_dir%/var/cache/admin/dev/profiler',
    ]);

1
2
3
4
5
6
7
8
9
10
11

// Using symfony-profiler-search tool
{
    "method": "tools/call",
    "params": {
        "name": "symfony-profiler-search",
        "arguments": {
            "statusCode": 500,
            "limit": 20
        }
    }
}

1
2
3
4
5
6
7

// Using resource template
{
    "method": "resources/read",
    "params": {
        "uri": "symfony-profiler://profile/abc123"
    }
}

1
2
3
4
5
6

{
    "method": "resources/read",
    "params": {
        "uri": "symfony-profiler://profile/abc123/exception"
    }
}

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.

mate debug:capabilities

Display all discovered MCP capabilities grouped by extension. This command is useful for:

• Verifying extension installation and capability registration
• Debugging missing or misconfigured extensions
• Understanding which package provides each capability
• Inspecting available tools during development

Options:

--format=FORMAT

Output format: text (default) or json

--extension=EXTENSION

Filter by extension package name (e.g., symfony/ai-monolog-mate-extension)

--type=TYPE

Filter by capability type: tool, resource, prompt, or template

Examples:

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

# Show all capabilities
$ vendor/bin/mate debug:capabilities

# Show only tools
$ vendor/bin/mate debug:capabilities --type=tool

# Show capabilities from specific extension
$ vendor/bin/mate debug:capabilities --extension=symfony/ai-monolog-mate-extension

# JSON output for scripting
$ vendor/bin/mate debug:capabilities --format=json

# Root project capabilities
$ vendor/bin/mate debug:capabilities --extension=_custom

mate debug:extensions

Display detailed information about discovered and loaded MCP extensions. This command is useful for:

• Understanding which extensions are discovered vs enabled vs loaded
• Debugging extension loading issues
• Verifying extension configuration from mate/extensions.php
• Inspecting scan directories and include files
• Troubleshooting why an extension isn't providing capabilities

Status Indicators:

[enabled]

Extension is configured to load in mate/extensions.php

[loaded]

Extension successfully loaded into the DI container

[not loaded]

Extension failed to load (package removed, error, etc.) - useful for troubleshooting

Options:

--format=FORMAT

Output format: text (default) or json

--show-all

Show all discovered extensions including disabled ones

Examples:

1
2
3
4
5
6
7
8

# Show enabled extensions
$ vendor/bin/mate debug:extensions

# Show all extensions (including disabled)
$ vendor/bin/mate debug:extensions --show-all

# JSON output for scripting
$ vendor/bin/mate debug:extensions --format=json

mate mcp:tools:list

List all available MCP tools with their metadata. This command provides a compact overview of tools for quick reference and filtering.

Options:

--filter=PATTERN

Filter tools by name pattern (supports wildcards like search* or *logs)

--extension=EXTENSION

Filter tools by extension package name

--format=FORMAT

Output format: table (default) or json

Examples:

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

# List all tools
$ vendor/bin/mate mcp:tools:list

# Filter by name pattern
$ vendor/bin/mate mcp:tools:list --filter="monolog*"
$ vendor/bin/mate mcp:tools:list --filter="*search"

# Show tools from specific extension
$ vendor/bin/mate mcp:tools:list --extension=symfony/ai-monolog-mate-extension

# JSON output for scripting
$ vendor/bin/mate mcp:tools:list --format=json

# Combined filters
$ vendor/bin/mate mcp:tools:list --extension=symfony/ai-monolog-mate-extension --filter="*search"

mate mcp:tools:inspect

Display detailed information about a specific MCP tool including its full JSON schema. This command is useful for understanding tool parameters and requirements.

Arguments:

tool-name

Name of the tool to inspect (required)

Options:

--format=FORMAT

Output format: text (default) or json

Examples:

1
2
3
4
5
6
7
8

# Inspect a specific tool
$ vendor/bin/mate mcp:tools:inspect php-version

# Inspect extension tool
$ vendor/bin/mate mcp:tools:inspect search-logs

# JSON output for scripting
$ vendor/bin/mate mcp:tools:inspect php-version --format=json

mate mcp:tools:call

Execute MCP tools via JSON input parameters. This command allows you to test and debug tools by executing them directly from the command line.

Arguments:

tool-name

Name of the tool to execute (required)

json-input

JSON object with tool parameters (required)

Options:

--format=FORMAT

Output format: pretty (default) or json

Examples:

1
2
3
4
5
6
7
8

# Execute tool with empty parameters
$ vendor/bin/mate mcp:tools:call php-version '{}'

# Execute tool with parameters
$ vendor/bin/mate mcp:tools:call search-logs '{"query": "error", "level": "error"}'

# JSON output format
$ vendor/bin/mate mcp:tools:call php-version '{}' --format=json

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