@mthines/reaper-mcp 0.13.0 → 0.14.0

package/main.js

@@ -1875,6 +1875,270 @@ function registerEnvelopeTools(server) {
   );
 }
 
+// apps/reaper-mcp-server/src/tools/batch.ts
+import { z as z15 } from "zod/v4";
+function registerBatchTools(server) {
+  server.tool(
+    "set_multiple_track_properties",
+    "Batch set properties (volume, pan, mute, solo, recordArm, phase, input) on multiple tracks in a single call. Much more efficient than calling set_track_property repeatedly. Pass an array of track update objects, each with trackIndex and any properties to change.",
+    {
+      tracks: z15.array(z15.object({
+        trackIndex: z15.coerce.number().int().min(0).describe("0-based track index"),
+        volume: z15.coerce.number().optional().describe("Volume in dB (0 = unity gain)"),
+        pan: z15.coerce.number().min(-1).max(1).optional().describe("Pan position -1.0 (left) to 1.0 (right)"),
+        mute: z15.coerce.number().int().min(0).max(1).optional().describe("Mute state (0=unmuted, 1=muted)"),
+        solo: z15.coerce.number().int().min(0).max(1).optional().describe("Solo state (0=unsolo, 1=solo)"),
+        recordArm: z15.coerce.number().int().min(0).max(1).optional().describe("Record arm state (0=unarmed, 1=armed)"),
+        phase: z15.coerce.number().int().min(0).max(1).optional().describe("Phase inversion (0=normal, 1=inverted)"),
+        input: z15.coerce.number().int().optional().describe("REAPER input index (-1 = no input)")
+      })).describe("Array of track property updates to apply")
+    },
+    async ({ tracks }) => {
+      const res = await sendCommand("set_multiple_track_properties", { tracks });
+      if (!res.success) {
+        return { content: [{ type: "text", text: `Error: ${res.error}` }], isError: true };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+  server.tool(
+    "setup_fx_chain",
+    "Add multiple FX plugins to a track with optional initial parameter values in a single call. Returns the FX chain indices of added plugins. More efficient than calling add_fx and set_fx_parameter repeatedly.",
+    {
+      trackIndex: z15.coerce.number().int().min(0).describe("0-based track index"),
+      plugins: z15.array(z15.object({
+        fxName: z15.string().describe('FX plugin name (partial match supported, e.g. "ReaEQ", "VST: Pro-Q 3")'),
+        enabled: z15.coerce.number().int().min(0).max(1).optional().describe("Initial enabled state (1=enabled default, 0=bypassed)"),
+        parameters: z15.array(z15.object({
+          index: z15.coerce.number().int().min(0).describe("Parameter index"),
+          value: z15.coerce.number().min(0).max(1).describe("Normalized parameter value 0.0\u20131.0")
+        })).optional().describe("Initial parameter values to set after adding the plugin")
+      })).describe("Array of FX plugins to add, in order")
+    },
+    async ({ trackIndex, plugins }) => {
+      const res = await sendCommand("setup_fx_chain", { trackIndex, plugins });
+      if (!res.success) {
+        return { content: [{ type: "text", text: `Error: ${res.error}` }], isError: true };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+  server.tool(
+    "set_multiple_fx_parameters",
+    "Batch set parameters across multiple FX plugins, potentially on different tracks, in a single call. Much faster than repeated set_fx_parameter calls. Pass an array of update objects with trackIndex, fxIndex, paramIndex, and value.",
+    {
+      updates: z15.array(z15.object({
+        trackIndex: z15.coerce.number().int().min(0).describe("0-based track index"),
+        fxIndex: z15.coerce.number().int().min(0).describe("0-based FX index in the chain"),
+        paramIndex: z15.coerce.number().int().min(0).describe("0-based parameter index"),
+        value: z15.coerce.number().min(0).max(1).describe("Normalized parameter value 0.0\u20131.0")
+      })).describe("Array of FX parameter updates to apply")
+    },
+    async ({ updates }) => {
+      const res = await sendCommand("set_multiple_fx_parameters", { updates });
+      if (!res.success) {
+        return { content: [{ type: "text", text: `Error: ${res.error}` }], isError: true };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+}
+
+// apps/reaper-mcp-server/src/tools/categories.ts
+import { z as z16 } from "zod/v4";
+var TOOL_CATEGORIES = {
+  project: {
+    name: "project",
+    description: "Project-level information: name, tempo, time signature, sample rate, transport state",
+    tools: ["get_project_info"]
+  },
+  tracks: {
+    name: "tracks",
+    description: "Track management: list, inspect, and set properties (volume, pan, mute, solo, record arm, phase, input). Includes batch set for multiple tracks at once.",
+    tools: ["list_tracks", "get_track_properties", "set_track_property", "set_multiple_track_properties"]
+  },
+  fx: {
+    name: "fx",
+    description: "FX chain management: add, remove, inspect, and set parameters. Includes batch setup of an entire FX chain and batch parameter updates across multiple plugins.",
+    tools: ["add_fx", "remove_fx", "get_fx_parameters", "set_fx_parameter", "set_fx_enabled", "set_fx_offline", "setup_fx_chain", "set_multiple_fx_parameters"]
+  },
+  transport: {
+    name: "transport",
+    description: "Transport control: play, stop, record, get transport state, set cursor position",
+    tools: ["play", "stop", "record", "get_transport_state", "set_cursor_position"]
+  },
+  midi: {
+    name: "midi",
+    description: "MIDI item editing: create items, insert/edit/delete notes and CC events, batch operations, analysis. Use analyze_midi first for large items; paginate with get_midi_notes offset/limit.",
+    tools: [
+      "create_midi_item",
+      "list_midi_items",
+      "get_midi_notes",
+      "analyze_midi",
+      "insert_midi_note",
+      "insert_midi_notes",
+      "edit_midi_note",
+      "edit_midi_notes",
+      "delete_midi_note",
+      "get_midi_cc",
+      "insert_midi_cc",
+      "delete_midi_cc",
+      "get_midi_item_properties",
+      "set_midi_item_properties"
+    ]
+  },
+  media: {
+    name: "media",
+    description: "Media item editing: list, inspect, set properties, split, delete, move, trim, stretch markers. Includes batch set for multiple items at once.",
+    tools: [
+      "list_media_items",
+      "get_media_item_properties",
+      "set_media_item_properties",
+      "set_media_items_properties",
+      "split_media_item",
+      "delete_media_item",
+      "move_media_item",
+      "trim_media_item",
+      "add_stretch_marker",
+      "get_stretch_markers",
+      "delete_stretch_marker"
+    ]
+  },
+  selection: {
+    name: "selection",
+    description: "Selection and navigation: get selected tracks, get/set time selection range",
+    tools: ["get_selected_tracks", "get_time_selection", "set_time_selection"]
+  },
+  markers: {
+    name: "markers",
+    description: "Markers and regions: list, add, delete markers and regions with optional names and colors",
+    tools: ["list_markers", "list_regions", "add_marker", "add_region", "delete_marker", "delete_region"]
+  },
+  tempo: {
+    name: "tempo",
+    description: "Tempo map: get all tempo and time signature changes with positions, BPM, and linear/step flags",
+    tools: ["get_tempo_map"]
+  },
+  envelopes: {
+    name: "envelopes",
+    description: "Automation envelopes: create, inspect, insert/delete points, clear, batch insert, set properties. Supports volume, pan, mute, width, trim volume, and FX parameter envelopes.",
+    tools: [
+      "create_track_envelope",
+      "get_track_envelopes",
+      "get_envelope_points",
+      "insert_envelope_point",
+      "insert_envelope_points",
+      "delete_envelope_point",
+      "clear_envelope",
+      "remove_envelope_points",
+      "set_envelope_properties"
+    ]
+  },
+  analysis: {
+    name: "analysis",
+    description: "Audio metering and analysis: peak/RMS meters, FFT spectrum, LUFS loudness, stereo correlation, crest factor",
+    tools: ["read_track_meters", "read_track_spectrum", "read_track_lufs", "read_track_correlation", "read_track_crest"]
+  },
+  discovery: {
+    name: "discovery",
+    description: "FX discovery and presets: list all installed plugins, fuzzy search by name, list and load presets",
+    tools: ["list_available_fx", "search_fx", "get_fx_preset_list", "set_fx_preset"]
+  },
+  snapshots: {
+    name: "snapshots",
+    description: "Mixer state snapshots: save, restore, and list named snapshots of volumes, pans, FX, and mutes",
+    tools: ["snapshot_save", "snapshot_restore", "snapshot_list"]
+  },
+  routing: {
+    name: "routing",
+    description: "Track routing: inspect sends, receives, parent/folder relationships for a track",
+    tools: ["get_track_routing"]
+  }
+};
+function registerCategoryTools(server) {
+  server.tool(
+    "list_tool_categories",
+    "List all available tool categories with descriptions and tool names. Use this to discover what tools are available without loading all 72+ tool schemas. Categories: project, tracks, fx, transport, midi, media, selection, markers, tempo, envelopes, analysis, discovery, snapshots, routing.",
+    {},
+    async () => {
+      const categories = Object.values(TOOL_CATEGORIES).map((cat) => ({
+        name: cat.name,
+        description: cat.description,
+        toolCount: cat.tools.length,
+        tools: cat.tools
+      }));
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({ categories, totalTools: categories.reduce((sum, c) => sum + c.toolCount, 0) }, null, 2)
+        }]
+      };
+    }
+  );
+  server.tool(
+    "enable_tool_category",
+    "Signal that you intend to use tools from a specific category. All tools are already registered and available \u2014 this call returns the full list of tools in the category so you know exactly which tool names to use. Use list_tool_categories first to see all available categories.",
+    {
+      category: z16.string().describe('Category name (e.g. "tracks", "fx", "midi", "media", "transport", "markers", "envelopes", "analysis", "discovery")')
+    },
+    async ({ category }) => {
+      const cat = TOOL_CATEGORIES[category];
+      if (!cat) {
+        const available = Object.keys(TOOL_CATEGORIES).join(", ");
+        return {
+          content: [{
+            type: "text",
+            text: `Error: Unknown category "${category}". Available categories: ${available}`
+          }],
+          isError: true
+        };
+      }
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            category: cat.name,
+            description: cat.description,
+            toolCount: cat.tools.length,
+            tools: cat.tools,
+            status: "ready"
+          }, null, 2)
+        }]
+      };
+    }
+  );
+  server.tool(
+    "disable_tool_category",
+    "Signal that you are done using tools from a specific category. This is a semantic hint to help manage your context budget \u2014 the tools remain registered but you can use this to indicate you no longer need them in the current workflow.",
+    {
+      category: z16.string().describe('Category name (e.g. "tracks", "fx", "midi", "media", "transport", "markers", "envelopes", "analysis", "discovery")')
+    },
+    async ({ category }) => {
+      const cat = TOOL_CATEGORIES[category];
+      if (!cat) {
+        const available = Object.keys(TOOL_CATEGORIES).join(", ");
+        return {
+          content: [{
+            type: "text",
+            text: `Error: Unknown category "${category}". Available categories: ${available}`
+          }],
+          isError: true
+        };
+      }
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            category: cat.name,
+            status: "disabled",
+            note: "Tools remain available if needed. Use enable_tool_category to re-activate."
+          }, null, 2)
+        }]
+      };
+    }
+  );
+}
+
 // apps/reaper-mcp-server/src/server.ts
 function instrumentToolHandlers(server) {
   const originalTool = server.tool.bind(server);
@@ -1932,6 +2196,8 @@ function createServer() {
   registerMarkerTools(server);
   registerTempoTools(server);
   registerEnvelopeTools(server);
+  registerBatchTools(server);
+  registerCategoryTools(server);
   return server;
 }
 
@@ -2091,7 +2357,15 @@ var MCP_TOOL_NAMES = [
   "create_track_envelope",
   "set_envelope_properties",
   "clear_envelope",
-  "remove_envelope_points"
+  "remove_envelope_points",
+  // composite batch tools
+  "set_multiple_track_properties",
+  "setup_fx_chain",
+  "set_multiple_fx_parameters",
+  // progressive discovery
+  "list_tool_categories",
+  "enable_tool_category",
+  "disable_tool_category"
 ];
 function ensureClaudeSettings(settingsPath) {
   const allowList = MCP_TOOL_NAMES.map((t) => `mcp__reaper__${t}`);

package/package.json

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

@@ -2352,6 +2352,196 @@ function handlers.set_fx_offline(params)
   return { trackIndex = params.trackIndex, fxIndex = params.fxIndex, offline = params.offline == 1 }
 end
 
+-- =============================================================================
+-- Composite batch tools
+-- =============================================================================
+
+function handlers.set_multiple_track_properties(params)
+  local tracks_input = params.tracks
+  if not tracks_input then return nil, "tracks array required" end
+
+  local tracks = nil
+  if type(tracks_input) == "string" then
+    tracks = json_decode(tracks_input)
+  elseif type(tracks_input) == "table" then
+    tracks = tracks_input
+  end
+  if not tracks then return nil, "Failed to parse tracks array" end
+
+  local updated = 0
+  local errors = {}
+
+  reaper.Undo_BeginBlock()
+
+  for _, t in ipairs(tracks) do
+    local track_idx = t.trackIndex
+    if track_idx == nil then
+      errors[#errors + 1] = "track entry missing trackIndex"
+    else
+      local track = reaper.GetTrack(0, track_idx)
+      if not track then
+        errors[#errors + 1] = "Track " .. track_idx .. " not found"
+      else
+        if t.volume ~= nil then
+          reaper.SetMediaTrackInfo_Value(track, "D_VOL", from_db(t.volume))
+        end
+        if t.pan ~= nil then
+          reaper.SetMediaTrackInfo_Value(track, "D_PAN", t.pan)
+        end
+        if t.mute ~= nil then
+          reaper.SetMediaTrackInfo_Value(track, "B_MUTE", t.mute)
+        end
+        if t.solo ~= nil then
+          reaper.SetMediaTrackInfo_Value(track, "I_SOLO", t.solo)
+        end
+        if t.recordArm ~= nil then
+          reaper.SetMediaTrackInfo_Value(track, "I_RECARM", t.recordArm)
+        end
+        if t.phase ~= nil then
+          reaper.SetMediaTrackInfo_Value(track, "B_PHASE", t.phase)
+        end
+        if t.input ~= nil then
+          reaper.SetMediaTrackInfo_Value(track, "I_RECINPUT", t.input)
+        end
+        updated = updated + 1
+      end
+    end
+  end
+
+  reaper.Undo_EndBlock("MCP: Batch set " .. updated .. " track properties", -1)
+
+  local result = { success = true, updated = updated, total = #tracks }
+  if #errors > 0 then result.errors = errors end
+  return result
+end
+
+function handlers.setup_fx_chain(params)
+  local track_idx = params.trackIndex
+  if track_idx == nil then return nil, "trackIndex required" end
+
+  local plugins_input = params.plugins
+  if not plugins_input then return nil, "plugins array required" end
+
+  local plugins = nil
+  if type(plugins_input) == "string" then
+    plugins = json_decode(plugins_input)
+  elseif type(plugins_input) == "table" then
+    plugins = plugins_input
+  end
+  if not plugins then return nil, "Failed to parse plugins array" end
+
+  local track = reaper.GetTrack(0, track_idx)
+  if not track then return nil, "Track " .. track_idx .. " not found" end
+
+  local added = 0
+  local errors = {}
+  local added_plugins = {}
+
+  reaper.Undo_BeginBlock()
+
+  for i, plugin in ipairs(plugins) do
+    local fx_name = plugin.fxName
+    if not fx_name or fx_name == "" then
+      errors[#errors + 1] = "plugin[" .. (i - 1) .. "] missing fxName"
+    else
+      local fx_idx = reaper.TrackFX_AddByName(track, fx_name, false, -1)
+      if fx_idx < 0 then
+        errors[#errors + 1] = "FX not found: " .. fx_name
+      else
+        -- Set enabled state if specified (default is enabled)
+        if plugin.enabled ~= nil then
+          reaper.TrackFX_SetEnabled(track, fx_idx, plugin.enabled == 1)
+        end
+
+        -- Set initial parameters if provided
+        local param_errors = {}
+        if plugin.parameters and type(plugin.parameters) == "table" then
+          for _, p in ipairs(plugin.parameters) do
+            if p.index ~= nil and p.value ~= nil then
+              local ok = reaper.TrackFX_SetParam(track, fx_idx, p.index, p.value)
+              if not ok then
+                param_errors[#param_errors + 1] = "Failed to set param " .. p.index
+              end
+            end
+          end
+        end
+
+        local _, actual_name = reaper.TrackFX_GetFXName(track, fx_idx)
+        added_plugins[#added_plugins + 1] = {
+          pluginIndex = i - 1,
+          fxName = actual_name or fx_name,
+          fxIndex = fx_idx,
+        }
+        if #param_errors > 0 then
+          for _, pe in ipairs(param_errors) do
+            errors[#errors + 1] = fx_name .. ": " .. pe
+          end
+        end
+        added = added + 1
+      end
+    end
+  end
+
+  reaper.Undo_EndBlock("MCP: Setup FX chain (" .. added .. " plugins) on track " .. track_idx, -1)
+
+  local result = {
+    success = true,
+    trackIndex = track_idx,
+    added = added,
+    total = #plugins,
+    plugins = added_plugins,
+  }
+  if #errors > 0 then result.errors = errors end
+  return result
+end
+
+function handlers.set_multiple_fx_parameters(params)
+  local updates_input = params.updates
+  if not updates_input then return nil, "updates array required" end
+
+  local updates = nil
+  if type(updates_input) == "string" then
+    updates = json_decode(updates_input)
+  elseif type(updates_input) == "table" then
+    updates = updates_input
+  end
+  if not updates then return nil, "Failed to parse updates array" end
+
+  local updated = 0
+  local errors = {}
+
+  reaper.Undo_BeginBlock()
+
+  for _, u in ipairs(updates) do
+    local track_idx = u.trackIndex
+    local fx_idx = u.fxIndex
+    local param_idx = u.paramIndex
+    local value = u.value
+
+    if track_idx == nil or fx_idx == nil or param_idx == nil or value == nil then
+      errors[#errors + 1] = "update entry missing trackIndex, fxIndex, paramIndex, or value"
+    else
+      local track = reaper.GetTrack(0, track_idx)
+      if not track then
+        errors[#errors + 1] = "Track " .. track_idx .. " not found"
+      else
+        local ok = reaper.TrackFX_SetParam(track, fx_idx, param_idx, value)
+        if not ok then
+          errors[#errors + 1] = "Failed to set track " .. track_idx .. " fx " .. fx_idx .. " param " .. param_idx
+        else
+          updated = updated + 1
+        end
+      end
+    end
+  end
+
+  reaper.Undo_EndBlock("MCP: Batch set " .. updated .. " FX parameters", -1)
+
+  local result = { success = true, updated = updated, total = #updates }
+  if #errors > 0 then result.errors = errors end
+  return result
+end
+
 -- =============================================================================
 -- Selection & Navigation
 -- =============================================================================