System Overview

This page describes the full runtime architecture of laravel-boost-copilot-cli: how the package's components are wired together, what happens when a developer installs and invokes the system, and how data flows between each layer. For individual component details, see:

• CopilotCli Agent Class (4.2) — method-level documentation of CopilotCli
• Service Provider Integration (4.3) — CopilotCliServiceProvider internals
• MCP Protocol Integration (4.4) — the MCP config payload format
• MCP Configuration File (5.1) — .github/mcp-config.json field reference

---

Role of This Package

This package is a custom agent plugin for the laravel/boost framework. Its sole job is to teach laravel/boost how to configure GitHub Copilot CLI as an AI agent: what files to generate, where to write them, and how to describe a running MCP server to the Copilot CLI binary.

The package contributes two PHP classes and a set of resource templates. Everything else — the actual MCP tool implementations, the boost:install and boost:mcp Artisan commands — lives in laravel/boost.

Sources: README.md1-15 .github/copilot-instructions.md1-35

---

Component Map

Title: Class and Method Relationships in the Package

Sources: src/CopilotCli.php1-150 src/CopilotCliServiceProvider.php1-43

---

Two-Phase Operation

The system operates in two clearly separated phases:

Phase	Trigger	What Happens
Install	php artisan boost:install	CopilotCli methods provide paths and config; laravel/boost writes files to .github/
Runtime	copilot --additional-mcp-config @.github/mcp-config.json	Copilot CLI reads .github/mcp-config.json, spawns boost:mcp as a subprocess, and communicates over MCP

These phases are independent. Install only needs to run once (or again after environment changes). Runtime runs every time the developer uses copilot.

Sources: README.md41-63

---

Install Phase: File Generation

When php artisan boost:install runs, it calls methods on the registered CopilotCli agent instance to determine what to write and where.

Title: Install Phase — Agent Method to Output File Mapping

The three file-generating methods on CopilotCli are:

Method	Returns	Output File
mcpConfigPath()	'.github/mcp-config.json'	.github/mcp-config.json
mcpServerConfig(string $command, ...)	Array with type, command, args, env, tools	Embedded in mcp-config.json
guidelinesPath()	'.github/instructions/laravel-boost.instructions.md'	.github/instructions/laravel-boost.instructions.md
skillsPath()	'.github/skills'	.github/skills/pest-testing/SKILL.md

Sources: src/CopilotCli.php63-103

---

Runtime Phase: Request Flow

Title: Runtime Request Flow from copilot CLI to boost:mcp Command

The runtime flow begins when Copilot CLI parses .github/mcp-config.json. The mcpServers.laravel-boost entry specifies type: local, which tells Copilot CLI to spawn a subprocess. The command and args fields (generated by CopilotCli::mcpServerConfig()) determine which executable runs: php artisan boost:mcp in a standard Laravel app, ./vendor/bin/testbench boost:mcp in Testbench, or ./vendor/bin/sail artisan boost:mcp in Laravel Sail.

Once the subprocess starts, the boost:mcp command bootstraps the Laravel application and begins MCP protocol communication over standard input/output. All MCP tools registered in Laravel Boost become available to Copilot CLI for the duration of the session.

Sources: .github/mcp-config.json1-14 .github/copilot-instructions.md38-73

---

Environment Adaptation

The CopilotCli::mcpServerConfig() method src/CopilotCli.php91-103 calls convertCommandToPhpPath() src/CopilotCli.php108-122 to select the correct command based on runtime environment detection. The resulting command and args values determine what Copilot CLI spawns as a subprocess.

Title: convertCommandToPhpPath() Environment Detection Flow

Generated MCP Configuration by Environment

Environment	Detection Method	command	args	Code Reference
Testbench	defined('TESTBENCH_CORE')	./vendor/bin/testbench	["boost:mcp"]	src/CopilotCli.php133-140
WSL	getenv('WSL_DISTRO_NAME') or getenv('IS_WSL')	Absolute PHP path from getPhpPath()	["artisan", "boost:mcp"]	src/CopilotCli.php124-131
Laravel Sail	Command ends with /sail	./vendor/bin/sail	["artisan", "boost:mcp"]	src/CopilotCli.php118-121
Standard Laravel	Default case	php (or provided command)	["artisan", "boost:mcp"]	src/CopilotCli.php118-121

Key Implementation Details

The mcpServerConfig() method src/CopilotCli.php91-103 constructs the final configuration array:

This ensures that:

• Testbench environments omit artisan since vendor/bin/testbench is already an Artisan entrypoint
• WSL environments use an absolute PHP path to avoid path translation issues
• Sail environments use the ./vendor/bin/sail wrapper to execute commands inside the Docker container
• Standard Laravel applications use the provided PHP command (typically php)

Sources: src/CopilotCli.php108-140 .github/copilot-instructions.md42-90

---

Service Provider Bootstrap

Title: CopilotCliServiceProvider Registration Flow

The CopilotCliServiceProvider src/CopilotCliServiceProvider.php14-43 serves as the integration point between this package and Laravel Boost:

Registration Phase src/CopilotCliServiceProvider.php16-18

This single call makes the CopilotCli agent available to Laravel Boost. When a user runs php artisan boost:install and selects "GitHub Copilot CLI" from the agent list, Laravel Boost instantiates CopilotCli and calls its interface methods (mcpConfigPath(), mcpServerConfig(), guidelinesPath(), skillsPath()) to generate the necessary files.

Testbench Path Fix src/CopilotCliServiceProvider.php20-42

In Testbench environments (defined('TESTBENCH_CORE')), the provider listens for CommandStarting events on the boost:install and boost:update commands. When these commands start, it:

1. Changes the base path from the Testbench skeleton to the current working directory via $this->app->setBasePath(getcwd())
2. Redirects storage and app paths to the Testbench skeleton via useStoragePath() and useAppPath()

This ensures that generated configuration files (.github/mcp-config.json, guidelines, skills) are written to the package's root directory rather than inside the Testbench skeleton directory.

Sources: src/CopilotCliServiceProvider.php1-43

---

Summary of Key Interfaces

CopilotCli implements three contracts from laravel/boost:

Interface	Namespace	Methods Required
SupportsGuidelines	Laravel\Boost\Contracts	guidelinesPath()
SupportsMcp	Laravel\Boost\Contracts	mcpConfigPath(), mcpServerConfig()
SupportsSkills	Laravel\Boost\Contracts	skillsPath()

These interfaces define the surface area that laravel/boost's boost:install command consults when generating configuration files for this agent.

Sources: src/CopilotCli.php8-14