Core Architecture

This document explains the internal architecture of the revolution/laravel-boost-copilot-cli package and how its components integrate with Laravel Boost to enable GitHub Copilot CLI communication with Laravel applications via the Model Context Protocol (MCP).

For installation and setup procedures, see Getting Started. For detailed configuration options, see Configuration System. For development and testing procedures, see Development Guide.

---

System Overview

The package consists of two primary components that work together to integrate GitHub Copilot CLI with Laravel Boost:

Component	File	Purpose
CopilotCli	src/CopilotCli.php	Core agent implementation extending Agent base class and implementing SupportsGuidelines, SupportsMcp, and SupportsSkills interfaces
CopilotCliServiceProvider	src/CopilotCliServiceProvider.php	Laravel service provider registering CopilotCli with Laravel Boost's agent registry and handling Testbench-specific path adjustments

Component Integration Diagram

Sources: src/CopilotCli.php1-150 src/CopilotCliServiceProvider.php1-43 .github/copilot-instructions.md24-36

---

CopilotCli Class Implementation

The CopilotCli class src/CopilotCli.php14 extends Laravel\Boost\Install\Agents\Agent and implements three interfaces:

1. Laravel\Boost\Contracts\SupportsGuidelines - Provides paths for AI guidelines and skills
2. Laravel\Boost\Contracts\SupportsMcp - Provides MCP server configuration
3. Laravel\Boost\Contracts\SupportsSkills - Provides skills directory path

Class Declaration and Properties

The class maintains two static properties for testing:

• $fake_testbench src/CopilotCli.php16 - Simulates Orchestra Testbench environment
• $fake_wsl src/CopilotCli.php18 - Simulates Windows Subsystem for Linux environment

Sources: src/CopilotCli.php1-18

Agent Base Class Methods

The CopilotCli class inherits from the Agent base class and provides agent-specific implementations:

Agent Identification

Method	Return Value	Purpose
name()	'copilot-cli'	Internal identifier used by Laravel Boost's agent registry
displayName()	'GitHub Copilot CLI'	User-facing name displayed in installation prompts

Sources: src/CopilotCli.php20-28

System-Wide Detection

The systemDetectionConfig() method src/CopilotCli.php35-46 returns platform-specific shell commands to detect GitHub Copilot CLI installation:

Platform	Detection Command	Purpose
Platform::Darwin (macOS)	command -v copilot	Checks if copilot exists in PATH
Platform::Linux	command -v copilot	Checks if copilot exists in PATH
Platform::Windows	where copilot 2>nul	Windows-specific command existence check

The method uses a match expression to return the appropriate detection configuration based on the platform.

Sources: src/CopilotCli.php35-46

Project-Specific Detection

The projectDetectionConfig() method src/CopilotCli.php54-59 checks for the presence of .github/copilot-instructions.md:

This file indicates that the project has been configured for GitHub Copilot CLI integration.

Sources: src/CopilotCli.php54-59

SupportsGuidelines Interface Implementation

The SupportsGuidelines interface implementation provides paths for AI-related configuration files:

Guidelines Path

The guidelinesPath() method src/CopilotCli.php66-69 returns the file path where AI guidelines should be written:

This path is configurable via config/boost.php, defaulting to .github/instructions/laravel-boost.instructions.md.

Sources: src/CopilotCli.php66-69

Skills Path

The skillsPath() method src/CopilotCli.php74-77 returns the directory path where agent skills should be written:

Skills are specialized AI capabilities that activate in specific contexts. The default path is .github/skills/.

Sources: src/CopilotCli.php74-77

SupportsMcp Interface Implementation

The SupportsMcp interface implementation provides MCP server configuration for GitHub Copilot CLI:

MCP Configuration File Path

The mcpConfigPath() method src/CopilotCli.php79-82 specifies where the MCP configuration file should be written:

This file contains the server configuration that GitHub Copilot CLI uses to connect to Laravel Boost's MCP server.

Sources: src/CopilotCli.php79-82

MCP Server Configuration Generation

The mcpServerConfig() method src/CopilotCli.php91-103 generates the MCP server configuration payload:

MCP Configuration Generation Flow

The generated configuration structure:

Configuration element purposes:

Key	Value	Purpose
type	'local'	Indicates a locally-spawned MCP server process
command	Environment-adapted	Converted via convertCommandToPhpPath() to match execution environment
args	Conditional array	['boost:mcp'] for Testbench, ['artisan', 'boost:mcp'] otherwise
env	Passthrough	Environment variables passed from caller
tools	['*']	Enables all available Laravel Boost MCP tools

Sources: src/CopilotCli.php91-103

Environment Detection and Command Conversion

Testbench Detection

The isRunningInTestbench() method src/CopilotCli.php133-140 detects if the code is running within Orchestra Testbench:

Detection logic:

1. Check the static $fake_testbench flag (for testing purposes)
2. Check if the TESTBENCH_CORE constant is defined (set by Orchestra Testbench)

Sources: src/CopilotCli.php133-140

WSL Detection

The isRunningInsideWsl() method src/CopilotCli.php124-131 detects if the code is running inside Windows Subsystem for Linux:

Detection logic:

1. Check the static $fake_wsl flag (for testing purposes)
2. Check for WSL_DISTRO_NAME environment variable (set by WSL 2)
3. Check for IS_WSL environment variable (alternative WSL indicator)

Sources: src/CopilotCli.php124-131

Command Path Conversion

The convertCommandToPhpPath() method src/CopilotCli.php108-122 adapts the PHP command based on execution environment:

Command Conversion Logic

Environment-specific command mapping:

Condition	Input Command	Output Command	Rationale
isRunningInTestbench()	Any	./vendor/bin/testbench	Testbench wrapper script required
isRunningInsideWsl()	Any	getPhpPath()	WSL needs proper PHP path resolution
Command ends with sail	*/sail	./vendor/bin/sail	Laravel Sail wrapper script required
Default	Any	Unchanged	Standard PHP command (typically php)

Sources: src/CopilotCli.php108-122

Testing Support

The fake() static method src/CopilotCli.php145-149 enables test mode simulation:

This method allows tests to simulate environment-specific behavior:

• $testbench - Controls isRunningInTestbench() return value
• $wsl - Controls isRunningInsideWsl() return value

This enables testing of environment-specific code paths without requiring actual environment setup.

Sources: src/CopilotCli.php145-149

---

Service Provider Integration

The CopilotCliServiceProvider class src/CopilotCliServiceProvider.php14 handles Laravel integration and agent registration.

Service Provider Structure

Service Provider Flow Diagram

Sources: src/CopilotCliServiceProvider.php16-42

Agent Registration

The boot() method src/CopilotCliServiceProvider.php16-23 performs two key operations:

1. Registration with Laravel Boost's Agent Registry:

This registers the CopilotCli class with the identifier 'copilot-cli' in Laravel Boost's agent registry. The agent becomes available during php artisan boost:install when users select their AI agent.

2. Testbench-Specific Configuration:

If running in Orchestra Testbench (detected via the TESTBENCH_CORE constant), additional path adjustments are applied to ensure correct file operations during installation.

Sources: src/CopilotCliServiceProvider.php16-23

Testbench Path Adjustments

The testbench() method src/CopilotCliServiceProvider.php28-42 corrects path resolution issues specific to Orchestra Testbench:

Testbench Path Resolution

Path Resolution Flow

Path correction purposes:

Path Type	Issue	Resolution	Method Call
Base Path	Points to Testbench skeleton directory instead of package root	Set to current working directory	setBasePath(getcwd())
Storage Path	Missing storage directory for file operations	Use Testbench default skeleton storage	useStoragePath(default_skeleton_path('storage'))
App Path	Missing app directory for application structure	Use Testbench default skeleton app	useAppPath(default_skeleton_path('app'))

These adjustments ensure that when php artisan boost:install runs in a package development environment, configuration files are written to the correct locations relative to the package root, not the Testbench skeleton directory.

Sources: src/CopilotCliServiceProvider.php28-42

---

MCP Protocol Integration

The Model Context Protocol (MCP) integration enables communication between GitHub Copilot CLI and the Laravel Boost MCP server.

MCP Configuration Flow

Sources: src/CopilotCli.php69-93 src/CopilotCli.php64-67

Generated Configuration Structure

The .github/mcp-config.json file structure generated by mcpServerConfig() varies by environment. The complete file includes the mcpServers wrapper:

Standard Laravel Application

Orchestra Testbench

Laravel Sail

WSL Environment

Environment-specific differences:

Environment	command Value	args Value	Notes
Standard Laravel	php	["artisan", "boost:mcp"]	Direct PHP execution
Testbench	./vendor/bin/testbench	["boost:mcp"]	No artisan prefix needed
Laravel Sail	./vendor/bin/sail	["artisan", "boost:mcp"]	Sail wrapper script
WSL	php	["artisan", "boost:mcp"]	Resolved via getPhpPath()

Sources: src/CopilotCli.php91-103 src/CopilotCli.php108-122 .github/copilot-instructions.md38-90

MCP Server Lifecycle

The MCP server remains active for the duration of the Copilot CLI session, providing continuous access to Laravel application context.

Sources: src/CopilotCli.php81-93

---

Architecture Constraints

The package enforces several architectural constraints through its implementation:

Interface Contracts

The CopilotCli class must implement:

1. Agent Interface Methods:

   • systemDetectionConfig(Platform $platform): array src/CopilotCli.php32-37
   • projectDetectionConfig(): array src/CopilotCli.php44-49
   • agentName(): ?string src/CopilotCli.php54-57
   • guidelinesPath(): string src/CopilotCli.php64-67

2. McpClient Interface Methods:

   • mcpConfigPath(): string src/CopilotCli.php69-72
   • mcpServerConfig(string $command, array $args, array $env): array src/CopilotCli.php81-93

Environment Adaptability Requirements

The class must:

• Detect Testbench environments via TESTBENCH_CORE constant src/CopilotCli.php117
• Convert commands appropriately for WSL, Sail, and Testbench src/CopilotCli.php98-109
• Provide different argument arrays for Testbench vs. standard environments src/CopilotCli.php86-89

Service Provider Requirements

The service provider must:

• Register the code environment with Laravel Boost on boot src/CopilotCliServiceProvider.php18
• Handle Testbench path adjustments when the constant is defined src/CopilotCliServiceProvider.php20-22
• Listen for CommandStarting events in Testbench mode src/CopilotCliServiceProvider.php30
• Apply path corrections only for boost:install and boost:update commands src/CopilotCliServiceProvider.php31-33

Sources: src/CopilotCli.php13-127 src/CopilotCliServiceProvider.php14-43