@mthines/reaper-mcp 0.11.0 → 0.12.0

package/main.js

@@ -838,13 +838,15 @@ import { z as z7 } from "zod/v4";
 function registerSnapshotTools(server) {
   server.tool(
     "snapshot_save",
-    "Save the current mixer state as a named snapshot. Uses SWS Snapshots if available, otherwise captures track volumes, pans, mutes, solos, and FX bypass states manually.",
+    'Save the current mixer state as a named snapshot. Stored in .reaper-mcp/snapshots/ alongside the project file (falls back to global bridge dir for unsaved projects). Captures track volumes, pans, mutes, solos, FX bypass/offline states, full FX parameter values, preset names, track names/colors, and send levels. Response includes storageLocation ("project" or "global").',
     {
       name: z7.string().min(1).describe('Unique snapshot name (e.g. "before-compression", "v1-mix")'),
-      description: z7.string().optional().describe("Optional human-readable description")
+      description: z7.string().optional().describe("Optional human-readable description"),
+      includeFxParams: z7.boolean().optional().default(true).describe("Include FX parameter values in snapshot (default true)"),
+      maxParamsPerFx: z7.coerce.number().int().min(1).max(2e3).optional().default(500).describe("Max parameters to capture per FX plugin (default 500)")
     },
-    async ({ name, description }) => {
-      const res = await sendCommand("snapshot_save", { name, description });
+    async ({ name, description, includeFxParams, maxParamsPerFx }) => {
+      const res = await sendCommand("snapshot_save", { name, description, includeFxParams, maxParamsPerFx });
       if (!res.success) {
         return { content: [{ type: "text", text: `Error: ${res.error}` }], isError: true };
       }
@@ -853,12 +855,14 @@ function registerSnapshotTools(server) {
   );
   server.tool(
     "snapshot_restore",
-    "Restore a previously saved mixer snapshot by name",
+    "Restore a previously saved mixer snapshot by name. Reads from .reaper-mcp/snapshots/ alongside the project file (falls back to global bridge dir for unsaved projects). Restores volumes, pans, mutes, solos, FX states, and optionally FX parameters (if snapshot is v2). FX parameters are only restored when the plugin name matches the snapshot to prevent applying wrong values.",
     {
-      name: z7.string().min(1).describe("Name of the snapshot to restore")
+      name: z7.string().min(1).describe("Name of the snapshot to restore"),
+      restoreTrackMeta: z7.boolean().optional().default(false).describe("Also restore track names and colors (default false)"),
+      restoreSendLevels: z7.boolean().optional().default(true).describe("Restore send volume/pan/mute for existing sends (default true)")
     },
-    async ({ name }) => {
-      const res = await sendCommand("snapshot_restore", { name });
+    async ({ name, restoreTrackMeta, restoreSendLevels }) => {
+      const res = await sendCommand("snapshot_restore", { name, restoreTrackMeta, restoreSendLevels });
       if (!res.success) {
         return { content: [{ type: "text", text: `Error: ${res.error}` }], isError: true };
       }
@@ -867,7 +871,7 @@ function registerSnapshotTools(server) {
   );
   server.tool(
     "snapshot_list",
-    "List all saved mixer snapshots with names, descriptions, and timestamps",
+    'List all saved mixer snapshots for the current project. Reads from .reaper-mcp/snapshots/ alongside the project file (falls back to global bridge dir for unsaved projects). Response includes storageLocation ("project" or "global").',
     {},
     async () => {
       const res = await sendCommand("snapshot_list", {});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mthines/reaper-mcp",
-  "version": "0.11.0",
+  "version": "0.12.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

@@ -831,9 +831,22 @@ end
 -- =============================================================================
 
 local function get_snapshot_dir()
+  local proj_path = reaper.GetProjectPath()
+  if proj_path and proj_path ~= "" then
+    return proj_path .. "/.reaper-mcp/snapshots/"
+  end
+  -- Fallback for unsaved projects
   return bridge_dir .. "snapshots/"
 end
 
+local function get_snapshot_storage_location()
+  local proj_path = reaper.GetProjectPath()
+  if proj_path and proj_path ~= "" then
+    return "project"
+  end
+  return "global"
+end
+
 local function ensure_snapshot_dir()
   reaper.RecursiveCreateDirectory(get_snapshot_dir(), 0)
 end
@@ -844,9 +857,13 @@ local function snapshot_path(name)
   return get_snapshot_dir() .. safe .. ".json"
 end
 
-local function capture_mixer_state()
-  local state = { tracks = {} }
+local function capture_mixer_state(params)
+  params = params or {}
+  local include_fx_params = params.includeFxParams ~= false  -- default true
+  local max_params = params.maxParamsPerFx or 500
+  local state = { version = 2, tracks = {} }
   local count = reaper.CountTracks(0)
+
   for i = 0, count - 1 do
     local track = reaper.GetTrack(0, i)
     local _, name = reaper.GetTrackName(track)
@@ -854,22 +871,75 @@ local function capture_mixer_state()
     local pan = reaper.GetMediaTrackInfo_Value(track, "D_PAN")
     local mute = reaper.GetMediaTrackInfo_Value(track, "B_MUTE")
     local solo = reaper.GetMediaTrackInfo_Value(track, "I_SOLO")
+    local color = reaper.GetMediaTrackInfo_Value(track, "I_CUSTOMCOLOR")
 
-    -- Capture FX bypass states
+    -- FX state with full parameter capture
     local fx_count = reaper.TrackFX_GetCount(track)
     local fx_states = {}
     for j = 0, fx_count - 1 do
-      fx_states[#fx_states + 1] = reaper.TrackFX_GetEnabled(track, j)
+      local enabled = reaper.TrackFX_GetEnabled(track, j)
+      local offline = reaper.TrackFX_GetOffline(track, j)
+      local _, preset = reaper.TrackFX_GetPreset(track, j)
+      local _, fx_name = reaper.TrackFX_GetFXName(track, j)
+
+      local params_data = {}
+      if include_fx_params then
+        local param_count = reaper.TrackFX_GetNumParams(track, j)
+        local limit = math.min(param_count, max_params)
+        for p = 0, limit - 1 do
+          local val = reaper.TrackFX_GetParam(track, j, p)
+          params_data[p + 1] = val
+        end
+      end
+
+      fx_states[j + 1] = {
+        name = fx_name,
+        enabled = enabled,
+        offline = offline,
+        preset = preset or "",
+        params = params_data,
+      }
     end
 
-    state.tracks[#state.tracks + 1] = {
+    -- Send levels (volume, pan, mute for existing sends)
+    local send_count = reaper.GetTrackNumSends(track, 0)
+    local sends = {}
+    for s = 0, send_count - 1 do
+      local dest_track = reaper.GetTrackSendInfo_Value(track, 0, s, "P_DESTTRACK")
+      local dest_idx = -1
+      local dest_name = ""
+      if dest_track then
+        dest_idx = reaper.GetMediaTrackInfo_Value(dest_track, "IP_TRACKNUMBER") - 1
+        local _, dname = reaper.GetTrackName(dest_track)
+        dest_name = dname or ""
+      end
+      sends[s + 1] = {
+        destTrackIndex = dest_idx,
+        destTrackName = dest_name,
+        volume = reaper.GetTrackSendInfo_Value(track, 0, s, "D_VOL"),
+        pan = reaper.GetTrackSendInfo_Value(track, 0, s, "D_PAN"),
+        muted = reaper.GetTrackSendInfo_Value(track, 0, s, "B_MUTE") ~= 0,
+      }
+    end
+
+    state.tracks[i + 1] = {
       index = i,
       name = name,
+      color = color,
       volume = vol,
       pan = pan,
       mute = mute ~= 0,
       solo = solo ~= 0,
-      fxEnabled = fx_states,
+      fx = fx_states,
+      sends = sends,
+      -- Legacy compat: flat fxEnabled array (derived from fx_states)
+      fxEnabled = (function()
+        local arr = {}
+        for j = 1, #fx_states do
+          arr[j] = fx_states[j].enabled
+        end
+        return arr
+      end)(),
     }
   end
   return state
@@ -888,7 +958,10 @@ function handlers.snapshot_save(params)
     name = name,
     description = params.description or "",
     timestamp = timestamp,
-    mixerState = capture_mixer_state(),
+    mixerState = capture_mixer_state({
+      includeFxParams = params.includeFxParams ~= false,
+      maxParamsPerFx = params.maxParamsPerFx or 500,
+    }),
   }
 
   local path = snapshot_path(name)
@@ -897,7 +970,7 @@ function handlers.snapshot_save(params)
     return nil, "Failed to write snapshot file: " .. path
   end
 
-  return { success = true, name = name, timestamp = timestamp, path = path }
+  return { success = true, name = name, timestamp = timestamp, path = path, storageLocation = get_snapshot_storage_location() }
 end
 
 function handlers.snapshot_restore(params)
@@ -917,30 +990,89 @@ function handlers.snapshot_restore(params)
     return nil, "Invalid snapshot file for: " .. name
   end
 
-  -- Restore each track state
-  local restored = 0
   local state = snapshot.mixerState
+  local version = state.version or 1
+  local restore_meta = params.restoreTrackMeta == true  -- default false
+  local restore_sends = params.restoreSendLevels ~= false  -- default true
+  local warnings = {}
 
   reaper.Undo_BeginBlock()
 
+  local restored = 0
+
   if state.tracks then
     for _, track_state in ipairs(state.tracks) do
       local track = reaper.GetTrack(0, track_state.index)
       if track then
+        -- Basic mixer state (all versions)
         reaper.SetMediaTrackInfo_Value(track, "D_VOL", track_state.volume)
         reaper.SetMediaTrackInfo_Value(track, "D_PAN", track_state.pan)
         reaper.SetMediaTrackInfo_Value(track, "B_MUTE", track_state.mute and 1 or 0)
         reaper.SetMediaTrackInfo_Value(track, "I_SOLO", track_state.solo and 1 or 0)
 
-        -- Restore FX bypass states
-        if track_state.fxEnabled then
+        -- Track metadata (v2, opt-in)
+        if restore_meta and version >= 2 then
+          if track_state.name then
+            reaper.GetSetMediaTrackInfo_String(track, "P_NAME", track_state.name, true)
+          end
+          if track_state.color and track_state.color ~= 0 then
+            reaper.SetMediaTrackInfo_Value(track, "I_CUSTOMCOLOR", track_state.color)
+          end
+        end
+
+        -- FX state (v2: full params; v1: bypass only)
+        if version >= 2 and track_state.fx then
+          for j, fx_state in ipairs(track_state.fx) do
+            local fx_idx = j - 1
+            if fx_idx < reaper.TrackFX_GetCount(track) then
+              -- Restore enabled/offline state
+              reaper.TrackFX_SetEnabled(track, fx_idx, fx_state.enabled)
+              if fx_state.offline ~= nil then
+                reaper.TrackFX_SetOffline(track, fx_idx, fx_state.offline)
+              end
+
+              -- Restore FX parameters only if plugin name matches
+              if fx_state.params and #fx_state.params > 0 then
+                local _, current_name = reaper.TrackFX_GetFXName(track, fx_idx)
+                if current_name == fx_state.name then
+                  for p, val in ipairs(fx_state.params) do
+                    reaper.TrackFX_SetParam(track, fx_idx, p - 1, val)
+                  end
+                else
+                  warnings[#warnings + 1] = "Track " .. track_state.index .. " FX " .. fx_idx .. ": name mismatch ('" .. (current_name or "?") .. "' vs '" .. (fx_state.name or "?") .. "'), skipped params"
+                end
+              end
+            end
+          end
+        elseif track_state.fxEnabled then
+          -- Legacy v1: bypass state only
           for j, enabled in ipairs(track_state.fxEnabled) do
-            local fx_idx = j - 1  -- convert to 0-based
+            local fx_idx = j - 1
             if fx_idx < reaper.TrackFX_GetCount(track) then
               reaper.TrackFX_SetEnabled(track, fx_idx, enabled)
             end
           end
         end
+
+        -- Send levels (v2, default on)
+        if version >= 2 and restore_sends and track_state.sends then
+          local send_count = reaper.GetTrackNumSends(track, 0)
+          for _, saved_send in ipairs(track_state.sends) do
+            for s = 0, send_count - 1 do
+              local dest = reaper.GetTrackSendInfo_Value(track, 0, s, "P_DESTTRACK")
+              if dest then
+                local dest_idx = reaper.GetMediaTrackInfo_Value(dest, "IP_TRACKNUMBER") - 1
+                if dest_idx == saved_send.destTrackIndex then
+                  reaper.SetTrackSendInfo_Value(track, 0, s, "D_VOL", saved_send.volume)
+                  reaper.SetTrackSendInfo_Value(track, 0, s, "D_PAN", saved_send.pan)
+                  reaper.SetTrackSendInfo_Value(track, 0, s, "B_MUTE", saved_send.muted and 1 or 0)
+                  break
+                end
+              end
+            end
+          end
+        end
+
         restored = restored + 1
       end
     end
@@ -951,12 +1083,15 @@ function handlers.snapshot_restore(params)
   reaper.TrackList_AdjustWindows(false)
   reaper.UpdateArrange()
 
-  return {
+  local result = {
     success = true,
     name = name,
     timestamp = snapshot.timestamp,
     tracksRestored = restored,
+    version = version,
   }
+  if #warnings > 0 then result.warnings = warnings end
+  return result
 end
 
 function handlers.snapshot_list(params)
@@ -987,7 +1122,7 @@ function handlers.snapshot_list(params)
   -- Sort by timestamp descending (newest first)
   table.sort(snapshots, function(a, b) return a.timestamp > b.timestamp end)
 
-  return { snapshots = snapshots, total = #snapshots }
+  return { snapshots = snapshots, total = #snapshots, storageLocation = get_snapshot_storage_location() }
 end
 
 -- =============================================================================