[Mate] Add AI Mate component for MCP server integration #1146

wachterjohannes · 2025-12-15T19:47:44Z

Q	A
Bug fix?	no
New feature?	yes
Docs?	yes
Issues	-
License	MIT

Description

This PR introduces the AI Mate component (symfony/ai-mate), a standalone MCP server that enables AI assistants (Claude, GitHub Copilot, JetBrains AI, Cursor) to interact with PHP/Symfony applications through standardized tools.

Key Features

Core Server

Extension discovery system via extra.ai-mate in composer.json
Automatic service registration with Symfony DI container
Feature filtering to enable/disable specific tools per extension
Built-in tools: php-version, operating-system, php-extensions

Symfony Bridge (symfony/ai-mate-symfony)

symfony-services tool for container introspection
Parses compiled container XML to expose service definitions

Monolog Bridge (symfony/ai-mate-monolog)

Log search and analysis tools
Supports both JSON and standard Monolog line formats
Tools: monolog-search, monolog-search-regex, monolog-context-search, monolog-tail, monolog-list-files, monolog-list-channels, monolog-by-level

Architecture

Unlike other Symfony AI components, Mate is standalone and does not integrate with the AI Bundle. It runs as an independent MCP server via stdio transport.

src/ai-mate/
├── src/
│   ├── Command/           # CLI commands (serve, init, discover, clear-cache)
│   ├── Container/         # DI container management
│   ├── Discovery/         # Extension discovery system
│   ├── Capability/        # Built-in MCP tools
│   ├── Service/           # Internal services
│   └── Bridge/
│       ├── Symfony/       # Container introspection
│       └── Monolog/       # Log analysis
├── tests/
├── resources/             # Template files for init command
└── bin/mate               # Executable

Usage Example

# Install
composer require symfony/ai-mate

# Initialize configuration
vendor/bin/mate init

# Discover extensions
vendor/bin/mate discover

# Start server (typically called by AI assistant)
vendor/bin/mate serve

Creating custom tools:

// 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];
   }
}

Documentation

Comprehensive documentation added to docs/components/mate.rst:

Quick start guide
Configuration reference
Bridge documentation with troubleshooting
Integration guides for Claude Desktop, Claude Code, JetBrains AI
Extension development guide"

wachterjohannes · 2025-12-15T19:51:03Z

A special thanks goes to @Nyholm which was a great companion during the prototype phase and discussion partner on the symfony con in amsterdam where this ideas was born

Nyholm · 2025-12-15T19:52:34Z

Johannes and I have been working on this together for the past few weeks. The idea of AI Mate is to create a framework agnostic platform where we easily can integrate with Symfony/Sulu/Laravel/Whatever specific features.

chr-hertel · 2025-12-15T20:25:57Z

Coming out of stealth mode - hitting symfony/ai repo 🎉

Awesome stuff - thanks for driving that and spinning it up only in two weeks since SymfonyCon - will give it a deeper read, when you ping me 👍

.gitignore

splitsh.json

.github/scripts/validate-bridge-naming.sh

docs/components/mate.rst

chr-hertel · 2025-12-16T20:22:40Z

docs/components/mate/creating-extensions.rst

+
+    {
+        "name": "vendor/my-extension",
+        "type": "library",


we could also go with a specific type here, similar to phpstan:

Suggested change

"type": "library",

"type": "mate-extension",

@chr-hertel do you think we should also add that to the dicsovery?

@Nyholm and i also discussed that - what do you think?

Yeah. I imagine some packages just adding one file to their existing repo. They would not change the package type. So we cannot use it anyways. So why bother?

@chr-hertel i also think it could make sense to have the tools also included in a "bigger" repo and so i would also ignore the package type

docs/components/mate/creating-extensions.rst

src/ai-mate/README.md

src/ai-mate/bin/mate.php

src/ai-mate/composer.json

chr-hertel · 2025-12-16T20:46:00Z

Hey @wachterjohannes, thanks again, one rather conceptual question.

In understand this PR now like mate would integrate with the dependencies of the main application, right? did you consider installing it as a phar to get rid of that dependency range?

wachterjohannes · 2025-12-16T20:56:49Z

Hey @wachterjohannes, thanks again, one rather conceptual question.

In understand this PR now like mate would integrate with the dependencies of the main application, right? did you consider installing it as a phar to get rid of that dependency range?

yes absolutly - this should be a point on the list in the next weeks - but i think for now we could go with that and collect feedback!

src/ai-mate/CHANGELOG.md

src/mate/CHANGELOG.md

wachterjohannes · 2025-12-17T21:18:54Z

@chr-hertel @Nyholm @OskarStark i have tested it in my test repository - please take a look at the last 3 commit which contains a view necessary changes for the final touch.

Not sure why there around 400 checks 😂 but that seems normal

OskarStark · 2025-12-18T12:33:44Z

Can you please rebase? Thanks

This adds a new standalone component that provides an MCP (Model Context Protocol) server enabling AI assistants to interact with PHP applications. The component includes: - Core MCP server with extension discovery system - Symfony bridge for container introspection - Monolog bridge for log search and analysis - Built-in tools for PHP environment information - Comprehensive documentation

- Rename mcp.json to .mcp.json following MCP convention - Standardize parameter naming: use mate.root_dir consistently - Follow Symfony directory conventions: var/cache and var/log paths - Improve DI configuration with explicit args() and service() helpers - Ensure service visibility by setting public flag on existing services

- Rename resources/.mcp.json to resources/mcp.json as primary template - Update InitCommand to create mcp.json and symlink .mcp.json to it - Add symlink handling in InitCommand with user confirmation - Update tests to verify mcp.json creation and .mcp.json symlink - Improve removeDirectory helper to handle symlinks properly

- Change DEBUG to MATE_DEBUG for debug logging - Change FILE_LOG to MATE_FILE_LOG for file output - Update Logger service to use new variable names - Update troubleshooting documentation with new names - More specific names avoid conflicts with other tools

.github/workflows/validation.yaml

OskarStark · 2025-12-18T21:15:19Z

src/mate/composer.json

+        "phpstan/phpstan": "^2.0",
+        "phpstan/phpstan-strict-rules": "^2.0",
+        "phpunit/phpunit": "^11.5",
+        "symfony/dotenv": "^7.4|^8.0"


Why 7.4 for dotenv and console devs?

no special reason

OskarStark · 2025-12-18T21:21:37Z

src/mate/composer.json

+    ],
+    "require": {
+        "php": ">=8.2",
+        "mcp/sdk": "^0.1.0",


Suggested change

"mcp/sdk": "^0.1.0",

"mcp/sdk": "^0.1",

OskarStark · 2025-12-18T21:22:26Z

src/mate/composer.json

+    },
+    "require-dev": {
+        "ext-simplexml": "*",
+        "phpstan/phpstan": "^2.0",


Suggested change

"phpstan/phpstan": "^2.0",

"phpstan/phpstan": "^2.1",

OskarStark · 2025-12-18T21:23:17Z

src/mate/phpunit.xml.dist

@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/11.5/phpunit.xsd"


please use the local namespace location, like done in all other phpunnit.xml files

OskarStark · 2025-12-18T21:23:52Z

src/mate/phpunit.xml.dist

+         failOnRisky="true"
+         failOnWarning="true">
+    <testsuites>
+        <testsuite name="AI Mate Test Suite">


Suggested change

<testsuite name="AI Mate Test Suite">

<testsuite name="Symony AI Mate Test Suite">

OskarStark · 2025-12-18T21:25:21Z

src/mate/src/Bridge/Monolog/.phpunit.result.cache

please remove and add dedicated .gitignore files to the bridges

OskarStark · 2025-12-18T21:26:03Z

src/mate/src/Bridge/Monolog/CHANGELOG.md

+0.1
+---
+
+ * Initial release


Suggested change

* Initial release

* Add bridge

same for the other bridge

OskarStark · 2025-12-18T21:29:54Z

src/mate/src/Bridge/Monolog/Tests/Capability/LogSearchToolTest.php

+/**
+ * @author Johannes Wachter <johannes@sulu.io>
+ */
+class LogSearchToolTest extends TestCase


lets make the tests final

OskarStark · 2025-12-18T21:32:27Z

src/mate/src/Bridge/Monolog/composer.json

+    "name": "symfony/ai-monolog-mate",
+    "description": "Monolog bridge for AI Mate - provides log search and analysis tools",
+    "license": "MIT",
+    "type": "library",


"type": "symfony-ai-mate",

same for the other bridge

@OskarStark there was already discussion about that:
#1146 (comment)

We can do that for the build in bridges but we should not make that a requirement

OskarStark · 2025-12-18T21:33:12Z

src/mate/src/Bridge/Monolog/composer.json

+        "phpstan/phpstan": "^2.0",
+        "phpstan/phpstan-strict-rules": "^2.0"
+    },
+    "repositories": [


should be removed

currrently neccesary so that the tests are running - shouldnt we remove that with a follow up PR when the packages are published on packagist?

OskarStark · 2025-12-18T21:33:57Z

src/mate/src/Bridge/Monolog/config/services.php

+        ->set('ai_mate_monolog.log_dir', '%mate.root_dir%/var/log');
+
+    $configurator->services()
+        ->set(Monolog\Service\LogParser::class)


why not importing the namespaces?

OskarStark · 2025-12-18T21:36:12Z

docs/components/mate.rst

+
+    $ vendor/bin/mate serve
+
+Adding Custom Tools


Add Custom Tools

OskarStark · 2025-12-18T21:39:03Z

docs/components/mate/creating-extensions.rst

+        "name": "vendor/my-extension",
+        "type": "library",
+        "require": {
+            "symfony/ai-mate": "^1.0"


Suggested change

"symfony/ai-mate": "^1.0"

"symfony/ai-mate": "^0.1"

OskarStark · 2025-12-18T21:40:15Z

docs/components/mate/creating-extensions.rst

+        $services = $configurator->services();
+
+        // Register a service with parameters
+        $services->set(MyApiClient::class)


Add a use statement for this class like App\MyApiClient;

chr-hertel added the Mate Issues & PRs about the AI Mate component label Dec 15, 2025

wachterjohannes force-pushed the feature/ai-mate-component branch 9 times, most recently from 6f175e1 to da96bfe Compare December 16, 2025 19:05