[Mate] Add AI Mate component for MCP server integration

.github/workflows/validation.yaml

@@ -103,3 +103,21 @@ jobs:
             - name: Validate platform bridges have correct type
               run: .github/scripts/validate-bridge-type.sh platform
 
+    validate_mate_bridges:
+        name: Mate Bridges
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v6
+
+            - name: Validate Mate bridge naming conventions
+              run: .github/scripts/validate-bridge-naming.sh mate mate
+
+            - name: Validate Mate bridges are in splitsh.json
+              run: .github/scripts/validate-bridge-splitsh.sh mate
+
+            - name: Validate Mate bridges have required files
+              run: .github/scripts/validate-bridge-files.sh mate
+
+            - name: Validate Mate bridges have correct type
+              run: .github/scripts/validate-bridge-type.sh mate

docs/components/index.rst

@@ -6,5 +6,6 @@ Components
 
     agent
     chat
+    mate
     platform
     store

docs/components/mate.rst

@@ -0,0 +1,308 @@
+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 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 symfony/ai-mate
+
+Initialize configuration:
+
+.. code-block:: terminal
+
+    $ 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:
+
+.. code-block:: json
+
+    {
+        "autoload": {
+            "psr-4": {
+                "App\\Mate\\": "mate/"
+            }
+        },
+        "extra": {
+            "ai-mate": {
+                "scan-dirs": ["mate"],
+                "includes": ["services.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`` 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/services.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/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
+        ;
+    };
+
+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.
+
+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``) 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``) 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
+
+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
+---------------
+
+.. toctree::
+    :maxdepth: 1
+
+    mate/integration
+    mate/creating-extensions
+    mate/troubleshooting
+
+.. _`MCP SDK documentation`: https://github.com/modelcontextprotocol/php-sdk