Boost Laravel Package

Getting Started

Laravel Boost is two things in one package: an MCP server (php artisan boost:mcp) that exposes Laravel-aware tools to your AI agent, and an installer that writes the files agents need (guidelines, skills, and per-editor MCP config). You install it as a dev dependency and let it wire up your editor.

composer require laravel/boost --dev
php artisan boost:install

boost:install asks which agents/editors you use and then writes:

• .ai/guidelines/* — Laravel-specific rules and conventions the agent reads
• .ai/skills/* — task-oriented playbooks (Livewire, testing, best practices index, etc.)
• Editor-specific MCP config files (.cursor/mcp.json, .mcp.json, .vscode/mcp.json, opencode.jsonc, and similar) pointing at php artisan boost:mcp
• Optionally a published config file you can tweak (agent list, DB connections, browser-log levels, executable paths)

Where to look first, in order:

1. .ai/guidelines/ — this is the "context" half of the package. Read it; it tells you what your agent will assume.
2. Your editor's MCP settings file — confirm the laravel-boost server is registered and connects.
3. The tool list in your editor's MCP panel — you should see tools like search-docs, database-schema, database-query, tinker, list-routes, read-log-entries, browser-logs, record-rule.

Then restart the editor (config is only read at startup) and verify with a trivial prompt.

First real use case: after install, ask your agent something that forces it to use the tools rather than guess:

"Use the schema tool to describe the orders table, then add a PATCH /orders/{order}/cancel endpoint with a form request, policy check, and a feature test. Follow the project's guidelines."

A correctly installed Boost setup will call database-schema before writing the migration/model, call search-docs before guessing at framework APIs, and produce code that matches your Laravel version. If the agent answers from memory with no tool calls, the MCP server isn't connected — fix that before going further.

Implementation Patterns

Let the tool descriptions do the routing. Boost's value is that you stop writing "please check the docs" into prompts. Instead, phrase requests so a tool is the obvious move: "what does the current Laravel version say about RateLimiter in jobs?", "what columns does subscriptions have?", "why did /checkout 500 in the last request?", "list my registered routes matching admin/*".

Debug loop pattern (highest day-to-day payoff). When a bug comes in, drive the agent through: read-log-entries (or the last-error tool) → browser-logs if it's a frontend/JS issue → tinker to reproduce the query or model behavior → patch → tinker again to confirm. This keeps the agent grounded in actual runtime state instead of inventing plausible tracebacks.

Keep generated vs. hand-written files separate. boost:update regenerates .ai/guidelines and refreshes skills; treat those as build output. Your own conventions go through the record-rule MCP tool (it writes a committed project rules file) or your own file the updater won't clobber. That way boost:update is safe to run on every dependency bump.

Vendor skills and guidelines. Since 2.5, boost:update discovers third-party guidelines/skills shipped by installed packages by default (vendor/.../resources/boost/... style). Precedence matters: a vendor skill with the same name as a built-in one is intended to override it. That's the extension point for package authors — ship a skill in your package, and every consuming app's agent gets your conventions for free. If a vendor guideline fails to render it is skipped rather than crashing the update, so if a package's guidance "doesn't show up," check its template before assuming Boost ignored it.

Adding remote/extra skills. Use the add-skill command with a path or URL. Remote skills are sanitized (Blade templates are rejected), and there's an audit gate — expect it to refuse paths that resolve outside the skills directory. A SKILL.md at the repository root is deliberately ignored so a bad path can't nuke .ai/skills.

Team setup. Commit the parts that encode decisions: your rules file, .ai/skills, and the editor config. If your team disagrees about committing regenerated guidelines, add them to .gitignore and make boost:update part of the post-composer update ritual, or add it as a composer script (Boost skips its interactive package-discovery prompt when run from a composer script). Add a CI check that re-running install/update produces no diff, so nobody's agent is working from stale context.

One install, many agents. Install once, select every editor in use, and boost:update will refresh each config. This is the cheapest way to keep a mixed Cursor/Claude Code/Copilot/PhpStorm team on identical context.

Smoke test outside the editor. php artisan boost:mcp --help and running the server directly is the fastest way to confirm the process boots and the tool list is sane before blaming your editor's MCP client.

Gotchas and Tips

The database tool is read-only — but treat it as a guardrail, not a security boundary. Queries run under an enforced read-only transaction (as of 2.6), and several point releases patched bypasses via CTE bodies, EXPLAIN ANALYZE, and INTO. Point it at a local or dedicated read-only connection, and never at production credentials. Configure the connections it may touch explicitly rather than letting it enumerate everything.

Huge schemas will eat your context window. Dumping every table's columns into the agent is the most common cause of "Boost made my agent worse." Scope the connections, and prefer prompts that name the tables you care about.

boost:update is not idempotent with hand edits. Anything you typed directly into generated guideline files will be lost. Move it to record-rule or a separate file first.

Table prefixes and schema-qualified names have historically broken generated SQL — prefixes corrupting ORDER BY ... DESC, foreign-key index examples that didn't actually create an index, MySQL table types failing under ANSI_QUOTES, and prefix leaks in table-detail reads have all been fixed in recent point releases. If you're on an older pin and your agent produces subtly wrong SQL, upgrade before debugging your own code.

Blank config values are treated as unset for executable paths — so an empty "php" => "" won't shadow the default. Also note Boost normalizes newlines in rule files; multi-byte UTF-8 corruption in that path was a real bug fixed in 2.5.5. If your rules file has non-ASCII text and renders mangled, that's the culprit.

Editor config formats are a minefield. JSON vs JSONC vs TOML, trailing-comma handling, preferring opencode.jsonc over .json when both exist, and detecting agents from shared directories (Boost has had to explicitly stop inferring Antigravity from the .agents directory it creates for others). If you hand-maintain an MCP block, re-run install on a clean checkout and diff rather than letting it merge blindly.

Signaled test processes have caused false negatives in test-enforcement detection — if Boost insists your tests didn't run, check for a killed process rather than a failing suite.

Browser logs are configurable by level; if Playwright/Chrome tooling produces noise or nothing, adjust the level in config before assuming the tool is broken.

Version-pin across the team. This package ships multiple releases per month with behavior changes in boost:update (e.g., third-party guidelines became default in 2.5) — read UPGRADE.md before bumping the major, and commit your lock file so every agent in the office sees the same guidelines.