mirror of
https://github.com/symfony/ai.git
synced 2026-03-23 23:42:18 +01:00
573 lines
16 KiB
ReStructuredText
573 lines
16 KiB
ReStructuredText
Symfony AI - Mate Component
|
|
===========================
|
|
|
|
The Mate component provides an MCP (Model Context Protocol) server that enables
|
|
AI assistants to interact with PHP applications (including Symfony) through
|
|
standardized tools. This is a development tool, not intended for production use.
|
|
|
|
Installation
|
|
------------
|
|
|
|
.. code-block:: terminal
|
|
|
|
$ 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:
|
|
|
|
.. code-block:: terminal
|
|
|
|
$ composer require --dev symfony/ai-mate
|
|
|
|
Initialize configuration:
|
|
|
|
.. code-block:: terminal
|
|
|
|
$ 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:
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"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:
|
|
|
|
.. code-block:: terminal
|
|
|
|
$ composer dump-autoload
|
|
|
|
Discover available extensions:
|
|
|
|
.. code-block:: terminal
|
|
|
|
$ vendor/bin/mate discover
|
|
|
|
Start the MCP server:
|
|
|
|
.. code-block:: terminal
|
|
|
|
$ 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::
|
|
|
|
// 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
|
|
|
|
.. tip::
|
|
|
|
The folder and default configuration is automatically generated by running ``mate init``.
|
|
|
|
Extensions Configuration
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
::
|
|
|
|
// 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],
|
|
];
|
|
|
|
Services Configuration
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
::
|
|
|
|
// 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
|
|
;
|
|
};
|
|
|
|
Disabling Specific Features
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Use the MateHelper class to disable specific features::
|
|
|
|
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'],
|
|
]);
|
|
};
|
|
|
|
Environment Variables
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Use ``%env(VAR_NAME)%`` syntax in service configuration to reference environment variables.
|
|
See the `Symfony documentation on environment variables`_ for more information.
|
|
|
|
.. _`Symfony documentation on environment variables`: https://symfony.com/doc/current/configuration.html#configuration-based-on-environment-variables
|
|
|
|
Adding Third-Party Extensions
|
|
-----------------------------
|
|
|
|
1. Install the package:
|
|
|
|
.. code-block:: terminal
|
|
|
|
$ composer require vendor/symfony-tools
|
|
|
|
2. Discover available tools (auto-generates/updates ``mate/extensions.php``):
|
|
|
|
.. code-block:: terminal
|
|
|
|
$ vendor/bin/mate discover
|
|
|
|
3. Optionally disable specific extensions::
|
|
|
|
// mate/extensions.php
|
|
return [
|
|
'vendor/symfony-tools' => ['enabled' => true],
|
|
'vendor/unwanted-tools' => ['enabled' => false],
|
|
];
|
|
|
|
To create a third party extension, see :doc:`mate/creating-extensions`.
|
|
|
|
Available Bridges
|
|
-----------------
|
|
|
|
Symfony Bridge
|
|
~~~~~~~~~~~~~~
|
|
|
|
The Symfony bridge (``symfony/ai-symfony-mate-extension``) provides container introspection tools
|
|
for Symfony applications:
|
|
|
|
* ``symfony-services`` - List all Symfony services from the compiled container
|
|
|
|
Configure the cache directory::
|
|
|
|
$container->parameters()
|
|
->set('ai_mate_symfony.cache_dir', '%root_dir%/var/cache');
|
|
|
|
**Troubleshooting**
|
|
|
|
*Container not found*:
|
|
|
|
Ensure the cache directory parameter points to the correct location. The bridge looks for
|
|
the compiled container XML file (e.g., ``App_KernelDevDebugContainer.xml``) in the cache directory.
|
|
|
|
*Services not appearing*:
|
|
|
|
1. Clear Symfony cache: ``bin/console cache:clear``
|
|
2. Ensure the container is compiled (warm up cache)
|
|
3. Verify the container XML file exists in the cache directory
|
|
|
|
Monolog Bridge
|
|
~~~~~~~~~~~~~~
|
|
|
|
The Monolog bridge (``symfony/ai-monolog-mate-extension``) provides log search and analysis tools:
|
|
|
|
* ``monolog-search`` - Search log entries by text term with optional filters
|
|
* ``monolog-search-regex`` - Search log entries using regex patterns
|
|
* ``monolog-context-search`` - Search logs by context field value
|
|
* ``monolog-tail`` - Get the last N log entries
|
|
* ``monolog-list-files`` - List available log files
|
|
* ``monolog-list-channels`` - List all log channels
|
|
* ``monolog-by-level`` - Get log entries filtered by level
|
|
|
|
Configure the log directory::
|
|
|
|
$container->parameters()
|
|
->set('ai_mate_monolog.log_dir', '%root_dir%/var/log');
|
|
|
|
**Troubleshooting**
|
|
|
|
*Logs not found*:
|
|
|
|
Ensure the log directory parameter points to the correct location where your Monolog
|
|
log files are stored.
|
|
|
|
*Log parsing errors*:
|
|
|
|
1. Verify log format is standard Monolog line format or JSON
|
|
2. Check file permissions on log files
|
|
3. Ensure log files are not empty or corrupted
|
|
|
|
Profiler Bridge
|
|
~~~~~~~~~~~~~~~
|
|
|
|
The Profiler bridge (``symfony/ai-profiler-mate-extension``) provides MCP tools and resources
|
|
for accessing Symfony profiler data:
|
|
|
|
**MCP Tools:**
|
|
|
|
* ``profiler-list`` - List available profiler profiles with summary data
|
|
* ``profiler-latest`` - Get the latest profiler profile summary
|
|
* ``profiler-search`` - Search profiles by criteria (route, method, status code, date range)
|
|
* ``profiler-get`` - Get a specific profile by token
|
|
|
|
All tools return profiles with a ``resource_uri`` field that points to the full profile resource.
|
|
|
|
**MCP Resources:**
|
|
|
|
* ``profiler://profile/{token}`` - Full profile details including metadata and list of available collectors with URIs
|
|
* ``profiler://profile/{token}/{collector}`` - Detailed collector-specific data (request, response, exception, events, etc.)
|
|
|
|
**Configuration:**
|
|
|
|
Single profiler directory (default)::
|
|
|
|
$container->parameters()
|
|
->set('ai_mate_profiler.profiler_dir', '%mate.root_dir%/var/cache/dev/profiler');
|
|
|
|
Multiple directories with contexts (e.g., for multi-kernel applications)::
|
|
|
|
$container->parameters()
|
|
->set('ai_mate_profiler.profiler_dir', [
|
|
'website' => '%mate.root_dir%/var/cache/website/dev/profiler',
|
|
'admin' => '%mate.root_dir%/var/cache/admin/dev/profiler',
|
|
]);
|
|
|
|
When using multiple directories, profiles include a ``context`` field for filtering.
|
|
|
|
**Example Usage:**
|
|
|
|
Search for errors::
|
|
|
|
// Using profiler-search tool
|
|
{
|
|
"method": "tools/call",
|
|
"params": {
|
|
"name": "profiler-search",
|
|
"arguments": {
|
|
"statusCode": 500,
|
|
"limit": 20
|
|
}
|
|
}
|
|
}
|
|
|
|
Access full profile via resource::
|
|
|
|
// Using resource template
|
|
{
|
|
"method": "resources/read",
|
|
"params": {
|
|
"uri": "profiler://profile/abc123"
|
|
}
|
|
}
|
|
|
|
Access specific collector::
|
|
|
|
{
|
|
"method": "resources/read",
|
|
"params": {
|
|
"uri": "profiler://profile/abc123/exception"
|
|
}
|
|
}
|
|
|
|
**Extensibility:**
|
|
|
|
Create custom collector formatters by implementing ``CollectorFormatterInterface`` and
|
|
registering via DI tag ``ai_mate.profiler_collector_formatter``.
|
|
|
|
**Troubleshooting:**
|
|
|
|
*Profiles not found*:
|
|
|
|
1. Ensure the profiler directory parameter points to the correct location
|
|
2. Verify Symfony profiler is enabled in your environment
|
|
3. Generate some HTTP requests to create profile data
|
|
|
|
*Collector data not available*:
|
|
|
|
1. Check that the specific collector is enabled in Symfony profiler configuration
|
|
2. Verify the profile was captured with that collector active
|
|
|
|
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:**
|
|
|
|
.. code-block:: terminal
|
|
|
|
# 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:**
|
|
|
|
.. code-block:: terminal
|
|
|
|
# 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:**
|
|
|
|
.. code-block:: terminal
|
|
|
|
# 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:**
|
|
|
|
.. code-block:: terminal
|
|
|
|
# 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:**
|
|
|
|
.. code-block:: terminal
|
|
|
|
# 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
|
|
---------------
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
mate/integration
|
|
mate/creating-extensions
|
|
mate/troubleshooting
|
|
|
|
.. _`MCP SDK documentation`: https://github.com/modelcontextprotocol/php-sdk
|