README

Maestro gives AI coding agents a reliable view of a real Symfony application. It exposes read-only MCP tools for routes, services, configuration, Doctrine, logs, the profiler, and common Symfony ecosystem packages, then teaches agents when to use those tools through instructions and on-demand skills.

Maestro is inspired by Laravel Boost, but is an independent community project and is not affiliated with or endorsed by Symfony or Laravel.

Requirements

PHP 8.2 or newer
Symfony 6.4, Symfony 7.3 or newer, or Symfony 8.x
Composer 2
An MCP-capable coding agent

Maestro is a development dependency and should not be installed in production.

Installation

Install Maestro in an existing Symfony application and run the setup once:

composer require --dev janvdb2000/maestro
vendor/bin/maestro install

maestro install does everything the project needs: it writes the local AI Mate configuration under mate/, enables the installed extensions, generates the agent instructions, installs the skills for supported coding agents, and creates mcp.json plus the .mcp.json that Claude Code reads. It asks no questions and is safe to run again at any time.

What Composer asks and prints

Maestro depends on AI Mate, which ships a Composer plugin. Two things follow from that:

Composer asks once whether to trust symfony/ai-mate-composer-plugin. Answering y lets Composer refresh Maestro automatically after every composer install and composer update. To answer up front — in CI, for example — run this before requiring the package:
```
composer config --no-plugins allow-plugins.symfony/ai-mate-composer-plugin true
```
Until the setup has run once, that plugin prints an AI Mate installed! Run vendor/bin/mate init box after every Composer command. vendor/bin/maestro install covers that step and the rest, so the box is gone from then on.

Updating

composer update janvdb2000/maestro
vendor/bin/maestro install

Command line

maestro wraps AI Mate: it owns install and discover, adds the short tool commands below, and passes everything else straight through. Run vendor/bin/maestro without arguments for the overview, or vendor/bin/maestro list for every AI Mate command.

Call a tool through Maestro's short CLI syntax:

vendor/bin/maestro tool symfony-app-info
vendor/bin/maestro tool symfony-routes '{"method":"GET"}' --format=json
vendor/bin/maestro tools
vendor/bin/maestro inspect symfony-app-info

If vendor/bin is on your PATH, the first example is exactly maestro tool symfony-app-info. Otherwise, composer exec maestro -- tool symfony-app-info works without changing your PATH.

The setup registers the MCP server in mcp.json, mirrored to .mcp.json for Claude Code:

{
    "mcpServers": {
        "symfony-ai-mate": {
            "command": "php",
            "args": ["./vendor/bin/mate", "serve", "--force-keep-alive"]
        }
    }
}

If your project runs inside Docker, DDEV or another development environment, replace php with the command that executes PHP there, for example ddev exec php. Restart the MCP server after installing, updating, adding, or renaming tools.

Tools

AI Mate also provides server-info. Maestro adds the following tools:

Area	Tools
Project	`symfony-app-info`, `symfony-routes`, `symfony-services`, `symfony-config`, `symfony-console-commands`
Doctrine	`doctrine-entities`, `doctrine-relations`, `doctrine-schema`, `doctrine-migrations`, `doctrine-query-readonly`
Debugging	`symfony-last-error`, `symfony-profiler`, `monolog-search`, `deprecations`, `mailer-debug`
Ecosystem	`messenger`, `twig`, `security`, `api-platform`, `ux-turbo`, `easyadmin`
Documentation	`search-docs`

Every optional integration reports an availability response with the package required to enable it. An unavailable integration does not prevent the MCP server or other tools from loading.

Tool responses are encoded as TOON rather than JSON, which drops the punctuation an agent does not need and lists uniform rows as a table:

available: true
routes[2]{name,path}:
  home,/
  post,"/p/{id}"

Maestro depends on helgesverre/toon for this. AI Mate falls back to JSON when that package is absent, so the tool contracts are unchanged either way — only the number of tokens differs.

Safety

Maestro treats application inspection as read-only:

MCP tool annotations declare read-only, non-destructive behavior.
Credentials and sensitive configuration values are redacted.
Potentially unbounded output is capped and marked when truncated.
Missing bundles and kernel boot failures are returned as structured responses.
Documentation search is the only tool that accesses the network.

The SQL query tool is disabled by default. To enable it for a trusted local development session, start the MCP server with MAESTRO_ALLOW_QUERY=1. It accepts one SELECT or EXPLAIN, rejects stacked and locking statements, caps results at 200 rows, applies a timeout where supported, and always rolls back its transaction.

Optional integrations

Maestro adapts to packages already installed by the application:

Capability	Package
Doctrine inspection	`doctrine/doctrine-bundle`, `doctrine/orm`
Migration status	`doctrine/doctrine-migrations-bundle`
Guarded SQL queries	`phpmyadmin/sql-parser`
Templates	`symfony/twig-bundle`
Security	`symfony/security-bundle`
Messages	`symfony/messenger`
Mail profiling	`symfony/mailer`, `symfony/web-profiler-bundle`
Logs	`symfony/monolog-bundle`
API resources	`api-platform/core`
Admin panels	`easycorp/easyadmin-bundle`
Frontend stack	`symfony/ux-turbo`

Instructions and skills

INSTRUCTIONS.md contains the short, always-available rules that tell an agent to inspect the project before guessing. The skills under skills/ provide deeper workflows for Symfony, Doctrine, Security, and testing only when a matching task activates them.

Run vendor/bin/maestro install again after updating Maestro to refresh generated guidance and skills. Project-specific instructions remain under your control and can complement Maestro's generated block.

Skills are installed as symlinks into .agents/skills and .claude/skills so they follow the package. Where symlinks are unavailable — Windows without Developer Mode, for example — Maestro falls back to a directory junction, and to a copy where junctions are unavailable too. It reports which one it used.

A copy cannot follow package updates, so Maestro warns when it has to make one and marks the directory with a .maestro-copy file. That marker is what lets a later vendor/bin/maestro install replace the copy with a current one, so run it after every composer update. Directories without the marker are yours: Maestro never touches them. Delete the marker to take a copy out of Maestro's hands.

Documentation search

search-docs selects documentation versions from the packages installed in the application. Symfony documentation is searched by version, and supported ecosystem documentation is searched from its official source repository. Set GITHUB_TOKEN to increase GitHub API limits; credentials are never returned by the tool.

Development

composer install
composer test
composer analyse
composer cs
composer rector
composer check

composer cs reports coding-standard violations; composer cs-fix applies them. composer check runs the whole set.

The integration suite builds a disposable Symfony fixture, SQLite database, logs, and profiler records on every run. No pre-generated runtime state is required.

See CONTRIBUTING.md for the contribution workflow and SECURITY.md for private vulnerability reporting.

License

Maestro is open-source software licensed under the MIT license.

janvdb2000 / maestro

Maintainers

Package info

Statistics

Security