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:

composer require --dev janvdb2000/maestro
vendor/bin/maestro init
vendor/bin/maestro discover

maestro init creates the local AI Mate configuration. maestro discover enables installed extensions, materializes their agent instructions, and installs their skills for supported coding agents.

maestro is a thin wrapper around AI Mate: it adds the short tool commands below and passes everything else straight through, so maestro init and mate init are the same command. This README uses maestro throughout.

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 generated MCP server uses the following command:

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

If your project runs inside Docker or another development environment, replace php with the command that executes PHP in that environment. 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.

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 discover again after updating Maestro to refresh generated guidance and skills. Project-specific instructions remain under your control and can complement Maestro's generated block.

On Windows, skill installation requires symlink support. Enable Developer Mode, run the agent inside WSL, or install the skills manually if the upstream AI Mate symlink operation is unavailable.

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 rector
composer check

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