feat(scripts): merge-mcp.sh — preserves laravel-boost, replaces brain-managed MCP

Uses jq --slurpfile pattern (NOT broken `.[1].mcpServers` form from plan):
  jq --slurpfile brain "$brain_mcp" \
     '.mcpServers = ((.mcpServers // {}) + $brain[0].mcpServers)' "$target"

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

scripts/fixtures/sample-claude-json.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "laravel-boost": {
+      "command": "php",
+      "args": ["app/artisan", "boost:mcp"]
+    },
+    "magic": {
+      "type": "stdio",
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "@21st-dev/magic@latest", "API_KEY=OLD_VALUE"]
+    }
+  },
+  "preserveMe": "yes"
+}

scripts/fixtures/sample-mcp.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://raw.githubusercontent.com/anthropics/claude-code/main/schemas/mcp.json",
+  "mcpServers": {
+    "laravel-boost": {
+      "command": "php",
+      "args": ["app/artisan", "boost:mcp"]
+    }
+  }
+}

scripts/lib/merge-mcp.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# Merge brain MCP template into consumer's claude.json or project .mcp.json
+# Mode: user (merge into ~/.claude.json:mcpServers) or project (merge into <repo>/.mcp.json:mcpServers)
+# Preserves consumer-specific servers; brain-managed servers override on key collision.
+#
+# Usage: merge-mcp.sh --mode=user|project <target> <brain-mcp.json>
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+mode=""
+case "${1:-}" in
+    --mode=user) mode="user"; shift ;;
+    --mode=project) mode="project"; shift ;;
+    *) log_error "First arg must be --mode=user or --mode=project"; exit 1 ;;
+esac
+
+target="$1"
+brain_mcp="$2"
+
+require_cmd jq || exit 1
+[ -f "$brain_mcp" ] || { log_error "Brain MCP file not found: $brain_mcp"; exit 1; }
+
+# If target missing, copy brain template
+if [ ! -f "$target" ]; then
+    log_info "Target $target missing, creating from brain template"
+    cp "$brain_mcp" "$target"
+    exit 0
+fi
+
+# Backup
+backup="${target}.bak.$(date +%s)"
+cp "$target" "$backup"
+
+# CORRECTION A: use --slurpfile to bind brain file to $brain (array of docs);
+# $brain[0] accesses the single document. This avoids the broken
+# "jq -s '.[0] | ... .[1].mcpServers'" form (which inside the inner pipe makes
+# .[1] index the object — runtime error "Cannot index object with number").
+#
+# Merge semantics: target.mcpServers (or {} if missing) UNION brain.mcpServers,
+# with brain entries overriding on key collision (laravel-boost stays — brain
+# template doesn't define it; magic gets replaced if brain defines it).
+tmp="${target}.tmp"
+jq --slurpfile brain "$brain_mcp" \
+   '.mcpServers = ((.mcpServers // {}) + $brain[0].mcpServers)' \
+   "$target" > "$tmp"
+
+# Validate
+jq empty "$tmp" || { log_error "Merge produced invalid JSON"; rm "$tmp"; exit 1; }
+
+mv "$tmp" "$target"
+log_info "MCP ($mode mode) merged (backup: $backup)"

scripts/tests/merge-mcp-test.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+set -u
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+source "$SCRIPT_DIR/lib/common.sh"
+
+FAILURES=0
+assert_eq() {
+    if [ "$1" = "$2" ]; then echo "PASS: $3"; else echo "FAIL: $3 (expected '$1', got '$2')"; FAILURES=$((FAILURES + 1)); fi
+}
+
+# Test 1: user-mode merge — magic replaced, laravel-boost preserved
+tmpdir=$(mktemp -d)
+cp "$SCRIPT_DIR/fixtures/sample-claude-json.json" "$tmpdir/.claude.json"
+cat > "$tmpdir/brain-mcp.json" <<EOF2
+{
+  "mcpServers": {
+    "magic": {
+      "type": "stdio",
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "@21st-dev/magic@latest", "API_KEY=<<MAGIC_API_KEY>>"]
+    }
+  }
+}
+EOF2
+
+bash "$SCRIPT_DIR/lib/merge-mcp.sh" --mode=user "$tmpdir/.claude.json" "$tmpdir/brain-mcp.json"
+
+# magic args should now contain placeholder
+magic_api_key=$(jq -r '.mcpServers.magic.args[-1]' "$tmpdir/.claude.json")
+assert_eq "API_KEY=<<MAGIC_API_KEY>>" "$magic_api_key" "user-mode: magic API_KEY replaced with placeholder"
+
+# laravel-boost preserved
+lb_cmd=$(jq -r '.mcpServers["laravel-boost"].command' "$tmpdir/.claude.json")
+assert_eq "php" "$lb_cmd" "user-mode: laravel-boost preserved"
+
+# preserveMe key still present (other keys unchanged)
+preserve=$(jq -r '.preserveMe' "$tmpdir/.claude.json")
+assert_eq "yes" "$preserve" "user-mode: other top-level keys preserved"
+
+rm -rf "$tmpdir"
+
+# Test 2: project-mode merge — playwright/github/semgrep added, laravel-boost preserved
+tmpdir=$(mktemp -d)
+cp "$SCRIPT_DIR/fixtures/sample-mcp.json" "$tmpdir/.mcp.json"
+cat > "$tmpdir/brain-mcp.json" <<EOF3
+{
+  "mcpServers": {
+    "playwright": {"command": "npx", "args": ["-y", "@playwright/mcp"]},
+    "github": {"type": "http", "url": "https://api.githubcopilot.com/mcp"},
+    "semgrep": {"command": "npx", "args": ["-y", "semgrep-mcp"]}
+  }
+}
+EOF3
+
+bash "$SCRIPT_DIR/lib/merge-mcp.sh" --mode=project "$tmpdir/.mcp.json" "$tmpdir/brain-mcp.json"
+
+# Should have 4 servers total
+count=$(jq '.mcpServers | length' "$tmpdir/.mcp.json")
+assert_eq "4" "$count" "project-mode: 4 servers after merge"
+
+# laravel-boost preserved
+lb=$(jq -r '.mcpServers["laravel-boost"].command' "$tmpdir/.mcp.json")
+assert_eq "php" "$lb" "project-mode: laravel-boost preserved"
+
+# playwright added
+pw=$(jq -r '.mcpServers.playwright.command' "$tmpdir/.mcp.json")
+assert_eq "npx" "$pw" "project-mode: playwright added"
+
+rm -rf "$tmpdir"
+
+echo "---"
+echo "Failures: $FAILURES"
+exit $FAILURES