Back to search
symfony-upgrade-scout
MCP serverGitHub
Upgrade Scout — what blocks your next Symfony upgrade? PHP MCP server + Symfony AI agent
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/jejuolledev--symfony-upgrade-scout)HTML
<a href="/listings/jejuolledev--symfony-upgrade-scout"><img src="/api/listings/jejuolledev--symfony-upgrade-scout/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 111 lines
- # Upgrade Scout — what blocks your next Symfony upgrade?
- An MCP server, written with the official PHP MCP SDK, that answers the questions you ask before a major Symfony upgrade, from the project itself:
- | MCP tool | Answers | Source |
- |---|---|---|
- | `project_summary` | Which Symfony, which PHP constraint, which direct dependencies? | `composer.json`, `composer.lock` |
- | `deprecations` | What will break, and in **which file of mine**? | the container's own deprecation log (`var/cache/dev/*Deprecations.log`), after a fresh `cache:clear` + `cache:warmup` of the project |
- | `dependency_readiness` | Which third-party bundle must be bumped, **to which exact release**, and which ones have no release for the target at all? Does my PHP constraint allow what the target needs? | Packagist metadata + Composer's semver |
- | `upgrade_notes` | What does the official `UPGRADE-8.0.md` (or `UPGRADE-8.1.md` for 8.1) say about exactly these deprecations? | `symfony/symfony` UPGRADE file |
- On top of it, `bin/console scout:plan` runs a **Symfony AI agent that reaches those tools through MCP** (`symfony/ai-mcp-tool`) and writes an `UPGRADE_PLAN.md`. Every package, version and file the agent names is checked against the tool results; if it names something the tools never returned, its plan is rejected and the tool-only plan is written instead.
- The same server works in Claude Desktop, Cursor or any MCP client, so "can I upgrade to 8.0?" becomes a question your editor's assistant can answer with facts instead of guesses.
- ## Try it in five minutes
- Requirements: PHP 8.4+, Composer.
- ```bash
- git clone https://github.com/jejuolledev/symfony-upgrade-scout && cd symfony-upgrade-scout
- (cd app && composer install)
- (cd demo-legacy && composer install) # a small Symfony 7.4 app with real upgrade problems
- php app/bin/console scout:plan demo-legacy --offline # no LLM; still reads Packagist and GitHub
- cat demo-legacy/UPGRADE_PLAN.md
- ```
- What you get for the demo app (real output, real Packagist data):
- - PHP: Symfony 8.0 needs PHP 8.4, the project still allows `>=8.2`.
- - **Blocker**: `craue/formflow-bundle` 3.7.0 — no stable release allows 8.0 yet.
- - `doctrine/annotations` is flagged as abandoned on Packagist.
- - **Bump first**: `knplabs/knp-paginator-bundle` v6.6.1 → v6.10.0 and `stof/doctrine-extensions-bundle` v1.12.0 → v1.15.0, with the `composer require` line.
- - **Deprecations**, each pointed at a file: `src/Report/LazyReport.php` (LazyGhostTrait), `config/legacy_routes.xml` (XML routing), and one that comes from `vendor/knplabs/knp-paginator-bundle` itself — which the plan says is fixed by the bump, not by you.
- - The matching bullets of `UPGRADE-8.0.md`.
- ### With the agent
- ```bash
- export OPENAI_API_KEY=... # an OpenAI key; --model picks the model
- php app/bin/console scout:plan demo-legacy --target=8.0 --model=gpt-4.1-mini
- ```
- The agent (`Symfony\AI\Agent\Agent`) gets the MCP server as its toolbox (`McpToolbox` + `ClientToolset` over stdio), decides which tools to call and writes the plan in plain words. `PlanChecker` then refuses any plan that mentions a package, version or project file absent from the tool results.
- ### In Claude Desktop / Cursor
- ```json
- {
- "mcpServers": {
- "upgrade-scout": {
- "command": "php",
- "args": ["/absolute/path/to/upgrade-scout/app/bin/upgrade-scout-mcp"]
- }
- }
- }
- ```
- Then ask: *"Use upgrade-scout on /path/to/my-app: what blocks Symfony 8.0?"*
- ## It fails loudly
- An upgrade tool that says "all good" by mistake is worse than none, so:
- - if the project does not boot (`cache:clear` / `cache:warmup` exit non-zero, or there is no `bin/console`), `deprecations` returns an MCP tool error with the last lines of the output, never an empty list; stale logs are deleted first;
- - the PHP check flags constraints that still accept older PHP (`>=8.2`) **and** ones that reject the required version (`8.2.*`);
- - wrong paths, wrong targets (`abc`) and unpublished UPGRADE files come back as readable `isError` tool results, so the client — and the model — know why.
- ## Safety
- `deprecations` boots the target project: it runs that project's `bin/console`, i.e. its code, and clears its dev cache. Its MCP annotations say so (`readOnlyHint: false`), so clients ask before calling it. Only point it at projects you trust, and set `SCOUT_ALLOWED_ROOT=/path/to/your/projects` to refuse anything outside that folder.
- ## How it is built
- ```
- app/
- bin/upgrade-scout-mcp stdio MCP server (mcp/sdk Server::builder, tools from #[McpTool] attributes)
- src/Mcp/ScoutTools.php the four tools, with honest MCP annotations (`deprecations` is not read-only)
- src/Scout/ProjectInspector.php the work: deprecation log parsing, Packagist + semver, UPGRADE file parsing
- src/Command/PlanCommand.php scout:plan — MCP client for the facts, Symfony AI agent over MCP for the plan
- src/Scout/PlanWriter.php deterministic plan (no model), also the fallback
- src/Scout/PlanChecker.php rejects plans that invent packages, versions or files
- prompts/planner.md the agent's instructions
- tests/ PHPUnit, fully offline (fixtures for Packagist and UPGRADE notes)
- demo-legacy/ Symfony 7.4 app with a blocker, two stale bundles and three deprecations
- ```
- ```bash
- cd app && php vendor/bin/phpunit
- ```
- The tests (14) run without network or API key. They cover the readiness logic, the PHP check, a project that fails to boot, readable MCP errors, and the agent path. `AgentOverMcpTest` starts the real MCP server as a subprocess, attaches it to a Symfony AI `Agent` through `McpToolbox`, and scripts only the model's replies (`MockPlatformFactory`), so the whole agent → MCP client → MCP server → Packagist-fixture path is exercised.
- ## What Symfony AI and the PHP MCP SDK unlocked
- - Before: "can we upgrade?" meant running `composer why-not`, reading a deprecation log nobody opens, and scrolling a 900-line UPGRADE file. An LLM could only guess, from memory, which bundle version supports 8.0.
- - Now: the facts are four MCP tools written in plain PHP with attributes, usable by any MCP client, and a Symfony AI agent consumes the very same server with three lines (`ClientToolset`, `McpToolbox`, `Agent`). The model chooses the questions and writes the prose; Composer, Packagist and the container answer them.
- ## Limits
- - Runtime-only deprecations (triggered by a request, not by booting the container) are not in that log.
- - The agent path is tested with a scripted model (`MockPlatformFactory`); results from a live model depend on that model, which is why `PlanChecker` gates its output.
- - Some MCP clients send `target` as a number; pass it as a string (`"8.0"`).
- - Readiness looks at direct dependencies and their `symfony/*` requirements; it does not run the full Composer solver.
- - Built on pre-releases: `symfony/ai-*` 1.0.0-BETA1 and `mcp/sdk` 0.9 (the MCP tool bridge does not accept `mcp/sdk` 0.10 yet).
- ## AI use
- The code was written with an AI coding assistant (Claude) and checked by running it against the demo project and the test suite.
- MIT License.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.