[1.x] Sail Support for Boost #303

NIAN97 · 2025-10-19T05:57:26Z

Add Automatic Laravel Sail Detection for MCP Server Configuration

Summary

This PR adds automatic detection of Laravel Sail environments and configures the MCP server to use Sail when detected. This ensures the MCP server runs inside the Docker container with the correct PHP version and environment, rather than using the host machine's PHP installation.

Motivation

Currently, users running Laravel Boost in Sail projects must manually configure the MCP server to use ./vendor/bin/sail instead of php. This PR makes the detection automatic, improving the developer experience for Sail users.

Problem

When Sail users run php artisan boost:install or php artisan boost:update, the generated MCP configuration uses:

{
    "mcpServers": {
        "laravel-boost": {
            "command": "php",
            "args": ["artisan", "boost:mcp"]
        }
    }
}

This runs the MCP server on the host machine, which may have:

Different PHP version than the container
Missing PHP extensions
Different environment configuration

Solution

With this PR, Sail projects automatically get:

{
    "mcpServers": {
        "laravel-boost": {
            "command": "./vendor/bin/sail",
            "args": ["artisan", "boost:mcp"]
        }
    }
}

EDIT

Updated Changes #303 (comment)

This commit adds automatic detection of Laravel Sail environments and configures the MCP server to use Sail when detected, ensuring the server runs inside the Docker container with the correct PHP version and environment. Changes: - Add isSailProject() method to detect Sail by checking for vendor/bin/sail and docker-compose.yml - Modify getPhpPath() to return './vendor/bin/sail' when Sail is detected - Modify getArtisanPath() to return 'artisan' when Sail is detected - Add fileExists() helper method for testability - Add 5 unit tests for Sail detection logic - Add 4 integration tests for real-world scenarios The detection is automatic and transparent - projects without Sail continue to work exactly as before using 'php artisan boost:mcp'. Fixes automatic configuration for Sail users running boost:install and boost:update commands.

Add comprehensive documentation for automatic Sail detection: - Add installation note for Sail users - Add dedicated 'Laravel Sail Support' section - Document automatic detection criteria - Provide configuration examples - Explain benefits of running MCP server inside Docker container

src/Install/CodeEnvironment/CodeEnvironment.php

@pushpak1300

Following code review feedback from @pushpak1300, removed the unnecessary fileExists() wrapper method and use file_exists() directly in isSailProject(). Also removed 3 unit tests that were specifically testing the fileExists() wrapper - the Sail detection is already covered by the integration tests in SailDetectionTest.php. Changes: - Remove fileExists() wrapper method - Use file_exists() directly in isSailProject() - Remove 3 redundant unit tests for fileExists() mocking - Integration tests still passing (6 tests, 10 assertions)

MltStephane · 2025-10-19T19:49:12Z

Hi! Thanks for the pull request 🙏🏾

I set up what should be my final environment (Ubuntu 25.04 / PhpStorm 2025.2.3 / Laravel Sail 1.46.0), but I still can’t get the integration to work.

Tried configuring mcpServers like this:

{
  "mcpServers": {
    "laravel-boost": {
      "command": "/home/stephane/Projets/my-app/vendor/bin/sail",
      "args": ["artisan", "boost:mcp"]
    }
  }
}

Also tried running Sail via a relative path:

{
  "mcpServers": {
    "laravel-boost": {
      "command": "./vendor/bin/sail",
      "args": ["artisan", "boost:mcp"]
    }
  }
}

Let me know if I’m missing a step or if there’s extra logging I can enable to help debug.

NIAN97 · 2025-10-19T20:25:58Z

Hi @MltStephane!

The MCP server needs to be configured with relative paths, not absolute paths.

Instead of:
"/home/stephane/Projets/my-app/vendor/bin/sail"

Use:
"./vendor/bin/sail"

The MCP server runs from your project root, so relative paths work correctly.
Can you try updating your configuration and let me know if it works?

MltStephane · 2025-10-19T20:51:03Z

Hi @MltStephane!

The MCP server needs to be configured with relative paths, not absolute paths.

Instead of: "/home/stephane/Projets/my-app/vendor/bin/sail"

Use: "./vendor/bin/sail"

The MCP server runs from your project root, so relative paths work correctly. Can you try updating your configuration and let me know if it works?

I tried both, but the relative path still throws an error.

503006172-9a579f0c-94f2-4e29-9e6d-9f4bdbd76a4b

@MltStephane

PhpStorm doesn't support symlinks in MCP configuration paths. When useAbsolutePathForMcp is true (PhpStorm), use the real Sail executable path instead of the symlink. Changes: - Detect when absolute paths are needed (PhpStorm/forceAbsolutePath) - Use 'vendor/laravel/sail/bin/sail' for PhpStorm - Keep './vendor/bin/sail' for other IDEs (Claude Code, Cursor, VS Code) This fixes the MCP server startup issue reported by @MltStephane

This file was only needed locally for creating the PR. Not required in the repository.

NIAN97 · 2025-10-19T21:10:40Z

Hola@MltStephane!
El servidor MCP debe configurarse con rutas relativas, no con rutas absolutas.
En lugar de: "/home/stephane/Projets/my-app/vendor/bin/sail"
Uso: "./vendor/bin/sail"
El servidor MCP se ejecuta desde la raíz de tu proyecto, por lo que las rutas relativas funcionan correctamente. ¿Podrías intentar actualizar tu configuración y avisarme si funciona?

Probé ambas cosas, pero la ruta relativa todavía arroja un error.

Hi @MltStephane!

I've fixed the PhpStorm symlink issue in cc1f068. PhpStorm now uses the real Sail executable path (vendor/laravel/sail/bin/sail) instead of the symlink (./vendor/bin/sail).

Can you pull the latest changes and try again? It should work now.

Thanks for testing!

MltStephane · 2025-10-19T21:29:49Z

Unfortunately, it's still not working.

After running boost:install, I get the following configuration:

"command": "/var/www/html/vendor/laravel/sail/bin/sail"

However, the following configuration doesn’t work either:

"command": "./vendor/laravel/sail/bin/sail"

NIAN97 · 2025-10-19T21:55:57Z

/home/stephane/Projets/my-app/vendor/bin/sail

The problem is PhpStorm needs to know which folder to run from. Try adding cwd to your config:

{
    "mcpServers": {
        "Laravel-boost": {
            "command": "/home/stephane/Projets/my-app/vendor/laravel/sail/bin/sail",
            "args": ["artisan", "boost:mcp"],
            "cwd": "/home/stephane/Projets/my-app"
        }
    }
}

Just replace /home/stephane/Projets/my-app with your actual project path on your computer (not the Docker path /var/www/html). Let me know if that works!

MltStephane · 2025-10-20T11:11:05Z

Still not working... No error, but the message "Not started" is displayed in Php Storm.

MltStephane · 2025-10-20T17:17:23Z

I made it work with the configuration from here : #36 (comment)

{
    "mcpServers": {
        "laravel-boost": {
            "command": "docker",
            "args": [
                "exec",
                "-i",
                "<container_name>",
                "php",
                "/var/www/html/artisan",
                "boost:mcp"
            ]
        }
    }
}

Edit: I'm now using this configuration, which tries to use the laravel.test container without specifying the name.

{
    "mcpServers": {
        "laravel-boost": {
            "command": "bash",
            "args": [
                "-lc",
                "docker exec -i \"$(docker ps -q --filter label=com.docker.compose.service=laravel.test | head -n1)\" php /var/www/html/artisan boost:mcp"
            ]
        }
    }
}

…ection This commit enhances Laravel Sail support for PhpStorm and adds compatibility with the modern compose.yaml format. ## Changes ### PhpStorm Docker Exec Integration - PhpStorm now uses `docker exec` instead of `./vendor/bin/sail` for better compatibility - Generates bash command that finds the running Sail container dynamically - Ensures MCP server runs inside the correct Docker container ### Compose.yaml Support - Updated Sail detection to support both `docker-compose.yml` (legacy) and `compose.yaml` (current) - Full compatibility with Laravel Sail's latest versions - Maintains backward compatibility with older Sail installations ### MCP Server Preservation - Added test to verify existing custom MCP servers are preserved - FileWriter correctly merges new laravel-boost server with user's existing configuration - Documentation updated to show preservation behavior ### Documentation - Added PhpStorm-specific configuration example - Documented difference between PhpStorm and other IDEs - Added examples showing custom MCP server preservation - Clear explanation of automatic vs manual configuration ### Tests - 8/8 Sail detection tests passing - 45/45 FileWriter tests passing (including new preservation test) - 313/315 total tests passing (2 PDO failures unrelated to changes) ## Generated Configuration **PhpStorm with Sail:** ```json { "command": "bash", "args": ["-lc", "docker exec -i \"$(docker ps -q ...)\" php .../artisan boost:mcp"] } ``` **Other IDEs with Sail:** ```json { "command": "./vendor/bin/sail", "args": ["artisan", "boost:mcp"] } ```

NIAN97 · 2025-10-26T20:55:36Z

@MltStephane Already updated the PR with that solution. Now it automatically detects Sail and generates the config with docker exec for PhpStorm (and also supports compose.yaml in addition to docker-compose.yml).

pushpak1300 · 2025-10-28T12:45:29Z

I tried this config on PHPStrom with Junie and ai-assitant and it worked. @MltStephane is it not working for you ?

{
    "mcpServers": {
        "laravel-boost": {
            "command": "<full-project-path>/vendor/bin/sail",
            "args": [
                "artisan",
                "boost:mcp"
            ]
        }
    }
}

Update:
Even this is working for me.

{
    "mcpServers": {
        "laravel-boost": {
            "command": "./vendor/bin/sail",
            "args": [
                "artisan",
                "boost:mcp"
            ]
        }
    }
}

MltStephane · 2025-10-28T13:15:01Z

None of these configurations are working for me (Ubuntu 25.04 / PhpStorm 2025.2.3 / Laravel Sail 1.46.0).

Are you on Ubuntu ?

pushpak1300 · 2025-10-28T13:35:29Z

None of these configurations are working for me (Ubuntu 25.04 / PhpStorm 2025.2.3 / Laravel Sail 1.46.0).

Are you on Ubuntu ?

Sadly, not. Very tricky situation to be in. Let me see if I can test on ubuntu any way.

MltStephane · 2025-10-28T13:38:00Z

Feel free to reach out if you need any additional tests or data from me.

pushpak1300 · 2025-10-29T12:30:17Z

@MltStephane I just verefied this with the Ubuntu + Phpstrom setup and it's working fine with this config.

I think we will go and implement with this config only and no docker exec is needed. @NIAN97

chinmaypurav · 2025-10-29T12:37:39Z

None of these configurations are working for me (Ubuntu 25.04 / PhpStorm 2025.2.3 / Laravel Sail 1.46.0).

Are you on Ubuntu ?

It is working on Ubuntu 24

MltStephane · 2025-10-29T13:06:32Z

@MltStephane I just verefied this with the Ubuntu + Phpstrom setup and it's working fine with this config.

I think we will go and implement with this config only and no docker exec is needed. @NIAN97

Did you try on 24 or 25? I just tested on a third laptop running Ubuntu 24, and it works. The others are on 25 and still don’t work.

I’d really like to understand the root cause to avoid issues for future users. Should we continue this in an issue?

pushpak1300 · 2025-10-29T13:15:24Z

Yes I tried with ubuntu 24 + PhpStorm 2025.2.4

MltStephane · 2025-10-29T13:17:49Z

Ok, so probably the issue is due to an incompatibility of a tool (which one ?) on Ubuntu 25

chinmaypurav · 2025-10-29T13:22:46Z

Ok, so probably the issue is due to an incompatibility of a tool (which one ?) on Ubuntu 25

Two of us recently faced quite a few bugs and issues with Ubuntu 25 (not related to this), but the point is as Ubutnu 25 is not an LTS, there is a high probabilty of compatibility issues. Would recommend to try with 24.04 LTS

NIAN97 · 2025-10-29T14:08:39Z

@pushpak1300 so should I keep this configuration?

{ 
  "mcpServers": {
    "laravel-boost": {
      "command": "./vendor/bin/sail",
      "args": [
        "artisan",
        "boost:mcp"
      ]
    }
  }
}

Signed-off-by: Pushpak Chhajed <[email protected]>

pushpak1300 · 2025-10-30T18:52:54Z

I made a few adjustments here.

Instead of forcing Sail on the user, it will now first prompt them to confirm whether they want to install Sail, but only when the Sail package is detected.
If the user runs sail artisan boost:install, the installer will assume the command is being executed inside Sail and will apply the Sail-specific setup.
Keeping scope of this MR to just add and update config for the Laravel sail. For guidelines updates based on Sail will create another MR.

For now, I am keeping the configuration as it is until we run into more constraints:

{
  "mcpServers": {
    "laravel-boost": {
      "command": "./vendor/bin/sail",
      "args": [
        "artisan",
        "boost:mcp"
      ]
    }
  }
}

Demo: https://www.loom.com/share/76618c48aad54259a834fcee381cf092

NIAN97 · 2025-10-30T21:07:09Z

@pushpak1300 issue in vendor/laravel/boost/src/Support/Composer.php (lines ~16 and ~48) with ->filter(is_dir(...))

The filter() method passes both value and key to the callback, but is_dir() only accepts one argument. This was causing an ArgumentCountError when running boost:install. Changed from is_dir(...) to explicit closure: fn (string $path): bool => is_dir($path)

Signed-off-by: Pushpak Chhajed <[email protected]>

joetannenbaum

Made some formatting and method name adjustments.

NIAN97 added 2 commits October 19, 2025 00:45

pushpak1300 reviewed Oct 19, 2025

View reviewed changes

src/Install/CodeEnvironment/CodeEnvironment.php Outdated Show resolved Hide resolved

pushpak1300 changed the title ~~Feature/sail auto detection~~ [1.x] Sail Support for Boost Oct 19, 2025

NIAN97 added 2 commits October 19, 2025 16:05

chore: Remove PR_DESCRIPTION.md

7121ab2

This file was only needed locally for creating the PR. Not required in the repository.

pushpak1300 self-assigned this Oct 27, 2025

pushpak1300 mentioned this pull request Oct 27, 2025

fix: detect if project uses sail #83

Closed

Merge branch 'main' into feature/sail-auto-detection

25a242c

Merge branch 'main' into feature/sail-auto-detection

93a79d7

pushpak1300 and others added 4 commits October 29, 2025 20:30

wip

5562d04

Signed-off-by: Pushpak Chhajed <[email protected]>

add Sail detection logic

74fb9cf

Signed-off-by: Pushpak Chhajed <[email protected]>

Revert README.md changes

0a4ea47

Signed-off-by: Pushpak Chhajed <[email protected]>

Merge branch 'main' into feature/sail-auto-detection

da7b538

NIAN97 and others added 4 commits October 31, 2025 01:14

run rector

0a8d751

Signed-off-by: Pushpak Chhajed <[email protected]>

Improve sail detection

5b9e055

Signed-off-by: Pushpak Chhajed <[email protected]>

Simplify Sail path handling

fc10db4

Signed-off-by: Pushpak Chhajed <[email protected]>

pushpak1300 approved these changes Oct 31, 2025

View reviewed changes

pushpak1300 requested a review from joetannenbaum October 31, 2025 09:27

pushpak1300 removed their assignment Oct 31, 2025

pushpak1300 added the docker label Oct 31, 2025

pushpak1300 linked an issue Oct 31, 2025 that may be closed by this pull request

Laravel Sail #105

Closed

pushpak1300 requested review from joetannenbaum and removed request for joetannenbaum October 31, 2025 09:28

wip

77ac357

joetannenbaum approved these changes Oct 31, 2025

View reviewed changes

pushpak1300 merged commit cf2414d into laravel:main Oct 31, 2025
17 checks passed

[1.x] Sail Support for Boost #303

[1.x] Sail Support for Boost #303

Uh oh!

Conversation

NIAN97 commented Oct 19, 2025 • edited by pushpak1300 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Add Automatic Laravel Sail Detection for MCP Server Configuration

Summary

Motivation

Problem

Solution

EDIT

Uh oh!

Uh oh!

MltStephane commented Oct 19, 2025

Uh oh!

NIAN97 commented Oct 19, 2025

Uh oh!

MltStephane commented Oct 19, 2025

Uh oh!

NIAN97 commented Oct 19, 2025

Uh oh!

MltStephane commented Oct 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

NIAN97 commented Oct 19, 2025

Uh oh!

MltStephane commented Oct 20, 2025

Uh oh!

MltStephane commented Oct 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

NIAN97 commented Oct 26, 2025

Uh oh!

pushpak1300 commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

MltStephane commented Oct 28, 2025

Uh oh!

pushpak1300 commented Oct 28, 2025

Uh oh!

MltStephane commented Oct 28, 2025

Uh oh!

pushpak1300 commented Oct 29, 2025

Uh oh!

chinmaypurav commented Oct 29, 2025

Uh oh!

MltStephane commented Oct 29, 2025

Uh oh!

pushpak1300 commented Oct 29, 2025

Uh oh!

MltStephane commented Oct 29, 2025

Uh oh!

chinmaypurav commented Oct 29, 2025

Uh oh!

NIAN97 commented Oct 29, 2025

Uh oh!

pushpak1300 commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

NIAN97 commented Oct 30, 2025

Uh oh!

joetannenbaum left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

NIAN97 commented Oct 19, 2025 •

edited by pushpak1300

Loading

MltStephane commented Oct 19, 2025 •

edited

Loading

MltStephane commented Oct 20, 2025 •

edited

Loading

pushpak1300 commented Oct 28, 2025 •

edited

Loading

pushpak1300 commented Oct 30, 2025 •

edited

Loading