@mthines/reaper-mcp 0.19.0-beta.20.2 → 0.19.0

package/main.js

@@ -27,10 +27,10 @@ var SCOPE_NAME = "reaper-mcp-server";
 function readServiceVersion() {
   try {
     const require2 = createRequire(import.meta.url);
-    const __dirname2 = dirname(fileURLToPath(import.meta.url));
+    const __dirname3 = dirname(fileURLToPath(import.meta.url));
     const pkgPaths = [
-      join(__dirname2, "..", "package.json"),
-      join(__dirname2, "package.json")
+      join(__dirname3, "..", "package.json"),
+      join(__dirname3, "package.json")
     ];
     for (const p of pkgPaths) {
       try {
@@ -2232,6 +2232,288 @@ function registerCategoryTools(server) {
   );
 }
 
+// apps/reaper-mcp-server/src/tools/aesthetics.ts
+import { z as z17 } from "zod/v4";
+import { unlink as unlink2 } from "node:fs/promises";
+import { randomUUID as randomUUID2 } from "node:crypto";
+
+// apps/reaper-mcp-server/src/sidecar.ts
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join as join3 } from "node:path";
+import { homedir as homedir2, platform as platform2 } from "node:os";
+var VENV_BIN = platform2() === "win32" ? "Scripts" : "bin";
+var VENV_PYTHON_NAME = platform2() === "win32" ? "python.exe" : "python";
+var SIDECAR_VENV_PATH = join3(homedir2(), ".reaper-mcp", "sidecar-venv");
+var SIDECAR_SCRIPT_PATH = join3(homedir2(), ".reaper-mcp", "sidecar", "server.py");
+var VENV_PYTHON = join3(SIDECAR_VENV_PATH, VENV_BIN, VENV_PYTHON_NAME);
+var _rawTimeout = Number(process.env["REAPER_MCP_SIDECAR_TIMEOUT_MS"]);
+var ANALYZE_TIMEOUT_MS = Number.isFinite(_rawTimeout) && _rawTimeout > 0 ? _rawTimeout : 6e4;
+var SidecarClientImpl = class {
+  process = null;
+  pending = /* @__PURE__ */ new Map();
+  nextId = 1;
+  lineBuffer = "";
+  restarting = false;
+  restartAttempted = false;
+  /** Cached spawn promise — prevents double-spawn on concurrent cold-start calls. */
+  spawnPromise = null;
+  isAvailable() {
+    return existsSync(SIDECAR_SCRIPT_PATH) && existsSync(VENV_PYTHON);
+  }
+  async analyze(wavPath, startTime, endTime) {
+    if (!this.isAvailable()) {
+      throw new Error(
+        "Audio understanding sidecar not installed. Run: node dist/apps/reaper-mcp-server/main.js setup-sidecar"
+      );
+    }
+    await this.ensureRunning();
+    return new Promise((resolve, reject) => {
+      const id = this.nextId++;
+      const request = {
+        jsonrpc: "2.0",
+        id,
+        method: "analyze",
+        params: { path: wavPath, startTime, endTime }
+      };
+      const timer = setTimeout(() => {
+        if (this.pending.delete(id)) {
+          process.stderr.write(
+            `[reaper-mcp] Sidecar analyze() timed out after ${ANALYZE_TIMEOUT_MS}ms \u2014 killing process
+`
+          );
+          if (this.process) {
+            this.process.kill("SIGKILL");
+            this.process = null;
+          }
+          reject(new Error(
+            `Sidecar timeout after ${ANALYZE_TIMEOUT_MS}ms. Override with REAPER_MCP_SIDECAR_TIMEOUT_MS env var.`
+          ));
+        }
+      }, ANALYZE_TIMEOUT_MS);
+      this.pending.set(id, {
+        resolve: (r) => {
+          clearTimeout(timer);
+          resolve(r);
+        },
+        reject: (e) => {
+          clearTimeout(timer);
+          reject(e);
+        }
+      });
+      const line = JSON.stringify(request) + "\n";
+      try {
+        const proc = this.process;
+        if (!proc || !proc.stdin) {
+          throw new Error("Sidecar process not running");
+        }
+        proc.stdin.write(line);
+      } catch (err) {
+        clearTimeout(timer);
+        this.pending.delete(id);
+        reject(new Error(`Failed to write to sidecar stdin: ${err instanceof Error ? err.message : String(err)}`));
+      }
+    });
+  }
+  shutdown() {
+    if (this.process) {
+      this.process.kill("SIGTERM");
+      this.process = null;
+    }
+    for (const [id, { reject }] of this.pending.entries()) {
+      reject(new Error("Sidecar shut down"));
+      this.pending.delete(id);
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Private
+  // -------------------------------------------------------------------------
+  async ensureRunning() {
+    if (this.process && !this.process.killed) return;
+    if (!this.spawnPromise) {
+      this.spawnPromise = this.spawn().finally(() => {
+        this.spawnPromise = null;
+      });
+    }
+    await this.spawnPromise;
+  }
+  async spawn() {
+    const child = spawn(VENV_PYTHON, [SIDECAR_SCRIPT_PATH], {
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    if (child.stdout) {
+      child.stdout.setEncoding("utf8");
+      child.stdout.on("data", (chunk) => this.onStdout(chunk));
+    }
+    if (child.stderr) {
+      child.stderr.setEncoding("utf8");
+      child.stderr.on("data", (data) => {
+        process.stderr.write(`[reaper-mcp-sidecar] ${data}`);
+      });
+    }
+    child.on("exit", (code) => {
+      process.stderr.write(`[reaper-mcp] Sidecar process exited (code ${code})
+`);
+      this.process = null;
+      this.handleProcessDeath();
+    });
+    child.on("error", (err) => {
+      process.stderr.write(`[reaper-mcp] Sidecar spawn error: ${err.message}
+`);
+      this.process = null;
+      this.handleProcessDeath();
+    });
+    this.process = child;
+    this.lineBuffer = "";
+    this.restarting = false;
+    this.restartAttempted = false;
+  }
+  onStdout(chunk) {
+    this.lineBuffer += chunk;
+    let newlineIdx;
+    while ((newlineIdx = this.lineBuffer.indexOf("\n")) !== -1) {
+      const line = this.lineBuffer.slice(0, newlineIdx).trim();
+      this.lineBuffer = this.lineBuffer.slice(newlineIdx + 1);
+      if (line) this.onResponse(line);
+    }
+  }
+  onResponse(line) {
+    let response;
+    try {
+      response = JSON.parse(line);
+    } catch {
+      process.stderr.write(`[reaper-mcp] Sidecar returned malformed JSON: ${line}
+`);
+      for (const [id, { reject }] of this.pending.entries()) {
+        reject(new Error(`Sidecar returned malformed JSON: ${line}`));
+        this.pending.delete(id);
+      }
+      return;
+    }
+    const pending = this.pending.get(response.id);
+    if (!pending) {
+      process.stderr.write(`[reaper-mcp] Sidecar response for unknown id ${response.id}
+`);
+      return;
+    }
+    this.pending.delete(response.id);
+    if (response.error) {
+      pending.reject(new Error(response.error.message));
+    } else if (response.result) {
+      pending.resolve(response.result);
+    } else {
+      pending.reject(new Error("Sidecar response missing both result and error fields"));
+    }
+  }
+  handleProcessDeath() {
+    if (this.restarting || this.pending.size === 0) {
+      return;
+    }
+    if (!this.restartAttempted) {
+      this.restarting = true;
+      this.restartAttempted = true;
+      process.stderr.write("[reaper-mcp] Sidecar crashed; attempting one restart...\n");
+      this.spawn().then(() => {
+        for (const [id, { reject }] of this.pending.entries()) {
+          reject(new Error("Sidecar restarted; please retry the operation"));
+          this.pending.delete(id);
+        }
+      }).catch((err) => {
+        for (const [id, { reject }] of this.pending.entries()) {
+          reject(new Error(`Sidecar restart failed: ${err.message}. Run: node dist/apps/reaper-mcp-server/main.js setup-sidecar`));
+          this.pending.delete(id);
+        }
+      });
+    } else {
+      for (const [id, { reject }] of this.pending.entries()) {
+        reject(new Error("Python sidecar unavailable after restart attempt. Run: node dist/apps/reaper-mcp-server/main.js setup-sidecar"));
+        this.pending.delete(id);
+      }
+    }
+  }
+};
+var _singleton = null;
+function getSidecarClient() {
+  if (!_singleton) {
+    _singleton = new SidecarClientImpl();
+  }
+  return _singleton;
+}
+
+// apps/reaper-mcp-server/src/tools/aesthetics.ts
+var SIDECAR_NOT_INSTALLED_MSG = "Audio understanding sidecar not installed. Run: node dist/apps/reaper-mcp-server/main.js setup-sidecar";
+function registerAestheticsTools(server) {
+  server.tool(
+    "analyze_track_aesthetics",
+    "Analyze the perceptual aesthetic quality of a track's audio using Meta's Audiobox Aesthetics model (CC-BY 4.0). Bounces the track to a temp WAV file (post-FX, post-fader) and runs 4-axis perceptual quality scoring: Production Quality (PQ), Production Complexity (PC), Content Enjoyment (CE), Content Usefulness (CU). Returns scores 0-10. Requires the Python sidecar (run: node dist/apps/reaper-mcp-server/main.js setup-sidecar).",
+    {
+      trackIndex: z17.coerce.number().int().min(0).describe("Zero-based track index"),
+      startTime: z17.coerce.number().min(0).optional().describe("Start time in seconds (default: 0 or use REAPER time selection)"),
+      endTime: z17.coerce.number().min(0).optional().describe("End time in seconds (default: startTime + durationSeconds)"),
+      durationSeconds: z17.coerce.number().min(0.5).max(30).optional().default(5).describe("Duration to analyze in seconds (default 5, max 30). Ignored if endTime is provided.")
+    },
+    async ({ trackIndex, startTime, endTime, durationSeconds }) => {
+      const sidecar = getSidecarClient();
+      if (!sidecar.isAvailable()) {
+        return {
+          content: [{ type: "text", text: SIDECAR_NOT_INSTALLED_MSG }],
+          isError: true
+        };
+      }
+      const resolvedStart = startTime ?? 0;
+      const resolvedEnd = endTime ?? resolvedStart + (durationSeconds ?? 5);
+      if (resolvedEnd <= resolvedStart) {
+        return {
+          content: [{ type: "text", text: "endTime must be greater than startTime" }],
+          isError: true
+        };
+      }
+      const commandId = randomUUID2();
+      const renderRes = await sendCommand("render_track_to_wav", {
+        trackIndex,
+        startTime: resolvedStart,
+        endTime: resolvedEnd,
+        commandId
+      });
+      if (!renderRes.success) {
+        return {
+          content: [{ type: "text", text: `Render failed: ${renderRes.error}` }],
+          isError: true
+        };
+      }
+      const renderData = renderRes.data;
+      const wavPath = renderData.wavPath;
+      try {
+        const scores = await sidecar.analyze(wavPath, resolvedStart, resolvedEnd);
+        const result = {
+          trackIndex,
+          trackName: renderData.trackName,
+          productionQuality: scores.PQ,
+          productionComplexity: scores.PC,
+          contentEnjoyment: scores.CE,
+          contentUsefulness: scores.CU,
+          startTime: resolvedStart,
+          endTime: resolvedEnd,
+          durationSeconds: resolvedEnd - resolvedStart,
+          modelVersion: scores.modelVersion
+        };
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (err) {
+        return {
+          content: [{
+            type: "text",
+            text: err instanceof Error ? err.message : String(err)
+          }],
+          isError: true
+        };
+      } finally {
+        await unlink2(wavPath).catch(() => {
+        });
+      }
+    }
+  );
+}
+
 // apps/reaper-mcp-server/src/server.ts
 function instrumentToolHandlers(server) {
   const originalTool = server.tool.bind(server);
@@ -2291,40 +2573,43 @@ function createServer() {
   registerEnvelopeTools(server);
   registerBatchTools(server);
   registerCategoryTools(server);
+  registerAestheticsTools(server);
   return server;
 }
 
 // apps/reaper-mcp-server/src/main.ts
-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 homedir3 } from "node:os";
+import { existsSync as existsSync5, mkdirSync as mkdirSync4 } from "node:fs";
+import { join as join7, dirname as dirname3 } from "node:path";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
+import { homedir as homedir5, platform as platform4 } from "node:os";
+import { exec as execCb } from "node:child_process";
+import { promisify as promisifyUtil } from "node:util";
 
 // apps/reaper-mcp-server/src/cli.ts
-import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { join as join3 } from "node:path";
+import { copyFileSync, existsSync as existsSync2, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join as join4 } from "node:path";
 function resolveAssetDir(baseDir, name) {
-  const sibling = join3(baseDir, name);
-  if (existsSync(sibling)) return sibling;
-  const parent = join3(baseDir, "..", name);
-  if (existsSync(parent)) return parent;
+  const sibling = join4(baseDir, name);
+  if (existsSync2(sibling)) return sibling;
+  const parent = join4(baseDir, "..", name);
+  if (existsSync2(parent)) return parent;
   let dir = baseDir;
   for (let i = 0; i < 5; i++) {
-    const candidate = join3(dir, name);
-    if (existsSync(candidate)) return candidate;
-    const up = join3(dir, "..");
+    const candidate = join4(dir, name);
+    if (existsSync2(candidate)) return candidate;
+    const up = join4(dir, "..");
     if (up === dir) break;
     dir = up;
   }
   return sibling;
 }
 function copyDirSync(src, dest) {
-  if (!existsSync(src)) return 0;
+  if (!existsSync2(src)) return 0;
   mkdirSync(dest, { recursive: true });
   let count = 0;
   for (const entry of readdirSync(src)) {
-    const srcPath = join3(src, entry);
-    const destPath = join3(dest, entry);
+    const srcPath = join4(src, entry);
+    const destPath = join4(dest, entry);
     if (statSync(srcPath).isDirectory()) {
       count += copyDirSync(srcPath, destPath);
     } else {
@@ -2335,14 +2620,14 @@ function copyDirSync(src, dest) {
   return count;
 }
 function installFile(src, dest) {
-  if (existsSync(src)) {
+  if (existsSync2(src)) {
     copyFileSync(src, dest);
     return true;
   }
   return false;
 }
 function createMcpJson(targetPath) {
-  if (existsSync(targetPath)) return false;
+  if (existsSync2(targetPath)) return false;
   const config = JSON.stringify({
     mcpServers: {
       reaper: {
@@ -2469,12 +2754,16 @@ var MCP_TOOL_NAMES = [
   // progressive discovery
   "list_tool_categories",
   "enable_tool_category",
-  "disable_tool_category"
+  "disable_tool_category",
+  // semantic audio analysis (requires Python sidecar — opt-in)
+  "analyze_track_aesthetics"
+  // Note: 'render_track_to_wav' is an internal Lua bridge command, NOT a public MCP tool.
+  // It must NOT be listed here — MCP_TOOL_NAMES drives the Claude Code allowlist.
 ];
 function ensureClaudeSettings(settingsPath) {
   const allowList = MCP_TOOL_NAMES.map((t) => `mcp__reaper__${t}`);
-  if (!existsSync(settingsPath)) {
-    mkdirSync(join3(settingsPath, ".."), { recursive: true });
+  if (!existsSync2(settingsPath)) {
+    mkdirSync(join4(settingsPath, ".."), { recursive: true });
     const config = { permissions: { allow: allowList } };
     writeFileSync(settingsPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
     return "created";
@@ -2491,21 +2780,21 @@ function ensureClaudeSettings(settingsPath) {
 }
 function resolveAssetDirWithFallback(baseDir, buildName, sourceName) {
   const resolved = resolveAssetDir(baseDir, buildName);
-  if (existsSync(resolved)) return resolved;
+  if (existsSync2(resolved)) return resolved;
   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";
+import { existsSync as existsSync3, mkdirSync as mkdirSync2 } from "node:fs";
+import { join as join5 } from "node:path";
+import { homedir as homedir3 } 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, "..", "..")}
+  console.log(`REAPER resource path: ${join5(bridgeDir, "..", "..")}
 `);
   let selections;
   if (headless) {
@@ -2550,27 +2839,27 @@ async function runInit(opts, dirResolver) {
       skillsScope
     };
   }
-  const __dirname2 = dirResolver();
+  const __dirname3 = dirResolver();
   if (selections.bridge) {
     console.log("Installing REAPER Bridge...");
     const scriptsDir = getReaperScriptsPath();
     mkdirSync2(scriptsDir, { recursive: true });
-    const reaperDir = resolveAssetDir(__dirname2, "reaper");
+    const reaperDir = resolveAssetDir(__dirname3, "reaper");
     for (const luaFile of ["mcp_bridge.lua", "mcp_snapshot_manager.lua"]) {
-      const src = join4(reaperDir, luaFile);
-      const dest = join4(scriptsDir, luaFile);
+      const src = join5(reaperDir, luaFile);
+      const dest = join5(scriptsDir, luaFile);
       if (installFile(src, dest)) {
         console.log(`  Installed: ${luaFile}`);
       } else {
         console.log(`  Not found: ${src}`);
       }
     }
-    const effectsDir = join4(getReaperEffectsPath(), "reaper-mcp");
+    const effectsDir = join5(getReaperEffectsPath(), "reaper-mcp");
     mkdirSync2(effectsDir, { recursive: true });
     for (const asset of REAPER_ASSETS) {
       if (asset.endsWith(".lua")) continue;
-      const src = join4(reaperDir, asset);
-      const dest = join4(effectsDir, asset);
+      const src = join5(reaperDir, asset);
+      const dest = join5(effectsDir, asset);
       if (installFile(src, dest)) {
         console.log(`  Installed: reaper-mcp/${asset}`);
       } else {
@@ -2581,32 +2870,32 @@ async function runInit(opts, dirResolver) {
   }
   if (selections.skills) {
     const isGlobal = selections.skillsScope === "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");
     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 knowledgeSrc = resolveAssetDir(__dirname3, "knowledge");
+    if (existsSync3(knowledgeSrc)) {
+      const dest = join5(isGlobal ? join5(homedir3(), ".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 rulesSrc = resolveAssetDirWithFallback(__dirname3, "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`);
     }
-    const skillsSrc = resolveAssetDirWithFallback(__dirname2, "claude-skills", join4(".claude", "skills"));
-    if (existsSync2(skillsSrc)) {
-      const dest = join4(claudeDir, "skills");
+    const skillsSrc = resolveAssetDirWithFallback(__dirname3, "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`);
     }
-    const agentsSrc = resolveAssetDirWithFallback(__dirname2, "claude-agents", join4(".claude", "agents"));
-    if (existsSync2(agentsSrc)) {
-      const dest = join4(claudeDir, "agents");
+    const agentsSrc = resolveAssetDirWithFallback(__dirname3, "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`);
     }
@@ -2614,8 +2903,8 @@ async function runInit(opts, dirResolver) {
   }
   if (selections.settings) {
     console.log("Configuring Claude Code Settings...");
-    const settingsDir = join4(homedir2(), ".claude");
-    const settingsPath = join4(settingsDir, "settings.json");
+    const settingsDir = join5(homedir3(), ".claude");
+    const settingsPath = join5(settingsDir, "settings.json");
     const result = ensureClaudeSettings(settingsPath);
     if (result === "created") {
       console.log(`  Created: ${settingsPath}`);
@@ -2628,7 +2917,7 @@ async function runInit(opts, dirResolver) {
   }
   if (selections.projectConfig) {
     console.log("Creating Project Config...");
-    const mcpJsonPath = join4(process.cwd(), ".mcp.json");
+    const mcpJsonPath = join5(process.cwd(), ".mcp.json");
     if (createMcpJson(mcpJsonPath)) {
       console.log(`  Created: ${mcpJsonPath}`);
     } else {
@@ -2639,18 +2928,18 @@ async function runInit(opts, dirResolver) {
   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 globalClaudeDir = join5(homedir3(), ".claude");
+  const localAgents = existsSync3(join5(process.cwd(), ".claude", "agents"));
+  const globalAgents = existsSync3(join5(globalClaudeDir, "agents"));
   const agentsExist = localAgents || globalAgents;
   console.log(`  Mix agents:    ${agentsExist ? "Installed" : "Not installed"}`);
-  const mcpJsonExists = existsSync2(join4(process.cwd(), ".mcp.json"));
+  const mcpJsonExists = existsSync3(join5(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");
+    const luaDest = join5(scriptsDir, "mcp_bridge.lua");
     console.log("  1. Open REAPER");
     console.log("  2. Actions > Show action list > Load ReaScript");
     console.log(`  3. Select: ${luaDest}`);
@@ -2665,33 +2954,206 @@ async function runInit(opts, dirResolver) {
   }
 }
 
-// apps/reaper-mcp-server/src/main.ts
+// apps/reaper-mcp-server/src/setup-sidecar.ts
+import { exec as execImpl } from "node:child_process";
+import { existsSync as existsSync4, mkdirSync as mkdirSync3, copyFileSync as copyFileSync2, rmSync } from "node:fs";
+import { join as join6, dirname as dirname2 } from "node:path";
+import { homedir as homedir4, platform as platform3 } from "node:os";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+var VENV_BIN2 = platform3() === "win32" ? "Scripts" : "bin";
+var VENV_PYTHON_NAME2 = platform3() === "win32" ? "python.exe" : "python";
+var VENV_PIP_NAME = platform3() === "win32" ? "pip.exe" : "pip";
+function exec(cmd) {
+  return new Promise((resolve, reject) => {
+    execImpl(cmd, (err, stdout, stderr) => {
+      if (err) reject(err);
+      else resolve({ stdout, stderr });
+    });
+  });
+}
 var __dirname = dirname2(fileURLToPath2(import.meta.url));
+var SIDECAR_VENV_PATH2 = join6(homedir4(), ".reaper-mcp", "sidecar-venv");
+var SIDECAR_DIR = join6(homedir4(), ".reaper-mcp", "sidecar");
+var SIDECAR_SCRIPT_DEST = join6(SIDECAR_DIR, "server.py");
+var MODEL_ID = "facebook/audiobox-aesthetics";
+var MIN_PYTHON_MAJOR = 3;
+var MIN_PYTHON_MINOR = 10;
+function getPythonBin() {
+  return process.env["PYTHON_BIN"] ?? "python3";
+}
+function parsePythonVersion(output) {
+  const match = output.match(/Python\s+(\d+)\.(\d+)\.(\d+)/i);
+  if (!match) return null;
+  return [parseInt(match[1], 10), parseInt(match[2], 10), parseInt(match[3], 10)];
+}
+async function checkPython(pythonBin) {
+  let stdout;
+  try {
+    const result = await exec(`"${pythonBin}" --version`);
+    stdout = (result.stdout + result.stderr).trim();
+  } catch {
+    const notFound = `Python interpreter not found: ${pythonBin}
+Install Python 3.10+ from https://python.org or set the PYTHON_BIN environment variable.
+Example: PYTHON_BIN=/usr/local/bin/python3.11 node dist/apps/reaper-mcp-server/main.js setup-sidecar`;
+    throw new Error(notFound);
+  }
+  const version = parsePythonVersion(stdout);
+  if (!version) {
+    throw new Error(`Could not parse Python version from: "${stdout}". Is PYTHON_BIN set correctly?`);
+  }
+  const [major, minor, patch] = version;
+  if (major < MIN_PYTHON_MAJOR || major === MIN_PYTHON_MAJOR && minor < MIN_PYTHON_MINOR) {
+    throw new Error(
+      `Python ${MIN_PYTHON_MAJOR}.${MIN_PYTHON_MINOR}+ required. Found: ${major}.${minor}.${patch} at ${pythonBin}.
+Install Python 3.10+ from https://python.org or set PYTHON_BIN to a newer interpreter.`
+    );
+  }
+  return `${major}.${minor}.${patch}`;
+}
+async function createVenv(pythonBin) {
+  mkdirSync3(join6(homedir4(), ".reaper-mcp"), { recursive: true });
+  await exec(`"${pythonBin}" -m venv --clear "${SIDECAR_VENV_PATH2}"`);
+}
+function cleanupBrokenVenv() {
+  try {
+    if (existsSync4(SIDECAR_VENV_PATH2)) {
+      rmSync(SIDECAR_VENV_PATH2, { recursive: true, force: true });
+    }
+  } catch {
+  }
+}
+function resolveRequirementsTxt(baseDir) {
+  const sidecarDir = resolveAssetDir(baseDir, "sidecar");
+  return join6(sidecarDir, "requirements.txt");
+}
+async function installDeps(requirementsPath) {
+  const pip = join6(SIDECAR_VENV_PATH2, VENV_BIN2, VENV_PIP_NAME);
+  await exec(`"${pip}" install --upgrade pip`);
+  const { stdout, stderr } = await exec(`"${pip}" install -r "${requirementsPath}"`);
+  if (stdout) process.stdout.write(stdout);
+  if (stderr) process.stderr.write(stderr);
+}
+async function downloadModelWeights() {
+  const python = join6(SIDECAR_VENV_PATH2, VENV_BIN2, VENV_PYTHON_NAME2);
+  const script = [
+    "from huggingface_hub import snapshot_download",
+    `print("Downloading ${MODEL_ID} weights to ~/.cache/huggingface/hub/ ...")`,
+    `snapshot_download("${MODEL_ID}")`,
+    `print("Download complete.")`
+  ].join("; ");
+  const { stdout, stderr } = await exec(`"${python}" -c "${script}"`);
+  if (stdout) process.stdout.write(stdout);
+  if (stderr) process.stderr.write(stderr);
+}
+function copySidecarScript(baseDir) {
+  const sidecarDir = resolveAssetDir(baseDir, "sidecar");
+  const src = join6(sidecarDir, "server.py");
+  if (!existsSync4(src)) {
+    throw new Error(
+      `sidecar/server.py not found at: ${src}
+Run \`pnpm nx build reaper-mcp-server\` first.`
+    );
+  }
+  mkdirSync3(SIDECAR_DIR, { recursive: true });
+  copyFileSync2(src, SIDECAR_SCRIPT_DEST);
+}
+async function setupSidecar() {
+  console.log("REAPER MCP \u2014 Setup Python Sidecar\n");
+  console.log("This installs the opt-in audio AI subsystem for perceptual analysis.");
+  console.log("Requires Python 3.10+ and an internet connection (~831 MB download).\n");
+  const pythonBin = getPythonBin();
+  console.log(`Checking Python interpreter: ${pythonBin}`);
+  let version;
+  try {
+    version = await checkPython(pythonBin);
+  } catch (err) {
+    console.error(`
+Error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+  console.log(`  Using Python interpreter: ${pythonBin} (${version})`);
+  console.log(`
+Creating virtual environment at: ${SIDECAR_VENV_PATH2}`);
+  try {
+    await createVenv(pythonBin);
+    console.log("  Virtual environment created.");
+  } catch (err) {
+    console.error(`
+Failed to create venv: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+  const requirementsPath = resolveRequirementsTxt(__dirname);
+  console.log(`
+Installing Python dependencies from: ${requirementsPath}`);
+  if (!existsSync4(requirementsPath)) {
+    console.error(`
+Error: requirements.txt not found at: ${requirementsPath}`);
+    console.error("Run `pnpm nx build reaper-mcp-server` first.");
+    process.exit(1);
+  }
+  try {
+    await installDeps(requirementsPath);
+    console.log("  Dependencies installed.");
+  } catch (err) {
+    console.error(`
+Failed to install dependencies: ${err instanceof Error ? err.message : String(err)}`);
+    cleanupBrokenVenv();
+    console.error("Removed partial venv so the next setup-sidecar run starts clean.");
+    process.exit(1);
+  }
+  console.log("\nPre-downloading Audiobox Aesthetics model weights (~831 MB)...");
+  console.log("This may take several minutes depending on your internet connection.");
+  try {
+    await downloadModelWeights();
+  } catch (err) {
+    console.error(`
+Model download failed: ${err instanceof Error ? err.message : String(err)}`);
+    console.error("Check your internet connection and run setup-sidecar again.");
+    process.exit(1);
+  }
+  console.log(`
+Installing sidecar script to: ${SIDECAR_SCRIPT_DEST}`);
+  try {
+    copySidecarScript(__dirname);
+    console.log("  Sidecar script installed.");
+  } catch (err) {
+    console.error(`
+Failed to install sidecar script: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+  console.log("\nSidecar setup complete!\n");
+  console.log("The analyze_track_aesthetics tool is now available.");
+  console.log("Run `node dist/apps/reaper-mcp-server/main.js doctor` to verify.\n");
+}
+
+// apps/reaper-mcp-server/src/main.ts
+var execAsync = promisifyUtil(execCb);
+var __dirname2 = dirname3(fileURLToPath3(import.meta.url));
 async function setup() {
   console.log("REAPER MCP Server \u2014 Setup\n");
   const bridgeDir = await ensureBridgeDir();
   console.log(`Bridge directory: ${bridgeDir}
 `);
   const scriptsDir = getReaperScriptsPath();
-  mkdirSync3(scriptsDir, { recursive: true });
-  const reaperDir = resolveAssetDir(__dirname, "reaper");
+  mkdirSync4(scriptsDir, { recursive: true });
+  const reaperDir = resolveAssetDir(__dirname2, "reaper");
   console.log("Installing Lua scripts...");
   for (const luaFile of ["mcp_bridge.lua", "mcp_snapshot_manager.lua"]) {
-    const src = join5(reaperDir, luaFile);
-    const dest = join5(scriptsDir, luaFile);
+    const src = join7(reaperDir, luaFile);
+    const dest = join7(scriptsDir, luaFile);
     if (installFile(src, dest)) {
       console.log(`  Installed: ${luaFile}`);
     } else {
       console.log(`  Not found: ${src}`);
     }
   }
-  const effectsDir = join5(getReaperEffectsPath(), "reaper-mcp");
-  mkdirSync3(effectsDir, { recursive: true });
+  const effectsDir = join7(getReaperEffectsPath(), "reaper-mcp");
+  mkdirSync4(effectsDir, { recursive: true });
   console.log("\nInstalling JSFX analyzers...");
   for (const asset of REAPER_ASSETS) {
     if (asset.endsWith(".lua")) continue;
-    const src = join5(reaperDir, asset);
-    const dest = join5(effectsDir, asset);
+    const src = join7(reaperDir, asset);
+    const dest = join7(effectsDir, asset);
     if (installFile(src, dest)) {
       console.log(`  Installed: reaper-mcp/${asset}`);
     } else {
@@ -2702,7 +3164,7 @@ async function setup() {
   console.log("Next steps:");
   console.log("  1. Open REAPER");
   console.log("  2. Actions > Show action list > Load ReaScript");
-  console.log(`  3. Select: ${join5(scriptsDir, "mcp_bridge.lua")}`);
+  console.log(`  3. Select: ${join7(scriptsDir, "mcp_bridge.lua")}`);
   console.log("  4. Run the script (it will keep running in background via defer loop)");
   console.log("  5. Add reaper-mcp to your Claude Code config (see: npx @mthines/reaper-mcp doctor)");
 }
@@ -2714,41 +3176,41 @@ async function installSkills(scope) {
   console.log(`REAPER MCP \u2014 Install AI Mix Engineer Skills (scope: ${scope})
 `);
   const isGlobal = scope === "global";
-  const baseDir = isGlobal ? join5(homedir3(), ".claude") : process.cwd();
-  const claudeDir = isGlobal ? baseDir : join5(baseDir, ".claude");
-  const knowledgeSrc = resolveAssetDir(__dirname, "knowledge");
-  if (existsSync3(knowledgeSrc)) {
-    const dest = join5(baseDir, "knowledge");
+  const baseDir = isGlobal ? join7(homedir5(), ".claude") : process.cwd();
+  const claudeDir = isGlobal ? baseDir : join7(baseDir, ".claude");
+  const knowledgeSrc = resolveAssetDir(__dirname2, "knowledge");
+  if (existsSync5(knowledgeSrc)) {
+    const dest = join7(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", join5(".claude", "rules"));
-  if (existsSync3(rulesSrc)) {
-    const dest = join5(claudeDir, "rules");
+  const rulesSrc = resolveAssetDirWithFallback(__dirname2, "claude-rules", join7(".claude", "rules"));
+  if (existsSync5(rulesSrc)) {
+    const dest = join7(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", join5(".claude", "skills"));
-  if (existsSync3(skillsSrc)) {
-    const dest = join5(claudeDir, "skills");
+  const skillsSrc = resolveAssetDirWithFallback(__dirname2, "claude-skills", join7(".claude", "skills"));
+  if (existsSync5(skillsSrc)) {
+    const dest = join7(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", join5(".claude", "agents"));
-  if (existsSync3(agentsSrc)) {
-    const dest = join5(claudeDir, "agents");
+  const agentsSrc = resolveAssetDirWithFallback(__dirname2, "claude-agents", join7(".claude", "agents"));
+  if (existsSync5(agentsSrc)) {
+    const dest = join7(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 = join5(claudeDir, "settings.json");
+  const settingsPath = join7(claudeDir, "settings.json");
   const result = ensureClaudeSettings(settingsPath);
   if (result === "created") {
     console.log(`Created Claude settings: ${settingsPath}`);
@@ -2758,7 +3220,7 @@ async function installSkills(scope) {
     console.log(`Claude settings already has all REAPER tools: ${settingsPath}`);
   }
   if (!isGlobal) {
-    const mcpJsonPath = join5(baseDir, ".mcp.json");
+    const mcpJsonPath = join7(baseDir, ".mcp.json");
     if (createMcpJson(mcpJsonPath)) {
       console.log(`
 Created: ${mcpJsonPath}`);
@@ -2779,31 +3241,92 @@ async function doctor() {
   if (!bridgeRunning) {
     console.log('  \u2192 Run "npx @mthines/reaper-mcp setup" then load mcp_bridge.lua in REAPER');
   }
-  const globalClaudeDir = join5(homedir3(), ".claude");
-  const localAgents = existsSync3(join5(process.cwd(), ".claude", "agents"));
-  const globalAgents = existsSync3(join5(globalClaudeDir, "agents"));
+  const globalClaudeDir = join7(homedir5(), ".claude");
+  const localAgents = existsSync5(join7(process.cwd(), ".claude", "agents"));
+  const globalAgents = existsSync5(join7(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 = existsSync3(join5(process.cwd(), "knowledge"));
-  const globalKnowledge = existsSync3(join5(globalClaudeDir, "knowledge"));
+  const localKnowledge = existsSync5(join7(process.cwd(), "knowledge"));
+  const globalKnowledge = existsSync5(join7(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 = existsSync3(join5(process.cwd(), ".mcp.json"));
+  const mcpJsonExists = existsSync5(join7(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');
   }
   console.log('\nTo check SWS Extensions, start REAPER and use the "list_available_fx" tool.');
   console.log("SWS provides enhanced plugin discovery and snapshot support.\n");
-  process.exit(bridgeRunning && knowledgeExists && mcpJsonExists ? 0 : 1);
+  console.log("Python Sidecar (opt-in, for analyze_track_aesthetics):");
+  const sidecarVenvPath = join7(homedir5(), ".reaper-mcp", "sidecar-venv");
+  const venvBin = platform4() === "win32" ? "Scripts" : "bin";
+  const venvPythonName = platform4() === "win32" ? "python.exe" : "python";
+  const venvPython = join7(sidecarVenvPath, venvBin, venvPythonName);
+  const hfCachePath = join7(homedir5(), ".cache", "huggingface", "hub");
+  let pythonOk = false;
+  let pythonDetail = "not found";
+  try {
+    const pythonBin = process.env["PYTHON_BIN"] ?? "python3";
+    const { stdout, stderr } = await execAsync(`"${pythonBin}" --version`);
+    const versionStr = (stdout + stderr).trim();
+    const match = versionStr.match(/Python\s+(\d+)\.(\d+)/i);
+    if (match) {
+      const major = parseInt(match[1], 10);
+      const minor = parseInt(match[2], 10);
+      pythonOk = major > 3 || major === 3 && minor >= 10;
+      pythonDetail = versionStr;
+    }
+  } catch {
+    pythonDetail = "not found";
+  }
+  console.log(`  Python \u2265 3.10:  ${pythonOk ? `\u2713 ${pythonDetail}` : `\u2717 ${pythonDetail}`}`);
+  if (!pythonOk) {
+    console.log("    \u2192 Install Python 3.10+ from https://python.org or set PYTHON_BIN");
+  }
+  const venvExists = existsSync5(sidecarVenvPath);
+  console.log(`  Venv:           ${venvExists ? `\u2713 ${sidecarVenvPath}` : "\u2717 Not installed"}`);
+  if (!venvExists) {
+    console.log("    \u2192 Run: node dist/apps/reaper-mcp-server/main.js setup-sidecar");
+  }
+  let depsOk = false;
+  if (venvExists && existsSync5(venvPython)) {
+    try {
+      await execAsync(`"${venvPython}" -c "import audiobox_aesthetics"`);
+      depsOk = true;
+    } catch {
+      depsOk = false;
+    }
+  }
+  console.log(`  Dependencies:   ${depsOk ? "\u2713 audiobox-aesthetics importable" : "\u2717 Not installed"}`);
+  if (!depsOk && venvExists) {
+    console.log("    \u2192 Run: node dist/apps/reaper-mcp-server/main.js setup-sidecar");
+  }
+  const weightsPath = join7(hfCachePath, "models--facebook--audiobox-aesthetics");
+  const weightsExist = existsSync5(weightsPath);
+  console.log(`  Model weights:  ${weightsExist ? `\u2713 ${weightsPath}` : "\u2717 Not downloaded"}`);
+  if (!weightsExist) {
+    console.log("    \u2192 Run: node dist/apps/reaper-mcp-server/main.js setup-sidecar");
+  }
+  const sidecarReady = venvExists && depsOk && weightsExist;
+  const sidecarOptedIn = venvExists || weightsExist;
+  const sidecarBroken = sidecarOptedIn && !sidecarReady;
+  if (!sidecarOptedIn) {
+    console.log("\n  Sidecar: not installed (opt-in). Run setup-sidecar to enable audio AI tools.");
+  } else if (sidecarBroken) {
+    console.log("\n  Sidecar: PARTIALLY INSTALLED \u2014 run setup-sidecar to repair.");
+  } else {
+    console.log("\n  Sidecar: fully installed and ready.");
+  }
+  console.log("");
+  process.exit(bridgeRunning && knowledgeExists && mcpJsonExists && !sidecarBroken ? 0 : 1);
 }
 async function serve() {
   const log = (...args) => console.error("[reaper-mcp]", ...args);
@@ -2812,7 +3335,7 @@ async function serve() {
   startDiagnosticsPoller();
   startEventsPoller();
   log("Starting REAPER MCP Server...");
-  log(`Entry: ${fileURLToPath2(import.meta.url)}`);
+  log(`Entry: ${fileURLToPath3(import.meta.url)}`);
   const tracer = getTracer();
   await tracer.startActiveSpan("mcp.server.startup", { kind: SpanKind3.INTERNAL }, async (startupSpan) => {
     try {
@@ -2866,7 +3389,7 @@ switch (command) {
   case "init":
     runInit(
       { yes: hasYesFlag, project: hasProjectFlag },
-      () => __dirname
+      () => __dirname2
     ).catch((err) => {
       console.error("Init failed:", err);
       process.exit(1);
@@ -2890,6 +3413,12 @@ switch (command) {
       process.exit(1);
     });
     break;
+  case "setup-sidecar":
+    setupSidecar().catch((err) => {
+      console.error("Sidecar setup failed:", err);
+      process.exit(1);
+    });
+    break;
   case "status": {
     (async () => {
       const running = await isBridgeRunning();
@@ -2915,6 +3444,7 @@ Usage:
   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 setup-sidecar    Install Python sidecar for perceptual audio analysis (opt-in, ~831 MB)
   npx @mthines/reaper-mcp install-skills   Install AI knowledge + agents globally (default)
   npx @mthines/reaper-mcp install-skills --project  Install into current project directory
   npx @mthines/reaper-mcp install-skills --global   Install into ~/.claude/ (default)
@@ -2936,24 +3466,31 @@ Tip: install globally for shorter commands:
 `);
     break;
 }
+function shutdownAll() {
+  stopPollers();
+  try {
+    getSidecarClient().shutdown();
+  } catch {
+  }
+}
 process.on("SIGINT", () => {
   console.error("[reaper-mcp] Interrupted");
-  stopPollers();
+  shutdownAll();
   shutdownTelemetry().finally(() => process.exit(0));
 });
 process.on("SIGTERM", () => {
   console.error("[reaper-mcp] Terminated");
-  stopPollers();
+  shutdownAll();
   shutdownTelemetry().finally(() => process.exit(0));
 });
 process.on("uncaughtException", (err) => {
   console.error("[reaper-mcp] Uncaught exception:", err);
-  stopPollers();
+  shutdownAll();
   shutdownTelemetry().finally(() => process.exit(1));
 });
 process.on("unhandledRejection", (reason) => {
   console.error("[reaper-mcp] Unhandled rejection:", reason);
-  stopPollers();
+  shutdownAll();
   shutdownTelemetry().finally(() => process.exit(1));
 });
 //# sourceMappingURL=main.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mthines/reaper-mcp",
-  "version": "0.19.0-beta.20.2",
+  "version": "0.19.0",
   "type": "module",
   "description": "MCP server for controlling REAPER DAW — real-time mixing, FX control, and frequency analysis for AI agents",
   "license": "MIT",

package/reaper/mcp_bridge.lua

@@ -1533,7 +1533,11 @@ 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_MIDI_EMITTER_FX_NAME      = "reaper-mcp/mcp_midi_emitter"
-local MCP_FX_PREFIX                 = "reaper%-mcp/"  -- Lua pattern for matching MCP JSFX names
+-- Lua pattern matching the JSFX `desc:` line — that's what TrackFX_GetFXName
+-- returns, not the on-disk path. Every MCP JSFX starts its desc with "MCP ".
+-- (The outer container is renamed to "MCP Meters", but this prefix is only used
+-- to identify the JSFX *inside* a container, so collisions are not possible.)
+local MCP_FX_PREFIX                 = "MCP "
 
 -- 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).
@@ -3612,6 +3616,187 @@ function handlers.send_midi_note(params)
   return { sent = true, timestampMs = math.floor(reaper.time_precise() * 1000) }
 end
 
+-- =============================================================================
+-- render_track_to_wav handler
+--
+-- Renders a target track's output (post-FX, post-fader) to a temp WAV file.
+-- Saves and restores all render settings and solo states around the render.
+-- Blocks the defer loop during render (~0.5-1s) — this is by design.
+--
+-- Params:
+--   trackIndex  (number) — zero-based track index
+--   startTime   (number) — render start, seconds from project start
+--   endTime     (number) — render end, seconds from project start
+--   commandId   (string) — used to generate a unique temp filename
+--
+-- Returns:
+--   { trackIndex, trackName, wavPath, durationSeconds, sampleRate, channelCount }
+-- =============================================================================
+
+function handlers.render_track_to_wav(params)
+  local track_index = params.trackIndex
+  local start_time  = params.startTime
+  local end_time    = params.endTime
+  local command_id  = params.commandId or tostring(os.time())
+
+  -- Validate inputs
+  if track_index == nil then
+    return nil, "Missing required param: trackIndex"
+  end
+  if start_time == nil or end_time == nil then
+    return nil, "Missing required params: startTime, endTime"
+  end
+  if end_time <= start_time then
+    return nil, "endTime must be greater than startTime"
+  end
+
+  -- Get track
+  local track = reaper.GetTrack(0, track_index)
+  if not track then
+    return nil, "Track " .. tostring(track_index) .. " not found"
+  end
+  local track_name = ({reaper.GetSetMediaTrackInfo_String(track, "P_NAME", "", false)})[2] or ""
+  if track_name == "" then track_name = "Track " .. (track_index + 1) end
+
+  -- Render target is always 44100 Hz (WAV for sidecar inference).
+  -- The actual project sample rate is irrelevant here; Audiobox resamples internally.
+  local sample_rate = 44100
+
+  -- Build unique temp file path
+  -- Use GetTempPath() if available (REAPER 6.29+), fall back to os.tmpname pattern
+  local temp_dir
+  if reaper.GetTempPath then
+    temp_dir = reaper.GetTempPath()
+  else
+    -- Fallback: derive temp dir from os.tmpname()
+    local t = os.tmpname()
+    temp_dir = t:match("^(.+)[/\\][^/\\]+$") or "/tmp"
+    os.remove(t)
+  end
+
+  -- Ensure temp dir ends with separator
+  if temp_dir:sub(-1) ~= "/" and temp_dir:sub(-1) ~= "\\" then
+    temp_dir = temp_dir .. "/"
+  end
+
+  local wav_filename = "mcp_aes_" .. command_id:gsub("-", ""):sub(1, 16) .. ".wav"
+  local wav_path = temp_dir .. wav_filename
+
+  -- -------------------------------------------------------------------------
+  -- Save current render settings
+  -- -------------------------------------------------------------------------
+  local saved_file     = ({reaper.GetSetProjectInfo_String(0, "RENDER_FILE",       "", false)})[2] or ""
+  local saved_pattern  = ({reaper.GetSetProjectInfo_String(0, "RENDER_PATTERN",    "", false)})[2] or ""
+  local saved_format   = ({reaper.GetSetProjectInfo_String(0, "RENDER_FORMAT",     "", false)})[2] or ""
+  local saved_bounds   = reaper.GetSetProjectInfo(0, "RENDER_BOUNDSFLAG", 0, false)
+  local saved_settings = reaper.GetSetProjectInfo(0, "RENDER_SETTINGS",   0, false)
+  local saved_start    = reaper.GetSetProjectInfo(0, "RENDER_STARTPOS",   0, false)
+  local saved_end      = reaper.GetSetProjectInfo(0, "RENDER_ENDPOS",     0, false)
+  local saved_srate    = reaper.GetSetProjectInfo(0, "RENDER_SRATE",      0, false)
+  local saved_channels = reaper.GetSetProjectInfo(0, "RENDER_CHANNELS",   0, false)
+
+  -- Save solo states for all tracks
+  local track_count = reaper.CountTracks(0)
+  local saved_solo_states = {}
+  for i = 0, track_count - 1 do
+    local t = reaper.GetTrack(0, i)
+    saved_solo_states[i] = reaper.GetMediaTrackInfo_Value(t, "I_SOLO")
+  end
+
+  -- -------------------------------------------------------------------------
+  -- Apply render settings
+  -- -------------------------------------------------------------------------
+  local ok, restore_err = pcall(function()
+    -- Set output: render to temp dir with unique filename (no extension in pattern)
+    reaper.GetSetProjectInfo_String(0, "RENDER_FILE",    temp_dir,     true)
+    reaper.GetSetProjectInfo_String(0, "RENDER_PATTERN", wav_filename:match("^(.+)%.wav$") or wav_filename, true)
+
+    -- Set render bounds: 0 = custom time range
+    reaper.GetSetProjectInfo(0, "RENDER_BOUNDSFLAG", 0, true)
+    reaper.GetSetProjectInfo(0, "RENDER_STARTPOS", start_time, true)
+    reaper.GetSetProjectInfo(0, "RENDER_ENDPOS",   end_time,   true)
+
+    -- Set render mode: 2 = stems (selected tracks via master mix / solo)
+    reaper.GetSetProjectInfo(0, "RENDER_SETTINGS", 2, true)
+
+    -- Force WAV at 44100 Hz stereo so the sidecar always gets a known format,
+    -- independent of whatever the user last rendered. Restored in finally.
+    -- "evaw" is the little-endian "wave" fourcc REAPER uses for WAV format.
+    reaper.GetSetProjectInfo_String(0, "RENDER_FORMAT", "evaw", true)
+    reaper.GetSetProjectInfo(0, "RENDER_SRATE",    sample_rate, true)
+    reaper.GetSetProjectInfo(0, "RENDER_CHANNELS", 2,           true)
+
+    -- Unsolo all tracks, then solo only the target track
+    for i = 0, track_count - 1 do
+      local t = reaper.GetTrack(0, i)
+      reaper.SetMediaTrackInfo_Value(t, "I_SOLO", 0)
+    end
+    reaper.SetMediaTrackInfo_Value(track, "I_SOLO", 1)
+
+    -- Trigger render: action 42230 = "Render project, using the most recent render settings, auto-close render dialog"
+    -- This call is synchronous — it blocks the defer loop until rendering completes.
+    reaper.Main_OnCommand(42230, 0)
+  end)
+
+  -- -------------------------------------------------------------------------
+  -- Restore all settings and solo states (always, even on error)
+  -- -------------------------------------------------------------------------
+  local restore_ok, restore_err2 = pcall(function()
+    reaper.GetSetProjectInfo_String(0, "RENDER_FILE",       saved_file,     true)
+    reaper.GetSetProjectInfo_String(0, "RENDER_PATTERN",    saved_pattern,  true)
+    reaper.GetSetProjectInfo_String(0, "RENDER_FORMAT",     saved_format,   true)
+    reaper.GetSetProjectInfo(0, "RENDER_BOUNDSFLAG", saved_bounds,   true)
+    reaper.GetSetProjectInfo(0, "RENDER_SETTINGS",   saved_settings, true)
+    reaper.GetSetProjectInfo(0, "RENDER_STARTPOS",   saved_start,    true)
+    reaper.GetSetProjectInfo(0, "RENDER_ENDPOS",     saved_end,      true)
+    reaper.GetSetProjectInfo(0, "RENDER_SRATE",      saved_srate,    true)
+    reaper.GetSetProjectInfo(0, "RENDER_CHANNELS",   saved_channels, true)
+    for i = 0, track_count - 1 do
+      local t = reaper.GetTrack(0, i)
+      reaper.SetMediaTrackInfo_Value(t, "I_SOLO", saved_solo_states[i] or 0)
+    end
+  end)
+
+  if not restore_ok then
+    -- Log but don't fail — the render may have succeeded
+    reaper.ShowConsoleMsg("[reaper-mcp] Warning: failed to restore render settings: " .. tostring(restore_err2) .. "\n")
+  end
+
+  if not ok then
+    return nil, "Render failed: " .. tostring(restore_err)
+  end
+
+  -- Verify the file was actually created.
+  -- RENDER_PATTERN was set without the .wav extension so REAPER appends it;
+  -- wav_path already has the full expected name including the extension.
+  local f = io.open(wav_path, "rb")
+  if not f then
+    return nil, "Render produced no output file at: " .. wav_path
+  end
+  -- Verify the rendered file is actually a WAV. RENDER_FORMAT was set to "evaw"
+  -- (REAPER's WAV fourcc) above; if REAPER silently ignored that value the file
+  -- could be any codec the user last rendered (MP3/FLAC/etc.). Check the RIFF
+  -- magic bytes so we fail loudly here rather than crashing in the Python sidecar
+  -- with a confusing "Cannot read audio file" error.
+  local magic = f:read(4)
+  f:close()
+  if magic ~= "RIFF" then
+    os.remove(wav_path)
+    return nil, "Render produced a non-WAV file (RENDER_FORMAT may not have been applied). " ..
+                "First 4 bytes: " .. (magic and string.format("%q", magic) or "<empty>")
+  end
+
+  local duration = end_time - start_time
+  return {
+    trackIndex     = track_index,
+    trackName      = track_name,
+    wavPath        = wav_path,
+    durationSeconds = duration,
+    sampleRate     = sample_rate,
+    channelCount   = 2,
+  }
+end
+
 -- =============================================================================
 -- Bridge diagnostics handler
 -- =============================================================================