Multi-Project Workflow

This document provides step-by-step instructions for managing multiple Laravel projects when using the laravel-boost-phpstorm-copilot package. It explains the architectural constraint of system-wide MCP configuration and the required workflow when switching between projects.

For information about the underlying architectural reason for this workflow, see Understanding System-Wide MCP Configuration. For initial setup of your first project, see Initial Configuration with boost:install.

---

The System-Wide Configuration Constraint

The mcp.json configuration file used by PhpStorm's GitHub Copilot plugin is stored in a system-wide location, not within individual Laravel projects. However, this configuration file contains absolute paths to a specific Laravel project's PHP binary and artisan file.

System-Wide Storage Locations:

Operating System	MCP Configuration Path
macOS	~/.config/github-copilot/intellij/mcp.json
Linux	~/.config/github-copilot/intellij/mcp.json
Windows	%LOCALAPPDATA%\github-copilot\intellij\mcp.json
WSL	%LOCALAPPDATA%\github-copilot\intellij\mcp.json (Windows side)

Project-Specific Content:

The configuration contains entries like:

This means when you switch from Project A to Project B, the configuration still points to Project A's paths, causing GitHub Copilot to connect to the wrong project's MCP server.

Sources: README.md114-124 resources/boost/guidelines/core.blade.php5-32

---

Project Switching State Diagram

Diagram: Configuration State Transitions During Project Switching

Code Entity Mapping:

User Action	Code Entity Invoked	File Path
php artisan boost:install	Laravel Boost command	Provided by laravel/boost
Agent selection	PhpStormCopilotServiceProvider::boot()	src/PhpStormCopilotServiceProvider.php
Platform detection	PhpStormCopilot::systemDetectionConfig()	src/PhpStormCopilot.php
PHP path resolution	PhpStormCopilot::getPhpPath()	src/PhpStormCopilot.php
Artisan path resolution	PhpStormCopilot::getArtisanPath()	src/PhpStormCopilot.php
Native file write	PhpStormCopilot::installFileMcp()	src/PhpStormCopilot.php
WSL file write	WithWSL::installMcpViaWsl()	src/Concerns/WithWSL.php
Sail command wrapping	PhpStormCopilot::transformSailCommand()	src/PhpStormCopilot.php
WSL command wrapping	WithWSL::transformMcpCommandForWsl()	src/Concerns/WithWSL.php

Sources: README.md114-118 resources/boost/guidelines/core.blade.php23-28

---

Step-by-Step Project Switching Workflow

1. Switch to the New Project Directory

Navigate to your target Laravel project:

2. Run boost:install to Update Configuration

Execute the installation command to reconfigure mcp.json with the new project's paths:

Interactive Mode:

Select the following when prompted:

• Features: AI Guidelines, Agent Skills, Boost MCP Server Configuration
• Agent: PhpStorm with GitHub Copilot

Non-Interactive Mode (Recommended):

The --no-interaction flag skips all prompts and uses default selections.

3. Verify Configuration Update

Check that the configuration was written successfully:

Platform	Verification Command
macOS/Linux	cat ~/.config/github-copilot/intellij/mcp.json
Windows	type %LOCALAPPDATA%\github-copilot\intellij\mcp.json
WSL	powershell.exe -Command "Get-Content $env:LOCALAPPDATA\github-copilot\intellij\mcp.json"

The command and args[0] values should contain absolute paths pointing to your current project.

4. Resume Development

PhpStorm's GitHub Copilot will now connect to the correct project's MCP server when you use AI assistance features.

Sources: README.md96-118 resources/boost/guidelines/core.blade.php16-28

---

Command Options Reference

The boost:install command provided by Laravel Boost accepts flags for controlling installation behavior.

Diagram: Command Flag Processing

Flag Reference:

Flag	Invokes	Output	Required for Switching
--guidelines	Template rendering from resources/boost/guidelines/core.blade.php	.github/instructions/laravel-boost.instructions.md	Optional
--skills	Skill file operations	.github/skills/ directory	Optional
--mcp	PhpStormCopilot::installFileMcp() or WithWSL::installMcpViaWsl()	System-wide mcp.json with absolute paths	Required
--no-interaction	Skips prompts in Laravel Boost	None	Recommended

Minimum Required Command:

Recommended Command:

Sources: README.md117 README.md120

---

Common Multi-Project Scenarios

Scenario 1: Daily Work Across Multiple Projects

Workflow:

1. Morning: Work on Project A
2. Afternoon: Switch to Project B for client demo
3. Evening: Return to Project A for bug fix

Commands:

Scenario 2: Cloned Repository to New Location

Problem: You cloned a project to a new directory or machine. The old mcp.json points to the previous location.

Solution:

Scenario 3: Multiple Versions of Same Project

Example: Separate directories for main, staging, and feature-branch versions.

Workflow: Each directory requires separate boost:install execution when switching:

Sources: resources/boost/guidelines/core.blade.php23-28

---

Detection of Stale Configuration

The package installs AI guidelines that help GitHub Copilot detect configuration issues.

Diagram: Stale Configuration Detection Flow

Guideline Generation:

The guidelines file is created by the PhpStormCopilot agent during boost:install execution:

Component	Value
Template source	resources/boost/guidelines/core.blade.php5-32
Output location	.github/instructions/laravel-boost.instructions.md
Contains	Verification instructions referencing PhpStormCopilot::mcpConfigPath() locations
Purpose	Instruct Copilot to check mcp.json contains correct project paths

Warning Signs of Stale Configuration:

Symptom	Cause
MCP tools return data from different project	mcp.json points to wrong project's artisan file
File paths don't match current structure	PhpStormCopilot::getArtisanPath() resolved to old project
Database operations affect wrong database	Wrong project's .env file being read
Generated code uses wrong namespace	Context from wrong project's composer.json

Sources: resources/boost/guidelines/core.blade.php1-33

---

Integration with Laravel Boost Update Command

Important Limitation: As of Laravel Boost 1.8+, the boost:update command does not update the MCP configuration file.

Reason: The boost:update command is designed for updating package-managed files within the project directory. The system-wide mcp.json is considered environment-specific configuration, not package-managed content.

Correct Command for MCP Updates:

Sources: README.md120

---

Configuration File Anatomy

When boost:install --mcp executes, the PhpStormCopilot agent generates the configuration through this call chain.

Diagram: MCP Configuration Generation Call Flow

Code Entity Reference:

Method	Signature	Purpose
PhpStormCopilot::systemDetectionConfig()	public function systemDetectionConfig(): array	Returns OS detection config arrays
PhpStormCopilot::mcpConfigPath()	public function mcpConfigPath(array $environment): string	Resolves OS-specific mcp.json path
PhpStormCopilot::getPhpPath()	protected function getPhpPath(): string	Returns absolute PHP binary path
PhpStormCopilot::getArtisanPath()	protected function getArtisanPath(): string	Returns absolute artisan file path
PhpStormCopilot::transformSailCommand()	protected function transformSailCommand(string $command): string	Wraps command with bash -c for Sail
PhpStormCopilot::removeEmptyArrays()	protected function removeEmptyArrays(array $data): array	Recursively removes empty arrays
PhpStormCopilot::installFileMcp()	protected function installFileMcp(string $path, string $content): bool	Writes file using Laravel File facade
WithWSL::isWSL()	protected function isWSL(): bool	Checks WSL_DISTRO_NAME environment variable
WithWSL::transformMcpCommandForWsl()	protected function transformMcpCommandForWsl(string $command, array $args): array	Wraps with wsl.exe --cd PROJECT
WithWSL::installMcpViaWsl()	protected function installMcpViaWsl(string $windowsPath, string $content): bool	Uses PowerShell to write Windows-side file

Sources: src/PhpStormCopilot.php src/Concerns/WithWSL.php src/PhpStormCopilotServiceProvider.php

---

Performance Considerations

The boost:install command is designed to be fast when run with --no-interaction:

Operation	Typical Duration
Environment detection	< 100ms
Path resolution	< 50ms
File writing (Unix)	< 50ms
File writing (WSL)	200-500ms (requires PowerShell)
Total (non-interactive)	< 1 second (standard), 1-2 seconds (WSL)

Optimization Tip: Create shell aliases for frequent project switches:

---

Verification Checklist

After running boost:install in a new project, verify the configuration:

Check	Command	Expected Result
MCP file exists	See OS-specific commands above	File exists
Contains current project path	Check command/args in JSON	Absolute path to current project
PHP path is correct	which php (Unix) or where php (Windows)	Matches command in JSON
Artisan path is absolute	Check args[0] in JSON	Full path like /home/user/project/artisan
Laravel Boost responds	php artisan boost:mcp	Starts MCP server without errors

Sources: README.md122-124

---

Alternative Solution for Frequent Switchers

For developers who frequently switch between many projects, the repository recommends considering laravel-boost-copilot-cli which supports project-level MCP configuration instead of system-wide configuration.

This alternative eliminates the need to run boost:install when switching projects, as each project maintains its own configuration file.

Sources: README.md84