Boost Configuration (boost.json)

Purpose and Scope

This page covers two configuration files used in the development of this package:

1. boost.json — The project-level configuration file for the Laravel Boost framework. It declares which agents, feature flags, packages, and AI skills are active. This file lives in the project root and is version-controlled.
2. .github/mcp-config.json — A development-only MCP server definition used when running the package locally via orchestra/testbench. It configures GitHub Copilot to connect to the local testbench-based boost:mcp server.

For the system-wide MCP configuration file (mcp.json) written by boost:install, see page 7.3. For package-level configuration (composer.json), see page 7.1.

Sources: boost.json1-17 .github/mcp-config.json1-14

---

boost.json — File Location and Purpose

boost.json resides in the root directory of the Laravel project. It is read by the laravel/boost framework to determine which agents and features are active. Unlike the system-wide mcp.json written by boost:install, boost.json is project-specific and version-controlled.

The properties in boost.json influence runtime behavior: for example, guidelines and skills entries map to the guidelinesPath() and skillsPath() methods on PhpStormCopilot, which are called by the laravel/boost install commands to determine where to write generated files. The mcp, sail, herd_mcp, and nightwatch_mcp flags control which MCP-related install steps are executed.

Diagram: boost.json Properties → PhpStormCopilot Methods

Sources: boost.json1-17 src/PhpStormCopilot.php86-97

---

boost.json — Configuration Schema

Root Structure

boost.json is a single JSON object. The following table documents every property present in this repository's copy of the file:

Property	Type	Value in this repo	Description
agents	string[]	["copilot-cli"]	Agent identifiers to register
guidelines	boolean	true	Enable AI guideline file generation
mcp	boolean	true	Enable MCP server installation step
herd_mcp	boolean	false	Enable Laravel Herd MCP integration
nightwatch_mcp	boolean	false	Enable Nightwatch MCP integration
packages	string[]	["revolution/laravel-boost-copilot-cli"]	Related Boost package identifiers
sail	boolean	false	Enable Laravel Sail command transformation
skills	string[]	["pest-testing"]	AI skill module names

Sources: boost.json1-17

The agents Property

The agents array lists agent identifiers, each corresponding to an agent's name() method return value. In PhpStormCopilot, name() returns 'phpstorm-copilot' src/PhpStormCopilot.php19-22 In this repository, the agent listed is "copilot-cli", which corresponds to the revolution/laravel-boost-copilot-cli companion package. PhpStormCopilot is registered automatically by PhpStormCopilotServiceProvider via Laravel's package auto-discovery, not by an entry in this array.

Diagram: Agent Identifier → Class Registration

Sources: boost.json2-4 src/PhpStormCopilot.php19-22

---

The guidelines Property

Controls whether AI guideline files are generated. When true, the laravel/boost install command writes a guideline file to the path returned by guidelinesPath() on the active agent. For PhpStormCopilot, the default path is .github/instructions/laravel-boost.instructions.md, configurable via config('boost.agents.phpstorm_copilot.guidelines_path'). See page 3.3 for more on AI guidelines.

Sources: boost.json5 src/PhpStormCopilot.php86-89

---

The mcp Property

When true, the MCP server installation step is executed during boost:install. This causes PhpStormCopilot::installFileMcp() to run, writing (or updating) the system-wide mcp.json with the current project's boost:mcp command. See page 3.2 for MCP architecture details and page 4.3 for the installFileMcp dispatch logic.

Sources: boost.json7 src/PhpStormCopilot.php119-132

---

The packages Property

Lists companion Composer package names that are part of this Boost setup. In this repository, "revolution/laravel-boost-copilot-cli" is listed, which is a separate package providing the copilot-cli agent. These identifiers allow the framework to coordinate between installed Boost packages.

Sources: boost.json9-11

---

The skills Property

Lists AI skill module names. Skills are installed into the directory returned by skillsPath() on the agent. For PhpStormCopilot, the default path is .github/skills, configurable via config('boost.agents.phpstorm_copilot.skills_path'). The "pest-testing" skill provides GitHub Copilot with Pest PHP testing conventions. See page 3.3 for more on AI skills.

Sources: boost.json13-15 src/PhpStormCopilot.php93-97

---

Boolean Feature Flags

Flag	Value in this repo	Description
herd_mcp	false	Enable Laravel Herd MCP server integration
nightwatch_mcp	false	Enable Nightwatch MCP server integration
sail	false	Enable Sail command transformation via transformSailCommand()

When sail is true, PhpStormCopilot::transformSailCommand() wraps the detected ./vendor/bin/sail command in a bash -c wrapper for correct working directory handling. See page 5.4 for Sail integration details.

Sources: boost.json6-12 src/PhpStormCopilot.php141-162

---

boost.json — Configuration Flow

Diagram: Feature Flags → Install Actions

Sources: boost.json1-17 src/PhpStormCopilot.php86-97 src/PhpStormCopilot.php119-132

---

boost.json — The Repository's Configuration

The boost.json at the root of this repository boost.json1-17 is the configuration used when developing and testing the package itself. Its properties are:

• "agents": ["copilot-cli"] — registers the companion CLI agent during local development
• "guidelines": true — AI guideline files are generated
• "mcp": true — MCP installation step is active
• "herd_mcp": false, "nightwatch_mcp": false — Herd and Nightwatch MCP integrations are not used
• "sail": false — Sail is not used in this development environment
• "packages": ["revolution/laravel-boost-copilot-cli"] — declares the companion CLI package
• "skills": ["pest-testing"] — the Pest testing skill is active

Sources: boost.json1-17

---

.github/mcp-config.json — Development MCP Configuration

.github/mcp-config.json .github/mcp-config.json1-14 is a development-only file used by contributors when working on this package locally. It tells GitHub Copilot (in the IDE used by the package developer) how to reach the boost:mcp server running through orchestra/testbench, without requiring a full Laravel application.

Structure

Field	Value	Description
mcpServers	object	Top-level key (different from production mcp.json which uses servers)
mcpServers.laravel-boost.type	"local"	Marks this as a local subprocess MCP server
mcpServers.laravel-boost.command	"./vendor/bin/testbench"	Runs testbench instead of php artisan
mcpServers.laravel-boost.args	["boost:mcp"]	Passes the boost:mcp command to testbench
mcpServers.laravel-boost.tools	["*"]	Enables all available MCP tools

Contrast with Production mcp.json

Aspect	.github/mcp-config.json	System mcp.json (written by installFileMcp)
Top-level key	mcpServers	servers (from mcpConfigKey())
Command	./vendor/bin/testbench (relative)	Absolute path to php binary
Requires boost:install	No	Yes
Written by	Committed to repo manually	PhpStormCopilot::installFileMcp()
Scope	Package development only	End-user project

Note that installFileMcp() includes a guard that throws an exception if it detects TESTBENCH_CORE is defined src/PhpStormCopilot.php121-123 This prevents the system-wide mcp.json from being accidentally overwritten when running tests. The .github/mcp-config.json exists precisely to provide a usable MCP configuration during development without triggering that path.

Diagram: Development vs. Production MCP Config Files

Sources: .github/mcp-config.json1-14 src/PhpStormCopilot.php99-132

---

Modifying boost.json

The boost.json file can be manually edited to change Laravel Boost behavior. After modification, run:

This command re-reads boost.json and updates all dependent configurations, including the system-wide MCP configuration file.

Common Modifications

Change	When to Use	Impact
Add agent to agents array	Installing a new Boost agent	Agent becomes available for registration
Set guidelines: true	Enable AI guideline generation	Creates/updates .github/instructions/
Add skill to skills array	Enable additional AI capabilities	Generates skill files in .github/skills/
Set sail: true	Using Laravel Sail	Enables Sail command transformation
Set mcp: true	Enable MCP server	Allows PhpStorm Copilot integration

Sources: boost.json1-17

---

Integration with PhpStormCopilot Agent

The PhpStormCopilot agent does not directly read boost.json during execution, but relies on the Laravel Boost framework to have already processed it during application bootstrap. The agent's behavior is indirectly influenced by this configuration:

Diagram: PhpStormCopilot and boost.json Interaction

When the agent's install() or installFileMcp() methods execute, they operate within a Laravel Boost context that has already parsed boost.json. The agent generates appropriate files and configurations based on the framework's understanding of this configuration.

Sources: boost.json1-17