@kennethsolomon/shipkit 3.20.0 → 3.21.0

package/README.md

@@ -365,7 +365,9 @@ Rule files in `.claude/rules/` auto-activate in Claude Code when you edit matchi
 
 ## MCP Servers
 
-Installed optionally by `/sk:setup-claude` and `/sk:setup-optimizer`.
+### Global (opt-in, installed to `~/.mcp.json`)
+
+Installed by `/sk:setup-claude` and `/sk:setup-optimizer` when you opt in.
 
 | Server | What it does | Best for |
 |---|---|---|
@@ -373,6 +375,14 @@ Installed optionally by `/sk:setup-claude` and `/sk:setup-optimizer`.
 | **context7** | Fetches current, version-accurate docs for libraries you're using — no stale API suggestions | React 19, Next.js 15, Tailwind v4, shadcn/ui |
 | **ccstatusline** | Persistent statusline: context window %, model, git branch, current task | Every session |
 
+### Project-level (stack-conditional, installed to `.mcp.json`)
+
+Added/removed automatically based on detected stack. No opt-in required.
+
+| Server | Stack | What it does |
+|---|---|---|
+| **laravel-boost** | Laravel | Database schema, read-only queries, docs search (version-matched), application logs, browser errors, last exception, Eloquent model list |
+
 ---
 
 ## On-Demand Tools

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kennethsolomon/shipkit",
-  "version": "3.20.0",
+  "version": "3.21.0",
   "description": "A structured workflow toolkit for Claude Code.",
   "keywords": [
     "claude",

package/skills/sk:laravel-init/SKILL.md

@@ -12,13 +12,14 @@ Configure this Laravel project with production-ready conventions. Safe to run on
 Invokes the `setup-claude` skill to:
 
 1. **Detect stack** from `composer.json` + `package.json`
-2. **Install missing dev tools**: PHPStan/Larastan, Rector, Pint, Pest
-3. **Publish config files** (if missing): `phpstan.neon`, `rector.php`, `pint.json`
-4. **Configure strict models** in `AppServiceProvider`
-5. **Generate `CLAUDE.md`** — stack-aware, with full workflow, conventions, and sub-agent patterns
-6. **Bootstrap `tasks/`** — findings, lessons, todo, progress, security-findings
-7. **Generate `.claude/commands/`** — lint, test
-8. **Pre-seed `tasks/findings.md`** with detected stack info
+2. **Install missing dev tools**: PHPStan/Larastan, Rector, Pint, Pest, Laravel Boost
+3. **Configure Laravel Boost MCP** in `.mcp.json` — database schema, queries, docs search, logs, browser errors
+4. **Publish config files** (if missing): `phpstan.neon`, `rector.php`, `pint.json`
+5. **Configure strict models** in `AppServiceProvider`
+6. **Generate `CLAUDE.md`** — stack-aware, with full workflow, conventions, and sub-agent patterns
+7. **Bootstrap `tasks/`** — findings, lessons, todo, progress, security-findings
+8. **Generate `.claude/commands/`** — lint, test
+9. **Pre-seed `tasks/findings.md`** with detected stack info
 
 ## Idempotent
 

package/skills/sk:laravel-new/SKILL.md

@@ -54,6 +54,7 @@ Location: [path]
 
 Files created:
   CLAUDE.md
+  .mcp.json (laravel-boost MCP server)
   phpstan.neon
   rector.php
   pint.json

package/skills/sk:setup-claude/SKILL.md

@@ -277,8 +277,59 @@ composer require --dev laravel/pint
 # Pest (if missing)
 composer require --dev pestphp/pest pestphp/pest-plugin-laravel
 ./vendor/bin/pest --init
+
+# Laravel Boost MCP (if missing) — provides database schema, queries, docs search, logs, browser errors
+composer require --dev laravel/boost
+```
+
+### Laravel Boost MCP Configuration
+
+**Do NOT run `php artisan boost:install`** — it generates its own CLAUDE.md and skills that conflict with ShipKit-managed files. We configure the MCP server entry directly.
+
+After installing `laravel/boost`, configure the MCP server in the project's `.mcp.json` (create-if-missing, merge additively):
+
+```json
+{
+  "mcpServers": {
+    "laravel-boost": {
+      "command": "php",
+      "args": ["artisan", "boost:mcp"],
+      "env": {}
+    }
+  }
+}
 ```
 
+For **Laravel Sail** projects (detected by `vendor/bin/sail` existing), use:
+
+```json
+{
+  "mcpServers": {
+    "laravel-boost": {
+      "command": "vendor/bin/sail",
+      "args": ["artisan", "boost:mcp"],
+      "env": {}
+    }
+  }
+}
+```
+
+**Idempotency:** If `laravel-boost` already exists in `.mcp.json`, check whether the command matches the current Sail status. If `vendor/bin/sail` exists but the entry uses `php` (or vice versa), update the entry to match. Otherwise skip.
+
+**What Boost MCP provides (9 tools):**
+
+| Tool | Purpose |
+|------|---------|
+| ApplicationInfo | PHP/Laravel version, DB engine, installed packages, Eloquent models |
+| DatabaseSchema | Full schema — tables, columns, indexes, foreign keys (summary + filter modes) |
+| DatabaseQuery | Read-only SQL queries (SELECT, SHOW, EXPLAIN, DESCRIBE only) |
+| DatabaseConnections | All configured DB connections and the default |
+| SearchDocs | Laravel ecosystem docs (Laravel, Pest, Livewire, Filament, Tailwind, Inertia) |
+| ReadLogEntries | Last N log entries (PSR-3 and JSON format) |
+| BrowserLogs | Browser console errors/warnings from `storage/logs/browser.log` |
+| LastError | Last exception from cache or log file |
+| GetAbsoluteUrl | Convert relative paths or named routes to absolute URLs |
+
 ### Laravel Official Plugins
 
 After tool installation, suggest the two official Laravel plugins from Taylor Otwell:

package/skills/sk:setup-claude/references/skill-profiles.md

@@ -1,9 +1,9 @@
 # ShipKit Skill Profiles — Stack-Based Filtering
 
-**Last Updated:** 2026-03-29
-**Total Skills:** 44 | **Agents:** 13 | **Rules:** 6
+**Last Updated:** 2026-03-30
+**Total Skills:** 44 | **Agents:** 13 | **Rules:** 6 | **Project MCP:** 1
 
-This file is the source of truth for which skills, agents, and rules get installed per project. Read by `sk:setup-claude` (initial setup) and `sk:setup-optimizer` (ongoing sync).
+This file is the source of truth for which skills, agents, rules, and project-level MCP servers get installed per project. Read by `sk:setup-claude` (initial setup) and `sk:setup-optimizer` (ongoing sync).
 
 ---
 
@@ -179,6 +179,24 @@ These are installed universally because they run inside `sk:gates`. Perf auto-sk
 
 ---
 
+## Project-Level MCP Server → Stack Mapping
+
+MCP servers configured in the project's `.mcp.json` (not global `~/.mcp.json`). Managed by `sk:setup-claude` (initial setup) and `sk:setup-optimizer` (ongoing sync).
+
+| MCP Server | Stack | Command | Purpose |
+|-----------|-------|---------|---------|
+| laravel-boost | laravel | `php artisan boost:mcp` (or `vendor/bin/sail artisan boost:mcp` for Sail) | Database schema, queries, docs search, logs, browser errors |
+
+**Sync rules:**
+- **Add** to `.mcp.json` when stack matches and entry is missing
+- **Remove** from `.mcp.json` when stack no longer matches (e.g., project switched from Laravel to Next.js)
+- **Update** existing entry if command is stale (e.g., Sail added/removed — switch between `php` and `vendor/bin/sail`)
+- Never touch MCP entries not in this table (user-added entries are preserved)
+- Sail detection: use `vendor/bin/sail` command variant if `vendor/bin/sail` exists
+- **Ownership:** Project-level MCP is managed by `sk:setup-claude` (initial) and `sk:setup-optimizer` Step 0.5 (ongoing). Step 1.7 handles only global MCP.
+
+---
+
 ## Installation Formula
 
 For a given project with detected `stack` and `capabilities`:
@@ -196,6 +214,10 @@ installed_agents = universal_agents
 
 installed_rules  = universal_rules (tests.md)
                  + stack_matching_rules(stack, capabilities)
+
+project_mcp      = stack_matching_mcp(stack)
+                 # Add matching entries to .mcp.json
+                 # Remove non-matching entries from .mcp.json (only managed entries — never touch user-added)
 ```
 
 User overrides (`extra`, `disabled`) are never touched by auto-detection.

package/skills/sk:setup-claude/scripts/apply_setup_claude.py

@@ -58,6 +58,14 @@ def _has_dep(pkg: dict, name: str) -> bool:
     return name in deps
 
 
+def _has_composer_dep(composer: dict, name: str) -> bool:
+    """Check if a Composer package is in require or require-dev."""
+    deps = {}
+    for key in ("require", "require-dev"):
+        deps.update(composer.get(key, {}) or {})
+    return name in deps
+
+
 def _any_dep_prefix(pkg: dict, prefix: str) -> bool:
     deps = {}
     for key in ("dependencies", "devDependencies", "peerDependencies", "optionalDependencies"):
@@ -107,13 +115,16 @@ def _write_cached_detection(repo_root: Path, detection: Detection) -> None:
 
 def detect(repo_root: Path) -> Detection:
     package_json = _read_json(repo_root / "package.json") or {}
+    composer_json = _read_json(repo_root / "composer.json") or {}
     scripts = (package_json.get("scripts") or {}) if isinstance(package_json, dict) else {}
 
     project_name = str(package_json.get("name") or repo_root.name)
     description = str(package_json.get("description") or "Project instructions for Claude Code.")
 
-    # Language
-    if (repo_root / "tsconfig.json").exists() or _has_dep(package_json, "typescript"):
+    # Language — composer.json with laravel/framework takes priority over package.json
+    if _has_composer_dep(composer_json, "laravel/framework"):
+        language = "PHP"
+    elif (repo_root / "tsconfig.json").exists() or _has_dep(package_json, "typescript"):
         language = "TypeScript"
     elif (repo_root / "package.json").exists():
         language = "JavaScript"
@@ -129,7 +140,21 @@ def detect(repo_root: Path) -> Detection:
         language = "Unknown"
 
     # Framework (keep simple; expand later)
-    if _has_dep(package_json, "next"):
+    is_laravel = _has_composer_dep(composer_json, "laravel/framework")
+    if is_laravel:
+        # Sub-detect Laravel stack flavor
+        if _has_composer_dep(composer_json, "inertiajs/inertia-laravel"):
+            if _has_dep(package_json, "react"):
+                framework = "Laravel (Inertia + React)"
+            elif _has_dep(package_json, "vue"):
+                framework = "Laravel (Inertia + Vue)"
+            else:
+                framework = "Laravel (Inertia)"
+        elif _has_composer_dep(composer_json, "livewire/livewire"):
+            framework = "Laravel (Livewire)"
+        else:
+            framework = "Laravel (API)"
+    elif _has_dep(package_json, "next"):
         framework = "Next.js (App Router)"
     elif _has_dep(package_json, "react"):
         framework = "React"
@@ -139,7 +164,9 @@ def detect(repo_root: Path) -> Detection:
         framework = "Unknown"
 
     # Database / ORM
-    if _has_dep(package_json, "drizzle-orm"):
+    if is_laravel and (repo_root / "database" / "migrations").exists():
+        database = "Eloquent ORM"
+    elif _has_dep(package_json, "drizzle-orm"):
         if _has_dep(package_json, "better-sqlite3"):
             database = "Drizzle ORM + SQLite"
         elif _has_dep(package_json, "pg"):
@@ -165,7 +192,9 @@ def detect(repo_root: Path) -> Detection:
         ui = "Unknown"
 
     # Testing
-    if _has_dep(package_json, "vitest"):
+    if _has_composer_dep(composer_json, "pestphp/pest"):
+        testing = "Pest"
+    elif _has_dep(package_json, "vitest"):
         testing = "Vitest"
     elif _has_dep(package_json, "jest"):
         testing = "Jest"
@@ -190,10 +219,16 @@ def detect(repo_root: Path) -> Detection:
     else:
         browser_automation = "None"
 
-    dev_cmd = scripts.get("dev") and "npm run dev" or "npm run dev"
-    build_cmd = scripts.get("build") and "npm run build" or "npm run build"
-    lint_cmd = scripts.get("lint") and "npm run lint" or "npm run lint"
-    test_cmd = scripts.get("test") and "npm test" or "npm test"
+    if is_laravel:
+        dev_cmd = "php artisan serve"
+        build_cmd = "npm run build"
+        lint_cmd = "vendor/bin/pint"
+        test_cmd = "vendor/bin/pest"
+    else:
+        dev_cmd = scripts.get("dev") and "npm run dev" or "npm run dev"
+        build_cmd = scripts.get("build") and "npm run build" or "npm run build"
+        lint_cmd = scripts.get("lint") and "npm run lint" or "npm run lint"
+        test_cmd = scripts.get("test") and "npm test" or "npm test"
 
     typo_dir = repo_root / ".claude" / "docs" / "achritectural_change_log"
     correct_dir = repo_root / ".claude" / "docs" / "architectural_change_log"
@@ -413,7 +448,7 @@ def _rules_filter(detection: Detection):
     def _filter(filename: str) -> bool:
         if filename in always:
             return True
-        if filename == "laravel.md.template" and "Laravel" in detection.framework:
+        if filename == "laravel.md.template" and detection.framework.startswith("Laravel"):
             return True
         if filename == "react.md.template" and (
             "React" in detection.framework or detection.framework == "Next.js (App Router)"
@@ -424,6 +459,67 @@ def _rules_filter(detection: Detection):
     return _filter
 
 
+# Stack-conditional MCP server mapping (managed entries only)
+_MANAGED_MCP_SERVERS: Dict[str, dict] = {
+    "laravel-boost": {
+        "stack_prefix": "Laravel",
+        "command": "php",
+        "args": ["artisan", "boost:mcp"],
+        "sail_command": "vendor/bin/sail",
+    },
+}
+
+
+def _deploy_project_mcp(
+    repo_root: Path,
+    detection: Detection,
+    *,
+    dry_run: bool,
+) -> List[tuple]:
+    """Add/remove/update managed MCP entries in .mcp.json based on detected stack."""
+    mcp_path = repo_root / ".mcp.json"
+    results: List[tuple] = []
+
+    existing = _read_json(mcp_path) or {}
+    servers = existing.get("mcpServers", {})
+    changed = False
+
+    for name, config in _MANAGED_MCP_SERVERS.items():
+        stack_matches = detection.framework.startswith(config["stack_prefix"])
+        use_sail = (repo_root / "vendor" / "bin" / "sail").exists()
+        command = config["sail_command"] if use_sail else config["command"]
+        expected_entry = {"command": command, "args": config["args"], "env": {}}
+
+        if stack_matches:
+            if name not in servers:
+                servers[name] = expected_entry
+                changed = True
+            elif servers[name].get("command") != command:
+                # Sail status changed — update command
+                servers[name]["command"] = command
+                changed = True
+        else:
+            if name in servers:
+                del servers[name]
+                changed = True
+
+    if not changed:
+        results.append(("skipped", mcp_path))
+        return results
+
+    if dry_run:
+        action = "updated" if mcp_path.exists() else "created"
+        results.append((action, mcp_path))
+        return results
+
+    existing["mcpServers"] = servers
+    mcp_path.parent.mkdir(parents=True, exist_ok=True)
+    mcp_path.write_text(json.dumps(existing, indent=2) + "\n", encoding="utf-8")
+    action = "updated" if mcp_path.exists() else "created"
+    results.append((action, mcp_path))
+    return results
+
+
 def apply(
     repo_root: Path,
     skill_root: Path,
@@ -571,6 +667,10 @@ def apply(
             action_sl = "created"
         _collect_results([(action_sl, statusline_dest)], repo_root, created, updated, skipped)
 
+    # --- Deploy project-level .mcp.json (stack-conditional) ---
+    mcp_results = _deploy_project_mcp(repo_root, detection, dry_run=dry_run)
+    _collect_results(mcp_results, repo_root, created, updated, skipped)
+
     if dry_run:
         print("setup-claude dry-run complete (no files written)")
     else:

package/skills/sk:setup-claude/templates/.claude/rules/laravel.md.template

@@ -19,6 +19,20 @@ paths:
 - **Config**: Access config via `config()` helper, never `env()` outside config files.
 - **Strict mode**: Models use strict mode (prevent lazy loading, silently discarding attributes, accessing missing attributes).
 
+## Laravel Boost MCP
+
+Project MCP server auto-configured in `.mcp.json` by `/sk:laravel-init`. Provides 9 tools Claude can call directly:
+
+| Tool | When to use |
+|------|-------------|
+| `DatabaseSchema` | Before writing migrations or queries — get exact column types, indexes, FKs |
+| `DatabaseQuery` | Run read-only SELECTs to validate data assumptions |
+| `SearchDocs` | Look up Laravel/Livewire/Filament/Pest docs matched to your installed versions |
+| `ReadLogEntries` | Check recent errors without leaving Claude |
+| `BrowserLogs` | Inspect browser console errors captured server-side |
+| `LastError` | Get the last exception instantly |
+| `ApplicationInfo` | Check installed packages and Eloquent models at session start |
+
 ## Code Refinement
 
 After running `/sk:execute-plan`, use the `laravel-simplifier` agent to refine recently modified PHP/Laravel code:

package/skills/sk:setup-claude/tests/test_apply_setup_claude.py

@@ -158,5 +158,272 @@ class TestApplySetupClaude(unittest.TestCase):
             self.assertIn("Notes:", buf.getvalue())
 
 
+    def test_laravel_detection_inertia_react(self):
+        mod = _load_apply_module()
+
+        with tempfile.TemporaryDirectory() as td:
+            repo_root = Path(td)
+            (repo_root / "composer.json").write_text(
+                json.dumps({
+                    "require": {"laravel/framework": "^12.0"},
+                    "require-dev": {
+                        "pestphp/pest": "^3.0",
+                        "inertiajs/inertia-laravel": "^2.0",
+                    },
+                }),
+                encoding="utf-8",
+            )
+            (repo_root / "package.json").write_text(
+                json.dumps({"dependencies": {"react": "^19.0"}}),
+                encoding="utf-8",
+            )
+            (repo_root / "database" / "migrations").mkdir(parents=True)
+
+            detection = mod.detect(repo_root)
+            self.assertEqual(detection.framework, "Laravel (Inertia + React)")
+            self.assertEqual(detection.language, "PHP")
+            self.assertEqual(detection.database, "Eloquent ORM")
+            self.assertEqual(detection.testing, "Pest")
+            self.assertEqual(detection.dev_cmd, "php artisan serve")
+            self.assertEqual(detection.lint_cmd, "vendor/bin/pint")
+            self.assertEqual(detection.test_cmd, "vendor/bin/pest")
+
+    def test_laravel_detection_livewire(self):
+        mod = _load_apply_module()
+
+        with tempfile.TemporaryDirectory() as td:
+            repo_root = Path(td)
+            (repo_root / "composer.json").write_text(
+                json.dumps({
+                    "require": {
+                        "laravel/framework": "^12.0",
+                        "livewire/livewire": "^3.0",
+                    },
+                }),
+                encoding="utf-8",
+            )
+
+            detection = mod.detect(repo_root)
+            self.assertEqual(detection.framework, "Laravel (Livewire)")
+
+    def test_laravel_detection_api_only(self):
+        mod = _load_apply_module()
+
+        with tempfile.TemporaryDirectory() as td:
+            repo_root = Path(td)
+            (repo_root / "composer.json").write_text(
+                json.dumps({"require": {"laravel/framework": "^12.0"}}),
+                encoding="utf-8",
+            )
+
+            detection = mod.detect(repo_root)
+            self.assertEqual(detection.framework, "Laravel (API)")
+
+    def test_mcp_json_created_for_laravel(self):
+        mod = _load_apply_module()
+        skill_root = Path(__file__).resolve().parents[1]
+
+        with tempfile.TemporaryDirectory() as td:
+            repo_root = Path(td)
+            (repo_root / "composer.json").write_text(
+                json.dumps({"require": {"laravel/framework": "^12.0"}}),
+                encoding="utf-8",
+            )
+
+            buf = io.StringIO()
+            with contextlib.redirect_stdout(buf):
+                mod.apply(
+                    repo_root,
+                    skill_root,
+                    update_generated=False,
+                    dry_run=False,
+                    detection=mod.detect(repo_root),
+                )
+
+            mcp_path = repo_root / ".mcp.json"
+            self.assertTrue(mcp_path.exists())
+            mcp_data = json.loads(mcp_path.read_text(encoding="utf-8"))
+            self.assertIn("laravel-boost", mcp_data["mcpServers"])
+            self.assertEqual(mcp_data["mcpServers"]["laravel-boost"]["command"], "php")
+
+    def test_mcp_json_not_created_for_nextjs(self):
+        mod = _load_apply_module()
+        skill_root = Path(__file__).resolve().parents[1]
+
+        with tempfile.TemporaryDirectory() as td:
+            repo_root = Path(td)
+            (repo_root / "package.json").write_text(
+                json.dumps({
+                    "name": "demo",
+                    "dependencies": {"next": "15.0.0", "react": "19.0.0"},
+                }),
+                encoding="utf-8",
+            )
+
+            buf = io.StringIO()
+            with contextlib.redirect_stdout(buf):
+                mod.apply(
+                    repo_root,
+                    skill_root,
+                    update_generated=False,
+                    dry_run=False,
+                    detection=mod.detect(repo_root),
+                )
+
+            mcp_path = repo_root / ".mcp.json"
+            if mcp_path.exists():
+                mcp_data = json.loads(mcp_path.read_text(encoding="utf-8"))
+                self.assertNotIn("laravel-boost", mcp_data.get("mcpServers", {}))
+
+    def test_mcp_json_removed_when_stack_changes(self):
+        mod = _load_apply_module()
+        skill_root = Path(__file__).resolve().parents[1]
+
+        with tempfile.TemporaryDirectory() as td:
+            repo_root = Path(td)
+
+            # Start with Laravel — creates .mcp.json with laravel-boost
+            (repo_root / "composer.json").write_text(
+                json.dumps({"require": {"laravel/framework": "^12.0"}}),
+                encoding="utf-8",
+            )
+            laravel_detection = mod.detect(repo_root)
+
+            buf = io.StringIO()
+            with contextlib.redirect_stdout(buf):
+                mod.apply(
+                    repo_root,
+                    skill_root,
+                    update_generated=False,
+                    dry_run=False,
+                    detection=laravel_detection,
+                )
+
+            mcp_path = repo_root / ".mcp.json"
+            self.assertTrue(mcp_path.exists())
+            mcp_data = json.loads(mcp_path.read_text(encoding="utf-8"))
+            self.assertIn("laravel-boost", mcp_data["mcpServers"])
+
+            # Switch to Next.js — laravel-boost should be removed
+            (repo_root / "composer.json").unlink()
+            (repo_root / "package.json").write_text(
+                json.dumps({
+                    "name": "demo",
+                    "dependencies": {"next": "15.0.0", "react": "19.0.0"},
+                }),
+                encoding="utf-8",
+            )
+            nextjs_detection = mod.detect(repo_root)
+
+            buf = io.StringIO()
+            with contextlib.redirect_stdout(buf):
+                mod.apply(
+                    repo_root,
+                    skill_root,
+                    update_generated=False,
+                    dry_run=False,
+                    detection=nextjs_detection,
+                )
+
+            mcp_data = json.loads(mcp_path.read_text(encoding="utf-8"))
+            self.assertNotIn("laravel-boost", mcp_data.get("mcpServers", {}))
+
+    def test_mcp_json_sail_detection(self):
+        mod = _load_apply_module()
+        skill_root = Path(__file__).resolve().parents[1]
+
+        with tempfile.TemporaryDirectory() as td:
+            repo_root = Path(td)
+            (repo_root / "composer.json").write_text(
+                json.dumps({"require": {"laravel/framework": "^12.0"}}),
+                encoding="utf-8",
+            )
+            # Simulate Sail being present
+            (repo_root / "vendor" / "bin").mkdir(parents=True)
+            (repo_root / "vendor" / "bin" / "sail").write_text("#!/bin/sh\n", encoding="utf-8")
+
+            buf = io.StringIO()
+            with contextlib.redirect_stdout(buf):
+                mod.apply(
+                    repo_root,
+                    skill_root,
+                    update_generated=False,
+                    dry_run=False,
+                    detection=mod.detect(repo_root),
+                )
+
+            mcp_path = repo_root / ".mcp.json"
+            mcp_data = json.loads(mcp_path.read_text(encoding="utf-8"))
+            self.assertEqual(
+                mcp_data["mcpServers"]["laravel-boost"]["command"],
+                "vendor/bin/sail",
+            )
+
+    def test_mcp_json_preserves_user_entries(self):
+        mod = _load_apply_module()
+        skill_root = Path(__file__).resolve().parents[1]
+
+        with tempfile.TemporaryDirectory() as td:
+            repo_root = Path(td)
+            (repo_root / "composer.json").write_text(
+                json.dumps({"require": {"laravel/framework": "^12.0"}}),
+                encoding="utf-8",
+            )
+
+            # Pre-existing user MCP entry
+            (repo_root / ".mcp.json").write_text(
+                json.dumps({
+                    "mcpServers": {
+                        "my-custom-server": {"command": "node", "args": ["server.js"]},
+                    },
+                }),
+                encoding="utf-8",
+            )
+
+            buf = io.StringIO()
+            with contextlib.redirect_stdout(buf):
+                mod.apply(
+                    repo_root,
+                    skill_root,
+                    update_generated=False,
+                    dry_run=False,
+                    detection=mod.detect(repo_root),
+                )
+
+            mcp_data = json.loads((repo_root / ".mcp.json").read_text(encoding="utf-8"))
+            self.assertIn("my-custom-server", mcp_data["mcpServers"])
+            self.assertIn("laravel-boost", mcp_data["mcpServers"])
+
+    def test_laravel_rules_filter(self):
+        mod = _load_apply_module()
+
+        with tempfile.TemporaryDirectory() as td:
+            repo_root = Path(td)
+            (repo_root / "composer.json").write_text(
+                json.dumps({"require": {"laravel/framework": "^12.0"}}),
+                encoding="utf-8",
+            )
+            detection = mod.detect(repo_root)
+            rule_filter = mod._rules_filter(detection)
+            self.assertTrue(rule_filter("laravel.md.template"))
+            self.assertTrue(rule_filter("tests.md.template"))
+
+    def test_nextjs_rules_filter_excludes_laravel(self):
+        mod = _load_apply_module()
+
+        with tempfile.TemporaryDirectory() as td:
+            repo_root = Path(td)
+            (repo_root / "package.json").write_text(
+                json.dumps({
+                    "dependencies": {"next": "15.0.0", "react": "19.0.0"},
+                }),
+                encoding="utf-8",
+            )
+            detection = mod.detect(repo_root)
+            rule_filter = mod._rules_filter(detection)
+            self.assertFalse(rule_filter("laravel.md.template"))
+            self.assertTrue(rule_filter("react.md.template"))
+
+
 if __name__ == "__main__":
     unittest.main()

package/skills/sk:setup-optimizer/SKILL.md

@@ -89,6 +89,10 @@ Rule changes:
   + migrations.md  (database paths)
   No removals.
 
+Project MCP changes:
+  - laravel-boost  (stack is no longer laravel)
+  No additions.
+
 Apply changes? (y/n)
 ```
 
@@ -114,6 +118,13 @@ If the user confirms:
 - Remove stale rules: delete from `.claude/rules/` in the project if they no longer match
 - Never remove user-customized rules (same detection as agents)
 
+**Project-level MCP sync** (sole owner of `.mcp.json` managed entries — Step 1.7 only handles global MCP):
+- Read the MCP Server → Stack Mapping from `skill-profiles.md`
+- **Add:** MCP entries to `.mcp.json` when stack matches and entry is missing
+- **Remove:** MCP entries from `.mcp.json` when stack no longer matches (e.g., `laravel-boost` removed if stack changed from Laravel to Next.js). Only remove entries whose key matches the mapping table — never touch other entries.
+- **Update:** If entry exists but command is stale (e.g., Sail added/removed since last setup — `vendor/bin/sail` exists but entry uses `php`, or vice versa), update the command to match current state
+- For Laravel Boost Sail detection: use `vendor/bin/sail` command variant if `vendor/bin/sail` exists in the project
+
 **Config update:**
 - Update `.shipkit/config.json` with new `stack.detected`, `stack.detected_at`, `stack.capabilities`
 
@@ -245,9 +256,11 @@ After hooks deployment, check and configure LSP tooling:
 
 **Idempotency:** Never overwrite existing hook files — the user may have customized them. Only deploy hooks that don't exist yet. For settings.json, merge additively.
 
-### Step 1.7: MCP Servers & Plugin Check
+### Step 1.7: Global MCP Servers & Plugin Check
+
+After LSP check, verify the three recommended **global** tools are configured.
 
-After LSP check, verify the three recommended tools are configured:
+> **Note:** Project-level MCP (`.mcp.json`) is managed exclusively by Step 0.5 during stack sync. This step only handles global MCP/plugins.
 
 1. **Sequential Thinking MCP** — grep `~/.mcp.json` for `sequential-thinking`
 2. **Context7 plugin** — grep `~/.claude/settings.json` for `context7@claude-plugins-official` in `enabledPlugins`
@@ -255,7 +268,7 @@ After LSP check, verify the three recommended tools are configured:
 
 **Report status and prompt:**
 
-> "MCP/Plugins: [X/3] configured
+> "Global MCP/Plugins: [X/3] configured
 >   sequential-thinking: [✓ configured / ✗ missing]
 >   context7:            [✓ configured / ✗ missing]
 >   ccstatusline:        [✓ configured / ✗ missing]