Configuration System

Purpose and Scope

The Configuration System defines how the package generates, stores, and consumes configuration files that control MCP server integration, AI guidelines, and environment-specific behavior. All configuration files produced by this package reside under .github/. This page provides an architectural overview; each child page covers a specific configuration area in depth.

Child Page	Title	Primary File(s)
5.1	MCP Configuration File	.github/mcp-config.json
5.2	Local Configuration Overrides	.github/mcp-config.local.json
5.3	Guidelines and Instructions	.github/instructions/laravel-boost.instructions.md, .github/skills/
5.4	Environment Detection and Adaptation	src/CopilotCli.php (detection and path conversion logic)
5.5	Boost Configuration	boost.json

For the initial configuration generation process, see page 2.2 (Configuration Generation).

Configuration Architecture Overview

The configuration system operates across three distinct phases: generation, storage, and consumption. The CopilotCli agent class orchestrates configuration generation during installation, producing environment-specific configuration files that are later consumed by GitHub Copilot CLI at runtime.

Configuration Architecture Flow

Sources: src/CopilotCli.php1-129 README.md42-98

Configuration File Locations

The package generates and consumes multiple configuration files, each with a distinct purpose and storage location:

File Path	Purpose	Version Control	Generated By
.github/mcp-config.json	MCP server connection configuration	Yes (committed)	CopilotCli::mcpServerConfig()
.github/mcp-config.local.json	Local overrides with sensitive data	No (git-ignored)	Manual creation
.github/instructions/laravel-boost.instructions.md	AI guidelines for Copilot	Yes (committed)	CopilotCli::guidelinesPath()
.github/skills/	Agent-specific skills directory	Yes (committed)	CopilotCli::skillsPath()
boost.json	Laravel Boost agent configuration	Yes (committed)	Laravel Boost core

The separation between mcp-config.json (version-controlled) and mcp-config.local.json (git-ignored) enables secure credential management while maintaining shareable project configuration.

Sources: src/CopilotCli.php57-73 README.md100-162

Configuration Path Resolution

The CopilotCli class provides methods for resolving configuration file paths, with support for runtime customization via the boost.json configuration file:

CopilotCli Path Resolution Methods

The guidelinesPath() method (src/CopilotCli.php57-60) reads from config('boost.agents.copilot_cli.guidelines_path'), defaulting to .github/instructions/laravel-boost.instructions.md. Similarly, skillsPath() (src/CopilotCli.php65-68) reads from config('boost.agents.copilot_cli.skills_path'), defaulting to .github/skills.

The mcpConfigPath() method (src/CopilotCli.php70-73) returns a fixed path .github/mcp-config.json with no configuration override support.

Sources: src/CopilotCli.php57-73

MCP Server Configuration Generation

The mcpServerConfig() method generates the MCP server configuration payload that defines how GitHub Copilot CLI should launch and communicate with the Laravel Boost MCP server:

MCP Configuration Generation Logic

The implementation at src/CopilotCli.php82-94 follows this logic:

1. Command Conversion: The input $command (e.g., php, wsl, sail) is converted to the appropriate executable path via convertCommandToPhpPath()
2. Args Filtering: The args array includes 'artisan' only when not running in Testbench. The boost:mcp command is always included
3. Configuration Assembly: Returns an array with type, command, args, env, and tools keys

The tools key is always set to ['*'], granting access to all available MCP tools exposed by Laravel Boost.

Sources: src/CopilotCli.php82-94

Environment Detection and Command Conversion

The configuration system adapts to different execution environments through the convertCommandToPhpPath() method, which translates environment-specific commands into appropriate executable paths:

Command Conversion Decision Tree

The implementation at src/CopilotCli.php99-110 uses a priority-based conversion strategy:

1. Testbench Detection: If TESTBENCH_CORE is defined or testing is faked, return ./vendor/bin/testbench
2. Command Pattern Matching: Extract the command name after the last / and match against known patterns:
   • wsl or wsl.exe → php (converts WSL wrapper to direct PHP execution)
   • sail → ./vendor/bin/sail (Laravel Sail wrapper)
   • All others → return original command unchanged

This conversion ensures the MCP configuration file contains the correct executable path for each environment without requiring manual editing.

Sources: src/CopilotCli.php99-110

Testbench Environment Detection

The isRunningInTestbench() method at src/CopilotCli.php112-119 determines whether the code is executing in an Orchestra Testbench environment. It checks two conditions:

1. Fake Mode: If the static $fake flag is set (via CopilotCli::fake()), the method returns true. This lets unit tests simulate Testbench execution without the constant being defined.
2. Constant Detection: Falls back to checking whether TESTBENCH_CORE is defined, which Orchestra Testbench sets automatically during bootstrap.

This detection influences both command conversion and argument filtering in the generated MCP configuration — specifically, whether ./vendor/bin/testbench is used as the command and whether the artisan argument is omitted.

Sources: src/CopilotCli.php112-119

Configuration Consumption Patterns

GitHub Copilot CLI consumes the generated configuration through two distinct patterns:

Manual Configuration Loading

The explicit pattern requires passing the --additional-mcp-config flag on every invocation:

This pattern works with any Copilot CLI command:

Sources: README.md55-67

Automated Configuration Loading

The automated pattern uses a shell function wrapper (copilot_mcp) that automatically detects and loads configuration files defined at README.md73-93 It checks for both mcp-config.json and mcp-config.local.json, automatically appending the appropriate --additional-mcp-config flags when files exist. The function is then aliased to copilot, so users invoke copilot without explicit configuration flags.

Sources: README.md73-98

Configuration Security Model

The configuration system implements a two-tier security model separating public and sensitive configuration:

Configuration Tier	File	Security Model	Use Case
Public	mcp-config.json	Version-controlled, safe for repository	Laravel Boost MCP server connection
Private	mcp-config.local.json	Git-ignored, local-only	Credentials for external MCP servers

Example private configuration at README.md109-124:

The copilot_mcp() shell function automatically merges both configuration files when present, allowing projects to maintain secure credential separation while supporting both local and remote MCP servers.

Sources: README.md100-124

Environment-Specific Configuration Examples

The package generates different MCP configurations based on the detected environment:

Standard Laravel Configuration

Testbench Configuration

Note that the Testbench configuration omits "artisan" from the args array, as demonstrated in the logic at src/CopilotCli.php88-90

Sources: README.md62-77 src/CopilotCli.php82-94

Configuration Validation

When Copilot CLI successfully loads the MCP configuration, it displays a confirmation message:

Configured MCP servers: laravel-boost

This message at README.md115 indicates that:

1. The configuration file was successfully parsed
2. The laravel-boost MCP server is registered
3. The server connection will be established when MCP tools are invoked

Absence of this message indicates configuration loading failure, requiring verification of:

• File path correctness in the --additional-mcp-config flag
• JSON syntax validity in the configuration file
• Proper file permissions for reading the configuration

Sources: README.md115