winter/wn-laravelboost-plugin
A Winter CMS plugin that integrates Laravel Boost, giving AI coding assistants project-aware context and tooling for faster, more accurate Winter and Laravel development.
Prerequisites. A Winter CMS 1.2+ project, PHP 8.1+, Composer, and an MCP-capable client — Claude Code, Cursor, VS Code/GitHub Copilot, JetBrains AI, or Codex. The plugin is a thin integration layer over Laravel Boost, so the client is what actually consumes it; the plugin's job is to make Boost Winter-aware.
Install into a local/dev install only:
composer require winter/wn-laravelboost-plugin
php artisan winter:up
php artisan plugin:list # confirm Winter.LaravelBoost is enabled
Then run Boost's installer, which detects your editor and writes the MCP server definition plus a guidelines file into the project root:
php artisan boost:install
Restart your editor/agent so it picks up the new MCP server. You should see Boost's tools listed in the agent (application info, database schema, route list, log reader, tinker, docs search — plus whatever Winter-specific tools/guidelines the plugin registers).
Where to look first, in this order:
plugins/winter/laravelboost/ — Plugin.php, config/, and any guidelines/ or tools/ directory. This is where Winter's mappings live (custom tools, extra guideline text, doc sources)..mcp.json, .cursor/mcp.json, or .vscode/mcp.json) and the guidelines file (CLAUDE.md, AGENTS.md, or .cursor/rules/) — confirm the Winter-specific rules actually landed there.php artisan boost:mcp run manually once — if it starts and prints JSON-RPC on stdio without errors, the client-side problem is config, not the plugin.First use case. Open the project in your agent and ask something that exercises the whole chain: "Read the Winter guidelines, then list the enabled plugins and show me the database schema for the Blog plugin's posts table — don't propose any October CMS namespaces." A working install returns real table columns from the schema tool and reasons about Winter\Storm\Database\Model rather than Illuminate\Database\Eloquent\Model. That single prompt validates install, tool wiring, and guideline injection at once.
Daily loop: schema → plan → generate → verify. The productive pattern isn't "ask for a plugin." It's:
php artisan winter:up yourself (or let the agent run it if it has a shell tool).Winter-shaped scaffolding. Prompt explicitly for Winter conventions so the agent doesn't emit vanilla Laravel: Plugin.php with registerComponents/registerNavigation, models extending Winter\Storm\Database\Model with $formFields / $jsonable / $belongsTo, backend controllers extending Backend\Classes\Controller with $implement = ['Backend.Behaviors.FormController', ...], Twig views under partials/, lang files under lang/en/lang.php. The guidelines file is the cheapest place to encode this permanently — edit it once, every future session benefits.
Model/relationship work. This is the highest-value day-to-day use. Point the agent at a Winter model and let it use the schema tool to map foreign keys before writing relationship methods. It reliably catches the Winter-specific footguns (soft deletes via SoftDelete trait, $dates vs $casts, deferred binding) that generic Laravel advice gets wrong.
Debugging sessions. Ask the agent to tail storage/logs/laravel.log through the log tool, correlate with the route list (backend/* routes included), and use tinker for read-only probes against Winter models. This replaces most manual log-copy-paste. Keep tinker prompts read-only on any shared dev database.
Upgrades and audits. "Show me every place a plugin uses a deprecated Winter API" works well because the agent can grep the filesystem and cross-check against Winter docs via the docs-search tool. The same loop finds unused plugin dependencies before a composer update.
Team distribution. Commit the generated MCP config and guidelines file. The MCP server entry is per-developer only where paths differ (Docker/Sail). Guidelines are the shared artifact — treat them like coding standards and review changes to them in PRs.
CI-adjacent use. Don't wire boost:mcp into CI; it's an interactive stdio server. Do keep the guidelines file as the source of truth for any other AI tooling you run, so humans and agents get the same Winter rules.
Namespace drift is the number-one failure mode. Without the Winter guidelines loaded, agents confidently emit October\Rain\* or plain Illuminate\* for models and controllers. If output looks like a stock Laravel app, the guidelines file didn't get written or isn't being read — check it before blaming the plugin.
Boost assumes a stock Laravel skeleton. app/Models, routes/web.php, bootstrap/app.php don't exist in Winter. Some built-in tools return thin or empty results for those paths. Rely on the plugin's added context and the schema tool instead of assuming a "no results" answer means nothing exists.
Guard it to non-production. MCP exposes a shell-capable tinker tool and a full schema dump. Enable the plugin only in local/dev (conditionally in Plugin::boot() on App::environment()), and never expose the stdio server over a network socket. Add .mcp.json to your deployment exclusions if it contains environment-specific paths.
Context bloat on large installs. A Winter site with a dozen plugins produces a big schema dump. Scope prompts ("just the cms_pages and Blog tables") rather than asking for the whole schema, or the agent burns its window on table definitions and starts truncating.
Composer resolution conflicts. Boost pulls in laravel/mcp and friends with its own Laravel version constraints. Winter's bundled Laravel version may lag. If resolution fails, try composer require winter/wn-laravelboost-plugin -W and pin Boost to a compatible major. Pin the plugin version in composer.json — it's early-stage (5 stars, minimal dependents) and both it and Boost are moving fast; guideline formats have churned between Boost releases.
Stale tool output after changes. Winter caches plugin metadata and settings. After enabling/disabling a plugin or editing config, run php artisan cache:clear and php artisan config:clear, then restart the MCP client. Agents cache the tool list per session, so a config edit without a client restart looks like it did nothing.
Docker/Sail/Valet. The MCP server command must execute inside the container. A local php artisan boost:mcp on a Sail project starts fine but sees an empty/wrong filesystem. Set the command to docker compose exec -T app php artisan boost:mcp (or the Sail equivalent) in the MCP config.
Extension points worth knowing. Register additional tools and Winter-specific doc sources from the plugin's service provider rather than forking — and put project-specific conventions (your team's plugin structure, naming, test layout) in the guidelines file, not in prompts you retype daily. That's the difference between using this as a novelty and as infrastructure.
Expect gaps. With a single maintainer, zero dependents, and a release cadence measured in weeks, treat breakage after a Winter or Boost upgrade as normal. Read the plugin's changelog before upgrading either, and keep a known-good composer.lock committed.
How can I help you explore Laravel packages today?