Add Laravel Boost support (#184)

* Add Laravel Boost guidelines and skills

* Add spin-mcp-wait.sh script for Laravel Boost MCP setup and update documentation

- Added spin-mcp-wait.sh to composer.json and package.json for improved MCP server startup.
- Updated core.blade.php and SKILL.md to include instructions for configuring Laravel Boost with the new script.
- Emphasized the correct usage of spin-mcp-wait.sh to avoid misuse during command execution.

Author: jaydrogers

bin/spin-mcp-wait.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+#
+# MCP stdio bridge for Spin + Laravel Boost.
+#
+# Solves two problems when running Boost's MCP server inside Docker:
+# 1. Cursor/IDEs start MCP servers on launch — Docker may not be ready yet.
+#    This script retries until the container is available.
+# 2. Docker outputs startup noise (ANSI codes, container messages) that
+#    corrupts the JSON-RPC stdio protocol. This script filters stdout to
+#    pass only JSON-RPC messages.
+#
+# Usage (in .env):
+#   BOOST_PHP_EXECUTABLE_PATH="./vendor/bin/spin-mcp-wait.sh ./vendor/bin/spin run -T php php"
+#
+# This script is ONLY for MCP server startup. For all other commands, use
+# spin directly: spin run php composer install
+
+set -euo pipefail
+
+is_mcp=0
+for arg in "$@"; do
+    [ "$arg" = "boost:mcp" ] && is_mcp=1 && break
+done
+
+if [ "$is_mcp" -eq 0 ]; then
+    echo "Error: spin-mcp-wait.sh is only for starting the MCP server." >&2
+    echo "Use 'spin' directly instead. Example: spin run php composer install" >&2
+    exit 1
+fi
+
+MAX_RETRIES=${SPIN_MCP_MAX_RETRIES:-60}
+SLEEP_SECONDS=${SPIN_MCP_RETRY_INTERVAL:-5}
+attempt=0
+
+while [ $attempt -lt $MAX_RETRIES ]; do
+    "$@" 2>/dev/null | grep --line-buffered '^{'
+    exit_code="${PIPESTATUS[0]}"
+
+    [ "$exit_code" -eq 0 ] && exit 0
+    [ "$exit_code" -gt 128 ] && exit "$exit_code"
+
+    attempt=$((attempt + 1))
+    echo "spin-mcp-wait: attempt $attempt/$MAX_RETRIES failed (exit $exit_code), retrying in ${SLEEP_SECONDS}s..." >&2
+    sleep "$SLEEP_SECONDS"
+done
+
+echo "spin-mcp-wait: gave up after $MAX_RETRIES attempts." >&2
+echo "spin-mcp-wait: Is Docker Desktop running?" >&2
+exit 1

composer.json

@@ -2,7 +2,8 @@
     "name": "serversideup/spin",
     "description": "Replicate your production environment locally using Docker. Just run \"spin up\". It's really that easy.",
     "bin": [
-        "bin/spin"
+        "bin/spin",
+        "bin/spin-mcp-wait.sh"
       ],
     "authors": [
         {

package.json

@@ -13,6 +13,7 @@
   },
   "homepage": "https://github.com/serversideup/spin#readme",
   "bin": {
-    "spin": "./bin/spin"
+    "spin": "./bin/spin",
+    "spin-mcp-wait.sh": "./bin/spin-mcp-wait.sh"
   }
 }

resources/boost/guidelines/core.blade.php

@@ -0,0 +1,62 @@
+# Spin — Docker Workflow for Laravel
+
+Spin is a lightweight CLI that wraps Docker Compose (development) and Docker Swarm (production) so you can replicate any environment on any machine.
+
+## Key facts
+
+- Spin follows Docker Compose syntax exactly — `spin up` runs `docker compose up`, `spin run` runs `docker compose run`, etc.
+- Projects use a **Docker Compose overrides** pattern: a base `docker-compose.yml` merged with `docker-compose.dev.yml` (local) or `docker-compose.prod.yml` (production).
+- Laravel projects use `serversideup/php` Docker images (fpm-nginx, fpm-apache, frankenphp, cli).
+- The `.infrastructure/` folder stores configuration files (`conf/`) and gitignored volume data (`volume_data/`).
+- `SPIN_ENV` defaults to `dev`. Running `spin up` uses `docker-compose.yml` + `docker-compose.dev.yml`.
+- In Docker, services connect via container name as hostname (`DB_HOST=mysql`, `REDIS_HOST=redis`), not `localhost`.
+
+## Essential commands
+
+| Command | Purpose |
+|---------|---------|
+| `spin up` | Start development environment (foreground) |
+| `spin up --build` | Start and rebuild containers (recommended default if custom Dockerfile is used) |
+| `spin run <service> <cmd>` | Run a one-off command in a new container |
+| `spin exec <service> <cmd>` | Run a command in a running container |
+| `spin deploy <env>` | Deploy to a provisioned server |
+| `spin provision` | Provision and configure servers |
+
+## When to activate the full skill
+
+For tasks involving Docker Compose configuration, Dockerfile changes, `serversideup/php` image settings, adding Laravel services (databases, queues, Horizon, Reverb), server provisioning, deployment, or troubleshooting containerized environments — activate the **spin-laravel-development** skill.
+
+## Laravel Boost MCP setup
+
+Since Spin runs PHP inside Docker (not on the host), Laravel Boost needs special configuration to start its MCP server. Spin ships `spin-mcp-wait.sh` which retries until Docker is ready and filters stdout for clean JSON-RPC communication.
+
+Add these to your `.env` file:
+
+```
+BOOST_PHP_EXECUTABLE_PATH="./vendor/bin/spin-mcp-wait.sh ./vendor/bin/spin run -T php php"
+BOOST_COMPOSER_EXECUTABLE_PATH="./vendor/bin/spin run php composer"
+BOOST_NPM_EXECUTABLE_PATH="./vendor/bin/spin run node npm"
+```
+
+Then run:
+
+```
+spin run php php artisan boost:install
+```
+
+**IMPORTANT:** `spin-mcp-wait.sh` is exclusively for MCP server startup. NEVER use it to run commands. Always use `spin run` or `spin exec` for running commands (e.g., `spin run php composer install`).
+
+## Templates
+
+- **Basic** (`spin new laravel`): Free open source template — <https://github.com/serversideup/spin-template-laravel-basic>
+- **Pro** (`spin new laravel-pro`): Premium template with pre-configured services (Horizon, Reverb, databases, Vite, Mailpit, etc.) — <https://getspin.pro>
+
+## Resources
+
+- Spin docs: <https://serversideup.net/open-source/spin/docs>
+- Spin docs (LLM-friendly): <https://serversideup.net/open-source/spin/llms.txt>
+- serversideup/php docs: <https://serversideup.net/open-source/docker-php/docs>
+- serversideup/php docs (LLM-friendly): <https://serversideup.net/open-source/docker-php/llms.txt>
+- serversideup/php full docs (LLM-friendly): <https://serversideup.net/open-source/docker-php/llms-full.txt>
+- serversideup/php environment variable reference: <https://serversideup.net/open-source/docker-php/docs/reference/environment-variable-specification>
+- Spin Pro docs: <https://getspin.pro/docs>