Laravel Boost Copilot Cli Laravel Package

Getting Started

What this package is. A custom agent definition (plus MCP wiring) that teaches GitHub Copilot CLI how to talk to a Laravel app through Laravel Boost's MCP server. Boost is the thing doing the actual work — exposing routes, models, DB schema, config, logs, tinker, and docs search as tools. This package is the glue that hands those tools to Copilot's terminal agent with Laravel-aware instructions.

Prerequisites

• PHP 8.2+, Laravel 11/12
• laravel/boost installed and working (php artisan boost:mcp should start and wait on stdio)
• Node 18+ and the Copilot CLI: npm i -g @github/copilot, authenticated with a Copilot-enabled account
• A local database and APP_ENV=local — see Gotchas

Install

composer require revolution/laravel-boost-copilot-cli --dev

It is a dev-only tool; keep it out of production images. Then run whatever publish/install step the README specifies — either a vendor:publish tag or a small artisan command. You are looking for two artifacts to appear:

1. An agent file, typically under .github/agents/ (e.g. laravel-boost.agent.md)
2. An MCP server entry pointing at php artisan boost:mcp, written to .github/mcp.json as of 2.3.0 (project-scoped, not the user-level ~/.copilot/mcp-config.json it used previously)

Where to look first

• README.md — install command and any required Copilot CLI version
• vendor/revolution/laravel-boost-copilot-cli/ — the agent markdown is the whole product; read it, it is your extension point
• .github/agents/*.agent.md — the published copy you will actually edit
• .github/mcp.json — the project-level MCP config the package now writes; confirm Boost is registered and points at the right PHP binary
• ~/.copilot/mcp-config.json — only if you are still on 2.2.x or deliberately kept a user-level registration

First use case. Open a terminal in the project root, run copilot, and ask something that requires cross-referencing state:

"GET /api/orders is returning a 500. Use Boost to read the last error and the log entries, find the matching route and controller, and tell me the failing line before changing anything."

That exercises the three highest-value tools — last-error, read-log-entries, list-routes — in one shot. If it works, the wiring is correct. If the agent starts grepping the filesystem instead, Boost is not connected — check which of the two config locations Copilot actually loaded.

Implementation Patterns

Commit the agent file and the MCP config. As of 2.3.0 the MCP entry lives at .github/mcp.json, next to the agent markdown. Treat both as source, not local artifacts: everyone on the team gets identical tool policy, identical server registration, and changes go through review like any other code. This is the biggest practical win of the new default — the wiring is now reproducible from a clone instead of being re-typed per machine.

Layer instructions deliberately. Two files, two jobs:

• AGENTS.md (repo root) — house conventions: Pest over PHPUnit, Pint before commit, naming, where business logic lives. Applies to every agent, including Copilot's default.
• The Boost agent file — tool policy and Laravel-specific workflow ("read schema before writing a migration", "never run migrate:fresh without asking").

Read-before-write prompts. The highest-leverage habit with Boost is forcing a discovery phase. Ask for application-info, database-schema, and list-routes output first, then the change. It costs one round trip and eliminates most hallucinated column names and route paths.

Pair with the test runner. A loop that works well:

copilot -p "Use boost to find why OrderTest::test_checkout_total fails, fix it, then run php artisan test --filter=OrderTest"

The agent uses last-error after the failure rather than guessing from stack-trace text it cannot see.

Headless triage. Copilot CLI supports non-interactive -p runs with tool allowlists. A cheap nightly job can pull open issues, ask the agent to reproduce against a seeded local DB, and post findings. Budget for rate limits; this is a convenience, not a CI gate.

Scope the destructive tools. Boost exposes tinker and database-query, which execute arbitrary code against your DB. In a shared repo, either drop them from the agent's tool list or add an explicit "confirm before executing SQL" instruction. The agent file is the only place this is enforceable.

Monorepos. One .github/agents/ + .github/mcp.json pair per Laravel app directory, each launching boost:mcp with the correct working directory. Do not try to serve two apps from one MCP process.

Gotchas and Tips

Upgrading from 2.2.x: your config moved. 2.3.0 changes the default MCP config path to .github/mcp.json. An existing install will still have the Boost entry in the old user-level ~/.copilot/mcp-config.json, so after upgrading you can end up with the server registered in two places — duplicate tools, or the agent picking the stale one. Delete the old entry, re-run the install/publish step, and commit .github/mcp.json.

A committed config means committed paths. .github/mcp.json holding an absolute PHP path or a Sail-only command will break teammates on a different setup. Prefer the most portable invocation you can (./vendor/bin/sail artisan boost:mcp for container-first teams, plain php artisan boost:mcp otherwise), and if the team is split, commit a template and let each dev keep a local override rather than baking one machine's paths into the repo.

This is a 5-star, 0-dependent package with a very recent release. Pin the exact version in composer.json and expect the agent markdown to drift as Copilot CLI's agent frontmatter evolves. If a CLI upgrade breaks the agent, copy the markdown into your repo and maintain it there — the file is small and self-contained.

Working directory is everything. Boost's MCP entry launches php artisan boost:mcp; if Copilot spawns it from a subdirectory, artisan will not find the app. Always start copilot from the project root, and verify .github/mcp.json uses an absolute path or ./artisan.

Sail / Docker is the #1 setup failure. The stdio server runs on the host by default while your app runs in a container — right artisan, wrong PHP, wrong DB host. Point the MCP command at ./vendor/bin/sail artisan boost:mcp (or docker compose exec -T) and make sure the container is up before you start the agent.

Tool approvals block non-interactive runs. Copilot CLI prompts per tool unless you allowlist them. A -p run against an unapproved tool does not fail loudly — it just refuses. Debug by running the same prompt interactively first.

Never point this at production. tinker and database-query are real execution against whatever DB_* resolves to. Guard with APP_ENV=local in the agent instructions and keep a disposable SQLite or seeded MySQL copy for agent work.

Stale config and logs. The agent reports what Boost sees, not what is on disk right now. php artisan config:clear before blaming the agent for wrong values. Log reading is limited to storage/logs/laravel.log on the default channel — rotated or compressed files and non-default channels (LOG_CHANNEL=stderr, daily files) are invisible.

search-docs needs network. Offline or air-gapped, it returns empty rather than erroring. If the agent suddenly stops citing Laravel docs, check connectivity before suspecting the package.

Two MCP servers, overlapping tools. If you also run Boost through Cursor or Claude Code, the same tool names can appear twice and the agent may pick the wrong one. Keep one Boost registration per client — and with 2.3.0, remember the project-level .github/mcp.json plus a lingering global entry counts as two.

Extension points. In rough order of usefulness: edit the agent markdown (tool list, instructions, examples), add AGENTS.md conventions, adjust .github/mcp.json to register additional MCP servers alongside Boost (a browser-automation server pairs well with Boost's browser-logs), and finally fork the package if the install flow itself gets in the way — there is very little code to fork.