Download the PHP package janvdb2000/maestro without Composer

Maestro

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:

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:

• 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

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:

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:

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:

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:

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:

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 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 SECURITY.md for private vulnerability reporting.

License

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