@mthines/reaper-mcp 0.10.0 → 0.12.0

package/main.js

@@ -131,6 +131,91 @@ function getTimeoutCounter() {
   }
   return _timeoutCounter;
 }
+var _handlerDurationHistogram = null;
+var _pickupDurationHistogram = null;
+function getHandlerDurationHistogram() {
+  if (!_handlerDurationHistogram) {
+    _handlerDurationHistogram = getMeter().createHistogram(
+      "mcp.bridge.handler.duration",
+      {
+        description: "Time Lua spent executing the command handler inside REAPER",
+        unit: "ms",
+        advice: {
+          explicitBucketBoundaries: [
+            0.1,
+            0.25,
+            0.5,
+            1,
+            2,
+            5,
+            10,
+            25,
+            50,
+            100,
+            250,
+            500
+          ]
+        }
+      }
+    );
+  }
+  return _handlerDurationHistogram;
+}
+function getPickupDurationHistogram() {
+  if (!_pickupDurationHistogram) {
+    _pickupDurationHistogram = getMeter().createHistogram(
+      "mcp.bridge.pickup.duration",
+      {
+        description: "Time from Node writing the command file to Lua picking it up (defer cycle latency)",
+        unit: "ms",
+        advice: {
+          explicitBucketBoundaries: [
+            1,
+            2,
+            5,
+            10,
+            16,
+            33,
+            50,
+            100,
+            200,
+            500,
+            1e3
+          ]
+        }
+      }
+    );
+  }
+  return _pickupDurationHistogram;
+}
+var _deferP50Ms = 0;
+var _deferP95Ms = 0;
+var _scanAvgMs = 0;
+var _scanMaxMs = 0;
+function updateDeferStats(p50, p95) {
+  _deferP50Ms = p50;
+  _deferP95Ms = p95;
+}
+function updateScanStats(avg, max) {
+  _scanAvgMs = avg;
+  _scanMaxMs = max;
+}
+function registerBridgeGauges() {
+  getMeter().createObservableGauge("mcp.bridge.defer.interval", {
+    description: "REAPER defer loop interval (p50/p95 over last 100 cycles)",
+    unit: "ms"
+  }).addCallback((obs) => {
+    obs.observe(_deferP50Ms, { percentile: "p50" });
+    obs.observe(_deferP95Ms, { percentile: "p95" });
+  });
+  getMeter().createObservableGauge("mcp.bridge.scan.duration", {
+    description: "Time Lua spends per main_loop scan cycle (avg/max over last 100 scans)",
+    unit: "ms"
+  }).addCallback((obs) => {
+    obs.observe(_scanAvgMs, { percentile: "avg" });
+    obs.observe(_scanMaxMs, { percentile: "max" });
+  });
+}
 
 // apps/reaper-mcp-server/src/bridge.ts
 import { randomUUID } from "node:crypto";
@@ -224,9 +309,29 @@ async function sendCommand(type, params = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
           const tCleanup = now();
           await Promise.allSettled([unlink(commandPath), unlink(responsePath)]);
           if (profiling) t["cleanup"] = now() - tCleanup;
+          const rawResponse = response;
+          const handlerMs = rawResponse["_handlerMs"];
+          const pickupMs = rawResponse["_pickupMs"];
+          const deferCycle = rawResponse["_deferCycle"];
           const durationMs2 = Date.now() - startMs;
           const succeeded = response.success;
           span.setAttribute("mcp.response.success", succeeded);
+          if (handlerMs != null) {
+            span.setAttribute("mcp.bridge.handler_ms", handlerMs);
+            getHandlerDurationHistogram().record(handlerMs, {
+              command_type: type,
+              success: String(succeeded)
+            });
+          }
+          if (pickupMs != null) {
+            span.setAttribute("mcp.bridge.pickup_ms", pickupMs);
+            getPickupDurationHistogram().record(pickupMs, {
+              command_type: type
+            });
+          }
+          if (deferCycle != null) {
+            span.setAttribute("mcp.bridge.defer_cycle", deferCycle);
+          }
           if (!succeeded) {
             span.setStatus({ code: SpanStatusCode.ERROR, message: response.error ?? "Bridge error" });
             span.setAttribute("mcp.response.error", response.error ?? "unknown");
@@ -333,6 +438,69 @@ function getReaperEffectsPath() {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+async function readBridgeEvents() {
+  const eventsPath = join2(getBridgeDir(), "bridge_events.jsonl");
+  let content;
+  try {
+    content = await readFile(eventsPath, "utf-8");
+  } catch {
+    return;
+  }
+  await writeFile(eventsPath, "", "utf-8").catch(() => {
+  });
+  const lines = content.split("\n").filter((l) => l.trim() !== "");
+  for (const line of lines) {
+    try {
+      const evt = JSON.parse(line);
+      console.error(JSON.stringify({ msg: "bridge_event", ...evt }));
+    } catch {
+    }
+  }
+}
+var _diagnosticsTimer = null;
+var _eventsTimer = null;
+function startDiagnosticsPoller(intervalMs = 6e4) {
+  if (_diagnosticsTimer) return;
+  _diagnosticsTimer = setInterval(async () => {
+    try {
+      const res = await sendCommand(
+        "_bridge_diagnostics",
+        {},
+        5e3
+      );
+      if (res.success && res.data) {
+        const d = res.data;
+        if (d.deferIntervals) {
+          updateDeferStats(d.deferIntervals.p50Ms, d.deferIntervals.p95Ms);
+        }
+        if (d.scanDurations) {
+          updateScanStats(d.scanDurations.avgMs, d.scanDurations.maxMs);
+        }
+      }
+    } catch {
+    }
+  }, intervalMs);
+}
+function startEventsPoller(intervalMs = 3e4) {
+  if (_eventsTimer) return;
+  readBridgeEvents().catch(() => {
+  });
+  _eventsTimer = setInterval(
+    () => readBridgeEvents().catch(() => {
+    }),
+    intervalMs
+  );
+}
+function stopPollers() {
+  if (_diagnosticsTimer) {
+    clearInterval(_diagnosticsTimer);
+    _diagnosticsTimer = null;
+  }
+  if (_eventsTimer) {
+    clearInterval(_eventsTimer);
+    _eventsTimer = null;
+  }
+}
 
 // apps/reaper-mcp-server/src/tools/project.ts
 function registerProjectTools(server) {
@@ -670,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 };
       }
@@ -685,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 };
       }
@@ -699,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", {});
@@ -2086,6 +2258,9 @@ async function doctor() {
 async function serve() {
   const log = (...args) => console.error("[reaper-mcp]", ...args);
   await initTelemetry();
+  registerBridgeGauges();
+  startDiagnosticsPoller();
+  startEventsPoller();
   log("Starting REAPER MCP Server...");
   log(`Entry: ${fileURLToPath2(import.meta.url)}`);
   const tracer = getTracer();
@@ -2195,18 +2370,22 @@ Tip: install globally for shorter commands:
 }
 process.on("SIGINT", () => {
   console.error("[reaper-mcp] Interrupted");
+  stopPollers();
   shutdownTelemetry().finally(() => process.exit(0));
 });
 process.on("SIGTERM", () => {
   console.error("[reaper-mcp] Terminated");
+  stopPollers();
   shutdownTelemetry().finally(() => process.exit(0));
 });
 process.on("uncaughtException", (err) => {
   console.error("[reaper-mcp] Uncaught exception:", err);
+  stopPollers();
   shutdownTelemetry().finally(() => process.exit(1));
 });
 process.on("unhandledRejection", (reason) => {
   console.error("[reaper-mcp] Unhandled rejection:", reason);
+  stopPollers();
   shutdownTelemetry().finally(() => process.exit(1));
 });
 //# sourceMappingURL=main.js.map

package/package.json

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

@@ -231,6 +231,22 @@ local function write_file(path, content)
   return true
 end
 
+-- =============================================================================
+-- Telemetry event logging
+-- =============================================================================
+
+local EVENTS_LOG = bridge_dir .. "bridge_events.jsonl"
+
+local function log_event(event_type, payload)
+  local f = io.open(EVENTS_LOG, "a")
+  if not f then return end
+  payload = payload or {}
+  payload.ts = os.time() * 1000
+  payload.type = event_type
+  f:write(json_encode(payload) .. "\n")
+  f:close()
+end
+
 local function file_exists(path)
   local f = io.open(path, "r")
   if f then f:close() return true end
@@ -815,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
@@ -828,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)
@@ -838,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
+
+    -- 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[#state.tracks + 1] = {
+    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
@@ -872,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)
@@ -881,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)
@@ -901,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
@@ -935,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)
@@ -971,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
 
 -- =============================================================================
@@ -2788,12 +2939,18 @@ local function process_command(filename)
   -- Dispatch to handler
   local handler = handlers[cmd.type]
   local response = {}
+  local handler_ms = 0
 
   if handler then
+    local handler_start = reaper.time_precise()
     local ok, data_or_err, err_msg = pcall(handler, cmd.params or {})
+    handler_ms = (reaper.time_precise() - handler_start) * 1000
+
     if not ok then
       -- pcall caught a Lua runtime error — handler crashed
-      response = { id = cmd.id, success = false, error = "Handler error: " .. tostring(data_or_err), timestamp = os.time() * 1000 }
+      local err_str = tostring(data_or_err)
+      log_event("handler_error", { commandType = cmd.type, commandId = cmd.id, error = err_str })
+      response = { id = cmd.id, success = false, error = "Handler error: " .. err_str, timestamp = os.time() * 1000 }
     elseif err_msg then
       -- Handler returned (nil, errorString)
       response = { id = cmd.id, success = false, error = err_msg, timestamp = os.time() * 1000 }
@@ -2802,6 +2959,7 @@ local function process_command(filename)
       response = { id = cmd.id, success = true, data = data_or_err, timestamp = os.time() * 1000 }
     end
   else
+    log_event("handler_unknown", { commandType = cmd.type, commandId = cmd.id })
     response = {
       id = cmd.id,
       success = false,
@@ -2810,6 +2968,9 @@ local function process_command(filename)
     }
   end
 
+  -- Add handler timing to response (rounded to microsecond precision)
+  response._handlerMs = math.floor(handler_ms * 1000 + 0.5) / 1000
+
   -- Add pickup timing to response for profiling
   if cmd.timestamp then
     response._pickupMs = math.floor((pickup_time - (cmd.timestamp / 1000)) * 1000 + 0.5)
@@ -2887,5 +3048,11 @@ reaper.ShowConsoleMsg("MCP Bridge: Polling every " .. (POLL_INTERVAL * 1000) ..
 -- Write initial heartbeat
 write_heartbeat()
 
+-- Log bridge start event for OTel consumption
+log_event("bridge_start", { reaperVersion = reaper.GetAppVersion(), bridgeDir = bridge_dir })
+
+-- Register shutdown handler
+reaper.atexit(function() log_event("bridge_stop", {}) end)
+
 -- Start the loop
 main_loop()