Skip to content
Back to search

symfony-upgrade-scout

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jejuolledev--symfony-upgrade-scout/badge.svg)](/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
  1. # Upgrade Scout — what blocks your next Symfony upgrade?
  2. 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:
  3. | MCP tool | Answers | Source |
  4. |---|---|---|
  5. | `project_summary` | Which Symfony, which PHP constraint, which direct dependencies? | `composer.json`, `composer.lock` |
  6. | `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 |
  7. | `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 |
  8. | `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 |
  9. 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.
  10. 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.
  11. ## Try it in five minutes
  12. Requirements: PHP 8.4+, Composer.
  13. ```bash
  14. git clone https://github.com/jejuolledev/symfony-upgrade-scout && cd symfony-upgrade-scout
  15. (cd app && composer install)
  16. (cd demo-legacy && composer install) # a small Symfony 7.4 app with real upgrade problems
  17. php app/bin/console scout:plan demo-legacy --offline # no LLM; still reads Packagist and GitHub
  18. cat demo-legacy/UPGRADE_PLAN.md
  19. ```
  20. What you get for the demo app (real output, real Packagist data):
  21. - PHP: Symfony 8.0 needs PHP 8.4, the project still allows `>=8.2`.
  22. - **Blocker**: `craue/formflow-bundle` 3.7.0 — no stable release allows 8.0 yet.
  23. - `doctrine/annotations` is flagged as abandoned on Packagist.
  24. - **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.
  25. - **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.
  26. - The matching bullets of `UPGRADE-8.0.md`.
  27. ### With the agent
  28. ```bash
  29. export OPENAI_API_KEY=... # an OpenAI key; --model picks the model
  30. php app/bin/console scout:plan demo-legacy --target=8.0 --model=gpt-4.1-mini
  31. ```
  32. 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.
  33. ### In Claude Desktop / Cursor
  34. ```json
  35. {
  36. "mcpServers": {
  37. "upgrade-scout": {
  38. "command": "php",
  39. "args": ["/absolute/path/to/upgrade-scout/app/bin/upgrade-scout-mcp"]
  40. }
  41. }
  42. }
  43. ```
  44. Then ask: *"Use upgrade-scout on /path/to/my-app: what blocks Symfony 8.0?"*
  45. ## It fails loudly
  46. An upgrade tool that says "all good" by mistake is worse than none, so:
  47. - 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;
  48. - the PHP check flags constraints that still accept older PHP (`>=8.2`) **and** ones that reject the required version (`8.2.*`);
  49. - wrong paths, wrong targets (`abc`) and unpublished UPGRADE files come back as readable `isError` tool results, so the client — and the model — know why.
  50. ## Safety
  51. `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.
  52. ## How it is built
  53. ```
  54. app/
  55. bin/upgrade-scout-mcp stdio MCP server (mcp/sdk Server::builder, tools from #[McpTool] attributes)
  56. src/Mcp/ScoutTools.php the four tools, with honest MCP annotations (`deprecations` is not read-only)
  57. src/Scout/ProjectInspector.php the work: deprecation log parsing, Packagist + semver, UPGRADE file parsing
  58. src/Command/PlanCommand.php scout:plan — MCP client for the facts, Symfony AI agent over MCP for the plan
  59. src/Scout/PlanWriter.php deterministic plan (no model), also the fallback
  60. src/Scout/PlanChecker.php rejects plans that invent packages, versions or files
  61. prompts/planner.md the agent's instructions
  62. tests/ PHPUnit, fully offline (fixtures for Packagist and UPGRADE notes)
  63. demo-legacy/ Symfony 7.4 app with a blocker, two stale bundles and three deprecations
  64. ```
  65. ```bash
  66. cd app && php vendor/bin/phpunit
  67. ```
  68. 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.
  69. ## What Symfony AI and the PHP MCP SDK unlocked
  70. - 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.
  71. - 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.
  72. ## Limits
  73. - Runtime-only deprecations (triggered by a request, not by booting the container) are not in that log.
  74. - 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.
  75. - Some MCP clients send `target` as a number; pass it as a string (`"8.0"`).
  76. - Readiness looks at direct dependencies and their `symfony/*` requirements; it does not run the full Composer solver.
  77. - 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).
  78. ## AI use
  79. The code was written with an AI coding assistant (Claude) and checked by running it against the demo project and the test suite.
  80. MIT License.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.