@mthines/reaper-mcp 0.14.1 → 0.14.2-beta.17.1

package/main.js

@@ -2202,10 +2202,10 @@ function createServer() {
 }
 
 // apps/reaper-mcp-server/src/main.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync2 } from "node:fs";
-import { join as join4, dirname as dirname2 } from "node:path";
+import { existsSync as existsSync3, mkdirSync as mkdirSync3 } from "node:fs";
+import { join as join5, dirname as dirname2 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
-import { homedir as homedir2 } from "node:os";
+import { homedir as homedir3 } from "node:os";
 
 // apps/reaper-mcp-server/src/cli.ts
 import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
@@ -2391,6 +2391,174 @@ function resolveAssetDirWithFallback(baseDir, buildName, sourceName) {
   return resolveAssetDir(baseDir, sourceName);
 }
 
+// apps/reaper-mcp-server/src/init.ts
+import { checkbox, select } from "@inquirer/prompts";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2 } from "node:fs";
+import { join as join4 } from "node:path";
+import { homedir as homedir2 } from "node:os";
+async function runInit(opts, dirResolver) {
+  const isTTY = Boolean(process.stdin.isTTY);
+  const headless = opts.yes || !isTTY;
+  console.log("REAPER MCP \u2014 Interactive Setup\n");
+  const bridgeDir = await ensureBridgeDir();
+  console.log(`REAPER resource path: ${join4(bridgeDir, "..", "..")}
+`);
+  let selections;
+  if (headless) {
+    selections = {
+      bridge: true,
+      skills: true,
+      settings: true,
+      projectConfig: opts.project,
+      skillsScope: "global"
+    };
+    if (opts.yes) {
+      console.log("Running in non-interactive mode (--yes flag).\n");
+    } else {
+      console.log("Non-interactive terminal detected. Running with defaults.\n");
+    }
+  } else {
+    const components = await checkbox({
+      message: "Which components would you like to install?",
+      choices: [
+        { name: "REAPER Bridge  (Lua bridge + JSFX analyzers)", value: "bridge", checked: true },
+        { name: `AI Skills & Agents  (knowledge base, Claude agents, rules, skills)`, value: "skills", checked: true },
+        { name: `Claude Code Settings  (auto-allow ${MCP_TOOL_NAMES.length} REAPER tools)`, value: "settings", checked: true },
+        { name: "Project Config  (.mcp.json in current directory)", value: "projectConfig", checked: false }
+      ]
+    });
+    let skillsScope = "global";
+    if (components.includes("skills")) {
+      const scopeAnswer = await select({
+        message: "Install scope for AI Skills & Agents:",
+        choices: [
+          { name: "Global (~/.claude/)  \u2014 available in all projects", value: "global" },
+          { name: "Project (.claude/)   \u2014 current directory only", value: "project" }
+        ]
+      });
+      skillsScope = scopeAnswer;
+    }
+    selections = {
+      bridge: components.includes("bridge"),
+      skills: components.includes("skills"),
+      settings: components.includes("settings"),
+      projectConfig: components.includes("projectConfig"),
+      skillsScope
+    };
+  }
+  const __dirname2 = dirResolver();
+  if (selections.bridge) {
+    console.log("Installing REAPER Bridge...");
+    const scriptsDir = getReaperScriptsPath();
+    mkdirSync2(scriptsDir, { recursive: true });
+    const reaperDir = resolveAssetDir(__dirname2, "reaper");
+    const luaSrc = join4(reaperDir, "mcp_bridge.lua");
+    const luaDest = join4(scriptsDir, "mcp_bridge.lua");
+    if (installFile(luaSrc, luaDest)) {
+      console.log("  Installed: mcp_bridge.lua");
+    } else {
+      console.log(`  Not found: ${luaSrc}`);
+    }
+    const effectsDir = join4(getReaperEffectsPath(), "reaper-mcp");
+    mkdirSync2(effectsDir, { recursive: true });
+    for (const jsfx of REAPER_ASSETS) {
+      if (jsfx === "mcp_bridge.lua") continue;
+      const src = join4(reaperDir, jsfx);
+      const dest = join4(effectsDir, jsfx);
+      if (installFile(src, dest)) {
+        console.log(`  Installed: reaper-mcp/${jsfx}`);
+      } else {
+        console.log(`  Not found: ${src}`);
+      }
+    }
+    console.log("");
+  }
+  if (selections.skills) {
+    const isGlobal = selections.skillsScope === "global";
+    const baseDir = isGlobal ? join4(homedir2(), ".claude") : process.cwd();
+    const claudeDir = isGlobal ? baseDir : join4(baseDir, ".claude");
+    console.log(`Installing AI Skills & Agents (${selections.skillsScope})...`);
+    const knowledgeSrc = resolveAssetDir(__dirname2, "knowledge");
+    if (existsSync2(knowledgeSrc)) {
+      const dest = join4(isGlobal ? join4(homedir2(), ".claude") : process.cwd(), "knowledge");
+      const count = copyDirSync(knowledgeSrc, dest);
+      console.log(`  Installed knowledge base: ${count} files`);
+    } else {
+      console.log("  Knowledge base not found in package. Skipping.");
+    }
+    const rulesSrc = resolveAssetDirWithFallback(__dirname2, "claude-rules", join4(".claude", "rules"));
+    if (existsSync2(rulesSrc)) {
+      const dest = join4(claudeDir, "rules");
+      const count = copyDirSync(rulesSrc, dest);
+      console.log(`  Installed Claude rules: ${count} files`);
+    }
+    const skillsSrc = resolveAssetDirWithFallback(__dirname2, "claude-skills", join4(".claude", "skills"));
+    if (existsSync2(skillsSrc)) {
+      const dest = join4(claudeDir, "skills");
+      const count = copyDirSync(skillsSrc, dest);
+      console.log(`  Installed Claude skills: ${count} files`);
+    }
+    const agentsSrc = resolveAssetDirWithFallback(__dirname2, "claude-agents", join4(".claude", "agents"));
+    if (existsSync2(agentsSrc)) {
+      const dest = join4(claudeDir, "agents");
+      const count = copyDirSync(agentsSrc, dest);
+      console.log(`  Installed Claude agents: ${count} files`);
+    }
+    console.log("");
+  }
+  if (selections.settings) {
+    console.log("Configuring Claude Code Settings...");
+    const settingsDir = join4(homedir2(), ".claude");
+    const settingsPath = join4(settingsDir, "settings.json");
+    const result = ensureClaudeSettings(settingsPath);
+    if (result === "created") {
+      console.log(`  Created: ${settingsPath}`);
+    } else if (result === "updated") {
+      console.log(`  Updated with new REAPER tools: ${settingsPath}`);
+    } else {
+      console.log(`  Already configured: ${settingsPath}`);
+    }
+    console.log("");
+  }
+  if (selections.projectConfig) {
+    console.log("Creating Project Config...");
+    const mcpJsonPath = join4(process.cwd(), ".mcp.json");
+    if (createMcpJson(mcpJsonPath)) {
+      console.log(`  Created: ${mcpJsonPath}`);
+    } else {
+      console.log(`  Already exists: ${mcpJsonPath}`);
+    }
+    console.log("");
+  }
+  console.log("Running system check...");
+  const bridgeRunning = await isBridgeRunning();
+  console.log(`  Lua bridge:    ${bridgeRunning ? "Connected" : "Not detected (start after REAPER is open)"}`);
+  const globalClaudeDir = join4(homedir2(), ".claude");
+  const localAgents = existsSync2(join4(process.cwd(), ".claude", "agents"));
+  const globalAgents = existsSync2(join4(globalClaudeDir, "agents"));
+  const agentsExist = localAgents || globalAgents;
+  console.log(`  Mix agents:    ${agentsExist ? "Installed" : "Not installed"}`);
+  const mcpJsonExists = existsSync2(join4(process.cwd(), ".mcp.json"));
+  console.log(`  MCP config:    ${mcpJsonExists ? ".mcp.json found" : ".mcp.json not present"}`);
+  console.log("");
+  console.log("Setup complete! Next steps:");
+  if (selections.bridge) {
+    const scriptsDir = getReaperScriptsPath();
+    const luaDest = join4(scriptsDir, "mcp_bridge.lua");
+    console.log("  1. Open REAPER");
+    console.log("  2. Actions > Show action list > Load ReaScript");
+    console.log(`  3. Select: ${luaDest}`);
+    console.log("  4. Run the script (it keeps running via defer loop)");
+    console.log("  5. Open Claude Code \u2014 REAPER tools + mix engineer agents are ready");
+  } else {
+    console.log("  1. Open Claude Code \u2014 REAPER tools + mix engineer agents are ready");
+  }
+  if (agentsExist) {
+    console.log('\nTry: @mix-engineer "Please gain stage my tracks"');
+    console.log('Or:  @mix-analyzer "Roast my mix"');
+  }
+}
+
 // apps/reaper-mcp-server/src/main.ts
 var __dirname = dirname2(fileURLToPath2(import.meta.url));
 async function setup() {
@@ -2399,23 +2567,23 @@ async function setup() {
   console.log(`Bridge directory: ${bridgeDir}
 `);
   const scriptsDir = getReaperScriptsPath();
-  mkdirSync2(scriptsDir, { recursive: true });
+  mkdirSync3(scriptsDir, { recursive: true });
   const reaperDir = resolveAssetDir(__dirname, "reaper");
-  const luaSrc = join4(reaperDir, "mcp_bridge.lua");
-  const luaDest = join4(scriptsDir, "mcp_bridge.lua");
+  const luaSrc = join5(reaperDir, "mcp_bridge.lua");
+  const luaDest = join5(scriptsDir, "mcp_bridge.lua");
   console.log("Installing Lua bridge...");
   if (installFile(luaSrc, luaDest)) {
     console.log(`  Installed: mcp_bridge.lua`);
   } else {
     console.log(`  Not found: ${luaSrc}`);
   }
-  const effectsDir = join4(getReaperEffectsPath(), "reaper-mcp");
-  mkdirSync2(effectsDir, { recursive: true });
+  const effectsDir = join5(getReaperEffectsPath(), "reaper-mcp");
+  mkdirSync3(effectsDir, { recursive: true });
   console.log("\nInstalling JSFX analyzers...");
   for (const jsfx of REAPER_ASSETS) {
     if (jsfx === "mcp_bridge.lua") continue;
-    const src = join4(reaperDir, jsfx);
-    const dest = join4(effectsDir, jsfx);
+    const src = join5(reaperDir, jsfx);
+    const dest = join5(effectsDir, jsfx);
     if (installFile(src, dest)) {
       console.log(`  Installed: reaper-mcp/${jsfx}`);
     } else {
@@ -2438,41 +2606,41 @@ async function installSkills(scope) {
   console.log(`REAPER MCP \u2014 Install AI Mix Engineer Skills (scope: ${scope})
 `);
   const isGlobal = scope === "global";
-  const baseDir = isGlobal ? join4(homedir2(), ".claude") : process.cwd();
-  const claudeDir = isGlobal ? baseDir : join4(baseDir, ".claude");
+  const baseDir = isGlobal ? join5(homedir3(), ".claude") : process.cwd();
+  const claudeDir = isGlobal ? baseDir : join5(baseDir, ".claude");
   const knowledgeSrc = resolveAssetDir(__dirname, "knowledge");
-  if (existsSync2(knowledgeSrc)) {
-    const dest = join4(baseDir, "knowledge");
+  if (existsSync3(knowledgeSrc)) {
+    const dest = join5(baseDir, "knowledge");
     const count = copyDirSync(knowledgeSrc, dest);
     console.log(`Installed knowledge base: ${count} files \u2192 ${dest}`);
   } else {
     console.log("Knowledge base not found in package. Skipping.");
   }
-  const rulesSrc = resolveAssetDirWithFallback(__dirname, "claude-rules", join4(".claude", "rules"));
-  if (existsSync2(rulesSrc)) {
-    const dest = join4(claudeDir, "rules");
+  const rulesSrc = resolveAssetDirWithFallback(__dirname, "claude-rules", join5(".claude", "rules"));
+  if (existsSync3(rulesSrc)) {
+    const dest = join5(claudeDir, "rules");
     const count = copyDirSync(rulesSrc, dest);
     console.log(`Installed Claude rules: ${count} files \u2192 ${dest}`);
   } else {
     console.log("Claude rules not found in package. Skipping.");
   }
-  const skillsSrc = resolveAssetDirWithFallback(__dirname, "claude-skills", join4(".claude", "skills"));
-  if (existsSync2(skillsSrc)) {
-    const dest = join4(claudeDir, "skills");
+  const skillsSrc = resolveAssetDirWithFallback(__dirname, "claude-skills", join5(".claude", "skills"));
+  if (existsSync3(skillsSrc)) {
+    const dest = join5(claudeDir, "skills");
     const count = copyDirSync(skillsSrc, dest);
     console.log(`Installed Claude skills: ${count} files \u2192 ${dest}`);
   } else {
     console.log("Claude skills not found in package. Skipping.");
   }
-  const agentsSrc = resolveAssetDirWithFallback(__dirname, "claude-agents", join4(".claude", "agents"));
-  if (existsSync2(agentsSrc)) {
-    const dest = join4(claudeDir, "agents");
+  const agentsSrc = resolveAssetDirWithFallback(__dirname, "claude-agents", join5(".claude", "agents"));
+  if (existsSync3(agentsSrc)) {
+    const dest = join5(claudeDir, "agents");
     const count = copyDirSync(agentsSrc, dest);
     console.log(`Installed Claude agents: ${count} files \u2192 ${dest}`);
   } else {
     console.log("Claude agents not found in package. Skipping.");
   }
-  const settingsPath = join4(claudeDir, "settings.json");
+  const settingsPath = join5(claudeDir, "settings.json");
   const result = ensureClaudeSettings(settingsPath);
   if (result === "created") {
     console.log(`Created Claude settings: ${settingsPath}`);
@@ -2482,7 +2650,7 @@ async function installSkills(scope) {
     console.log(`Claude settings already has all REAPER tools: ${settingsPath}`);
   }
   if (!isGlobal) {
-    const mcpJsonPath = join4(baseDir, ".mcp.json");
+    const mcpJsonPath = join5(baseDir, ".mcp.json");
     if (createMcpJson(mcpJsonPath)) {
       console.log(`
 Created: ${mcpJsonPath}`);
@@ -2503,24 +2671,24 @@ async function doctor() {
   if (!bridgeRunning) {
     console.log('  \u2192 Run "npx @mthines/reaper-mcp setup" then load mcp_bridge.lua in REAPER');
   }
-  const globalClaudeDir = join4(homedir2(), ".claude");
-  const localAgents = existsSync2(join4(process.cwd(), ".claude", "agents"));
-  const globalAgents = existsSync2(join4(globalClaudeDir, "agents"));
+  const globalClaudeDir = join5(homedir3(), ".claude");
+  const localAgents = existsSync3(join5(process.cwd(), ".claude", "agents"));
+  const globalAgents = existsSync3(join5(globalClaudeDir, "agents"));
   const agentsExist = localAgents || globalAgents;
   const agentsLocation = localAgents ? ".claude/agents/" : globalAgents ? "~/.claude/agents/" : "";
   console.log(`Mix agents:    ${agentsExist ? `\u2713 Found (${agentsLocation})` : "\u2717 Not installed"}`);
   if (!agentsExist) {
     console.log('  \u2192 Run "npx @mthines/reaper-mcp install-skills"');
   }
-  const localKnowledge = existsSync2(join4(process.cwd(), "knowledge"));
-  const globalKnowledge = existsSync2(join4(globalClaudeDir, "knowledge"));
+  const localKnowledge = existsSync3(join5(process.cwd(), "knowledge"));
+  const globalKnowledge = existsSync3(join5(globalClaudeDir, "knowledge"));
   const knowledgeExists = localKnowledge || globalKnowledge;
   const knowledgeLocation = localKnowledge ? "project" : globalKnowledge ? "~/.claude/" : "";
   console.log(`Knowledge base: ${knowledgeExists ? `\u2713 Found (${knowledgeLocation})` : "\u2717 Not installed"}`);
   if (!knowledgeExists) {
     console.log('  \u2192 Run "npx @mthines/reaper-mcp install-skills"');
   }
-  const mcpJsonExists = existsSync2(join4(process.cwd(), ".mcp.json"));
+  const mcpJsonExists = existsSync3(join5(process.cwd(), ".mcp.json"));
   console.log(`MCP config:    ${mcpJsonExists ? "\u2713 .mcp.json found" : "\u2717 .mcp.json missing"}`);
   if (!mcpJsonExists) {
     console.log('  \u2192 Run "npx @mthines/reaper-mcp install-skills --project" to create .mcp.json');
@@ -2583,7 +2751,19 @@ async function serve() {
   });
 }
 var command = process.argv[2];
+var cliArgs = process.argv.slice(3);
+var hasYesFlag = cliArgs.includes("--yes") || cliArgs.includes("-y");
+var hasProjectFlag = cliArgs.includes("--project");
 switch (command) {
+  case "init":
+    runInit(
+      { yes: hasYesFlag, project: hasProjectFlag },
+      () => __dirname
+    ).catch((err) => {
+      console.error("Init failed:", err);
+      process.exit(1);
+    });
+    break;
   case "setup":
     setup().catch((err) => {
       console.error("Setup failed:", err);
@@ -2623,6 +2803,9 @@ switch (command) {
 Usage:
   npx @mthines/reaper-mcp                  Start MCP server (stdio mode)
   npx @mthines/reaper-mcp serve            Start MCP server (stdio mode)
+  npx @mthines/reaper-mcp init             Guided interactive setup (recommended for new users)
+  npx @mthines/reaper-mcp init --yes       Non-interactive setup (install everything with defaults)
+  npx @mthines/reaper-mcp init --project   Include .mcp.json in current directory
   npx @mthines/reaper-mcp setup            Install Lua bridge + JSFX analyzers into REAPER
   npx @mthines/reaper-mcp install-skills   Install AI knowledge + agents globally (default)
   npx @mthines/reaper-mcp install-skills --project  Install into current project directory
@@ -2630,7 +2813,10 @@ Usage:
   npx @mthines/reaper-mcp doctor           Check that everything is configured correctly
   npx @mthines/reaper-mcp status           Check if Lua bridge is running in REAPER
 
-Quick Start:
+Quick Start (interactive):
+  npx @mthines/reaper-mcp init             # guided setup \u2014 select components interactively
+
+Quick Start (manual steps):
   1. npx @mthines/reaper-mcp setup            # install REAPER components
   2. Load mcp_bridge.lua in REAPER (Actions > Load ReaScript > Run)
   3. npx @mthines/reaper-mcp install-skills   # install AI knowledge + agents (globally)
@@ -2638,7 +2824,7 @@ Quick Start:
 
 Tip: install globally for shorter commands:
   npm install -g @mthines/reaper-mcp
-  reaper-mcp setup
+  reaper-mcp init
 `);
     break;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mthines/reaper-mcp",
-  "version": "0.14.1",
+  "version": "0.14.2-beta.17.1",
   "type": "module",
   "description": "MCP server for controlling REAPER DAW — real-time mixing, FX control, and frequency analysis for AI agents",
   "license": "MIT",
@@ -27,6 +27,7 @@
     "reaper-mcp": "./main.js"
   },
   "dependencies": {
+    "@inquirer/prompts": "^8.3.2",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/auto-instrumentations-node": "^0.71.0",

package/reaper/mcp_bridge.lua

@@ -584,23 +584,10 @@ function handlers.read_track_spectrum(params)
   local track = reaper.GetTrack(0, idx)
   if not track then return nil, "Track " .. idx .. " not found" end
 
-  -- Check if MCP analyzer JSFX is already on the track
-  local analyzer_idx = -1
-  local fx_count = reaper.TrackFX_GetCount(track)
-  for i = 0, fx_count - 1 do
-    local _, name = reaper.TrackFX_GetFXName(track, i)
-    if name and name:find(MCP_ANALYZER_FX_NAME) then
-      analyzer_idx = i
-      break
-    end
-  end
-
-  -- Auto-insert if not present
-  if analyzer_idx < 0 then
-    analyzer_idx = reaper.TrackFX_AddByName(track, MCP_ANALYZER_FX_NAME, false, -1)
-    if analyzer_idx < 0 then
-      return nil, "MCP Spectrum Analyzer JSFX not found. Run 'reaper-mcp setup' to install it."
-    end
+  -- Find or auto-insert analyzer (uses MCP Meters container if available)
+  local analyzer_idx, err = ensure_jsfx_on_track(track, MCP_ANALYZER_FX_NAME)
+  if not analyzer_idx then
+    return nil, err or "MCP Spectrum Analyzer JSFX not found. Run 'reaper-mcp setup' to install it."
   end
 
   -- Read spectrum data from gmem
@@ -1228,10 +1215,119 @@ end
 local MCP_LUFS_METER_FX_NAME        = "reaper-mcp/mcp_lufs_meter"
 local MCP_CORRELATION_METER_FX_NAME = "reaper-mcp/mcp_correlation_meter"
 local MCP_CREST_FACTOR_FX_NAME      = "reaper-mcp/mcp_crest_factor"
+local MCP_FX_PREFIX                 = "reaper%-mcp/"  -- Lua pattern for matching MCP JSFX names
+
+-- Per-track cache of MCP container FX index to avoid rescanning on every read.
+-- Keyed by track pointer (userdata), value is container FX index or false (no container).
+-- Invalidated when the FX chain changes (checked via TrackFX_GetCount).
+local container_cache = {}
+
+-- Find or create the MCP Meters container on a track.
+-- Uses REAPER 7.06+ container_item.X API. Returns container FX index, or nil
+-- if containers are not supported (REAPER < 7.06).
+local function find_or_create_mcp_container(track)
+  -- Check cache first
+  local cache_entry = container_cache[tostring(track)]
+  if cache_entry then
+    local cached_idx, cached_fx_count = cache_entry[1], cache_entry[2]
+    local current_fx_count = reaper.TrackFX_GetCount(track)
+    if current_fx_count == cached_fx_count then
+      if cached_idx == false then return nil end  -- cached negative result
+      return cached_idx
+    end
+    -- FX count changed — invalidate cache
+    container_cache[tostring(track)] = nil
+  end
+
+  local fx_count = reaper.TrackFX_GetCount(track)
+
+  -- Search for existing container that holds MCP JSFX
+  for i = 0, fx_count - 1 do
+    local _, name = reaper.TrackFX_GetFXName(track, i)
+    if name and (name:find("Container") or name:find("MCP Meters")) then
+      local ok, count_str = reaper.TrackFX_GetNamedConfigParm(track, i, "container_count")
+      if ok then
+        local count = tonumber(count_str) or 0
+        for j = 0, count - 1 do
+          local _, addr_str = reaper.TrackFX_GetNamedConfigParm(track, i, "container_item." .. j)
+          local addr = tonumber(addr_str)
+          if addr then
+            local _, fx_name = reaper.TrackFX_GetFXName(track, addr)
+            if fx_name and fx_name:find(MCP_FX_PREFIX) then
+              -- Found our container — cache and return
+              container_cache[tostring(track)] = { i, fx_count }
+              return i
+            end
+          end
+        end
+      end
+    end
+  end
+
+  -- No existing MCP container — create one at end of chain
+  local idx = reaper.TrackFX_AddByName(track, "Container", false, -1)
+  if idx < 0 then
+    -- Container FX not available (REAPER < 7)
+    container_cache[tostring(track)] = { false, fx_count }
+    return nil
+  end
+
+  -- Name the container "MCP Meters" for easy identification
+  reaper.TrackFX_SetNamedConfigParm(track, idx, "renamed_name", "MCP Meters")
+
+  -- Verify container API works (confirms REAPER 7.06+)
+  local ok = reaper.TrackFX_GetNamedConfigParm(track, idx, "container_count")
+  if not ok then
+    -- API not available — remove the container and fall back
+    reaper.TrackFX_Delete(track, idx)
+    container_cache[tostring(track)] = { false, fx_count }
+    return nil
+  end
+
+  -- Cache the new container (fx_count + 1 because we just added the container)
+  container_cache[tostring(track)] = { idx, reaper.TrackFX_GetCount(track) }
+  return idx
+end
 
 -- Helper: find or auto-insert a named JSFX on a track.
--- Returns the FX index (0-based) on success, or nil + error message on failure.
+-- Tries to place inside an "MCP Meters" FX Container (REAPER 7.06+).
+-- Falls back to direct insertion on older REAPER versions.
+-- Returns the FX index (possibly container-addressed) on success, or nil + error.
 local function ensure_jsfx_on_track(track, fx_name)
+  -- Try container approach first (REAPER 7.06+)
+  local container_idx = find_or_create_mcp_container(track)
+  if container_idx then
+    local ok, count_str = reaper.TrackFX_GetNamedConfigParm(track, container_idx, "container_count")
+    local count = tonumber(count_str) or 0
+
+    -- Search inside container for existing JSFX
+    for i = 0, count - 1 do
+      local _, addr_str = reaper.TrackFX_GetNamedConfigParm(track, container_idx, "container_item." .. i)
+      local addr = tonumber(addr_str)
+      if addr then
+        local _, name = reaper.TrackFX_GetFXName(track, addr)
+        if name and name:find(fx_name, 1, true) then
+          return addr  -- Found inside container
+        end
+      end
+    end
+
+    -- Not found — insert inside container
+    -- Use legacy addressing: 0x2000000 + (1-based slot) * (top_chain_count + 1) + (1-based container pos)
+    local top_count = reaper.TrackFX_GetCount(track)
+    local slot = count + 1  -- 1-based, next empty slot
+    local container_pos = container_idx + 1  -- 1-based
+    local insert_addr = 0x2000000 + slot * (top_count + 1) + container_pos
+    local new_idx = reaper.TrackFX_AddByName(track, fx_name, false, insert_addr)
+    if new_idx >= 0 then
+      -- Invalidate cache since FX count changed
+      container_cache[tostring(track)] = nil
+      return new_idx
+    end
+    -- Container insertion failed — fall through to direct
+  end
+
+  -- Fallback: direct insertion (REAPER < 7.06 or container failed)
   local fx_count = reaper.TrackFX_GetCount(track)
   for i = 0, fx_count - 1 do
     local _, name = reaper.TrackFX_GetFXName(track, i)
@@ -1239,7 +1335,6 @@ local function ensure_jsfx_on_track(track, fx_name)
       return i
     end
   end
-  -- Auto-insert
   local idx = reaper.TrackFX_AddByName(track, fx_name, false, -1)
   if idx < 0 then
     return nil, fx_name .. " JSFX not found. Run 'reaper-mcp setup' to install it."