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

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-19T19:50:00Z

@OskarStark i have rebased again - and except the open questions there should be fixed everything

OskarStark

Some comments

docs/components/mate.rst

OskarStark · 2025-12-20T08:04:38Z

docs/components/mate.rst

+Symfony Bridge
+~~~~~~~~~~~~~~
+
+The Symfony bridge (``symfony/ai-symfony-mate``) provides container introspection tools


I am still thinking about the naming, symfony/ai-symfony-mate-extension would be the best fit IMHO, but we are talking about bridges here.

Proposal, lets keep the therm Bridge in the namespace and code, to ease development (I don't want to have special cases by introducing an Extension namespace), but lets use extension to communicate it in the docs and for package names. WDYT?

@chr-hertel @Nyholm

hmm, not sure, feels inconsistent to me - we don't have it anywhere else symfony/ai-azure-platform-extension?

should we drop the term "extension" at all in favor of "bridge"?
i feel it's more like coming from phpstan - with symfony not usually used but bridge

Ok, lets use the bridge wording everywhere and get rid of extension term

docs/components/mate/integration.rst

src/mate/CHANGELOG.md

src/mate/src/Bridge/Symfony/phpstan.dist.neon

src/mate/src/Bridge/Symfony/phpunit.xml.dist

src/mate/src/Bridge/Monolog/phpunit.xml.dist

src/mate/src/Exception/MissingDependencyException.php

src/mate/src/Exception/UnsupportedVersionException.php

chr-hertel · 2025-12-20T09:03:35Z

I guess "extension" vs "bridge" is some kind of higher level decision we need to take.

wachterjohannes · 2025-12-20T10:52:49Z

@OskarStark @chr-hertel i also think that bridge would fit better in this repo. not sure if it makes sense for external developer. But let us try and if we can explain that well it should not be an issue in the future.

@Nyholm is that ok for you?

wachterjohannes · 2025-12-20T14:42:46Z

@OskarStark will go on with the extension => bridge renaming after @Nyholm give his opinion about that

OskarStark · 2025-12-20T16:38:43Z

No worries 😉

wachterjohannes · 2025-12-20T20:09:00Z

@OskarStark @chr-hertel @Nyholm i have already done the renaming in the latest commit - if you are all happy with it i should give it a last try in my example repo before we can finally merge it

OskarStark · 2025-12-20T21:47:11Z

Do you think it is a good idea to add it to the demo application in this repo?

Nyholm · 2025-12-20T22:00:34Z

I do believe an "extension" is a more generic term than "bridge". A "bridge" connects two things. An "extension" adds some kind of functionally.

I agree that we should be constant and call it "bridge" in this repo. Ie, we should use the "Bridge" namespace and name our code accordingly. BUT, if I create "Tobias private Mate integration"-package, that is for sure an "extension".

So in the AI Mate code, we should refer to "extension".

I see that you changed to "Bridge". I dont think this should be a blocker for merging. We can open an issue and talk about it before the first tag.

wachterjohannes · 2025-12-21T06:53:24Z

@Nyholm i also agree to you! as i already mentioned that the term is not so self-explaining.

I have done the renaming in a completly own commit so no worries to revert that.

@OskarStark i also thought about that. but i think that should be part of a follow up pull-request.

OskarStark · 2025-12-21T08:26:11Z

Ok let's go with bridge and open an issue. Afterwards let's create a PR with extension, but we would need to tackle a lot of scripts etc.

I would also like @fabpot's opinion if extension renaming would have some more side effects

wachterjohannes · 2025-12-21T10:43:46Z

@OskarStark think thats a pragmatic solution! ler us merge it with bridge, merge it and i will create follow up PRs about extension term and example in the next days

fabpot · 2025-12-21T11:12:24Z

Ok let's go with bridge and open an issue. Afterwards let's create a PR with extension, but we would need to tackle a lot of scripts etc.

I would also like @fabpot's opinion if extension renaming would have some more side effects

Anything happening before 1.0 has not big consequences.

OskarStark

Good to merge from my side @chr-hertel, please give a final review

wachterjohannes · 2025-12-21T14:20:06Z

@OskarStark i tried this in my example repo so also from my side its good to go

OskarStark · 2025-12-21T14:24:10Z

As it is quite a new concept of a Symfony component, can you maybe share a small video in the PR header how you use it in PhpStorm or anywhere else?

chr-hertel · 2025-12-21T14:48:36Z

Good to merge from my side @chr-hertel, please give a final review

on it right now 👍

chr-hertel

will provide a follow up about referencing dev for composer, but we should just bring that in and level up in smaller steps

chr-hertel · 2025-12-21T15:18:09Z

Thank you @wachterjohannes.

wachterjohannes · 2025-12-21T15:20:56Z

@chr-hertel it was a pleasure! but now we have to improve it 😅

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