@mthines/reaper-mcp 0.18.0 → 0.19.0-beta.20.1

package/main.js

@@ -1375,6 +1375,59 @@ function registerMidiTools(server) {
       return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     }
   );
+  server.tool(
+    "send_midi_cc",
+    "Send a MIDI CC (continuous controller) event in real-time to a track's MIDI output. Auto-inserts the MCP MIDI Emitter JSFX if not present. Common CC numbers: 1=modulation, 7=volume, 10=pan, 11=expression, 64=sustain, 74=filter cutoff.",
+    {
+      trackIndex: z10.coerce.number().min(0).describe("0-based track index"),
+      cc: z10.coerce.number().min(0).max(127).describe("CC number (0-127)"),
+      value: z10.coerce.number().min(0).max(127).describe("CC value (0-127)"),
+      channel: z10.coerce.number().min(0).max(15).optional().describe("MIDI channel 0-15 (default 0)")
+    },
+    async ({ trackIndex, cc, value, channel }) => {
+      const res = await sendCommand("send_midi_cc", { trackIndex, cc, value, channel: channel ?? 0 });
+      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(
+    "send_midi_pc",
+    "Send a MIDI program change in real-time, optionally preceded by bank select (CC0 MSB + CC32 LSB). Auto-inserts the MCP MIDI Emitter JSFX if not present.",
+    {
+      trackIndex: z10.coerce.number().min(0).describe("0-based track index"),
+      program: z10.coerce.number().min(0).max(127).describe("Program number (0-127)"),
+      channel: z10.coerce.number().min(0).max(15).optional().describe("MIDI channel 0-15 (default 0)"),
+      bankMsb: z10.coerce.number().min(0).max(127).optional().describe("Bank select MSB (CC0, 0-127) \u2014 omit if no bank select needed"),
+      bankLsb: z10.coerce.number().min(0).max(127).optional().describe("Bank select LSB (CC32, 0-127) \u2014 omit if no bank select needed")
+    },
+    async ({ trackIndex, program, channel, bankMsb, bankLsb }) => {
+      const res = await sendCommand("send_midi_pc", { trackIndex, program, channel: channel ?? 0, bankMsb, bankLsb });
+      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(
+    "send_midi_note",
+    "Send a MIDI note-on in real-time to a track's MIDI output. If durationMs is provided, a note-off is automatically scheduled after that many milliseconds. Auto-inserts the MCP MIDI Emitter JSFX if not present.",
+    {
+      trackIndex: z10.coerce.number().min(0).describe("0-based track index"),
+      pitch: z10.coerce.number().min(0).max(127).describe("MIDI note number (0-127, 60=C4/Middle C)"),
+      velocity: z10.coerce.number().min(1).max(127).describe("Note velocity (1-127)"),
+      channel: z10.coerce.number().min(0).max(15).optional().describe("MIDI channel 0-15 (default 0)"),
+      durationMs: z10.coerce.number().min(1).int().optional().describe("Note duration in milliseconds (\u22651) \u2014 if provided, schedules an automatic note-off")
+    },
+    async ({ trackIndex, pitch, velocity, channel, durationMs }) => {
+      const res = await sendCommand("send_midi_note", { trackIndex, pitch, velocity, channel: channel ?? 0, durationMs });
+      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/media.ts
@@ -2307,6 +2360,7 @@ var REAPER_ASSETS = [
   "mcp_lufs_meter.jsfx",
   "mcp_correlation_meter.jsfx",
   "mcp_crest_factor.jsfx",
+  "mcp_midi_emitter.jsfx",
   "mcp_snapshot_manager.lua",
   "mcp_snapshot_lib.lua",
   "mcp_snapshot_next.lua",
@@ -2367,6 +2421,9 @@ var MCP_TOOL_NAMES = [
   "delete_midi_cc",
   "get_midi_item_properties",
   "set_midi_item_properties",
+  "send_midi_cc",
+  "send_midi_pc",
+  "send_midi_note",
   // media
   "list_media_items",
   "get_media_item_properties",

package/package.json

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

@@ -1532,6 +1532,7 @@ end
 local MCP_LUFS_METER_FX_NAME        = "reaper-mcp/mcp_lufs_meter"
 local MCP_CORRELATION_METER_FX_NAME = "reaper-mcp/mcp_correlation_meter"
 local MCP_CREST_FACTOR_FX_NAME      = "reaper-mcp/mcp_crest_factor"
+local MCP_MIDI_EMITTER_FX_NAME      = "reaper-mcp/mcp_midi_emitter"
 local MCP_FX_PREFIX                 = "reaper%-mcp/"  -- Lua pattern for matching MCP JSFX names
 
 -- Per-track cache of MCP container FX index to avoid rescanning on every read.
@@ -3499,6 +3500,118 @@ function handlers.insert_envelope_points(params)
   }
 end
 
+-- =============================================================================
+-- Live MIDI output handlers
+-- =============================================================================
+
+-- Write a single 3-byte MIDI event to the MCPMidiEmitter gmem ring buffer.
+-- status: fully-formed status byte (caller is responsible for ORing channel)
+-- d1, d2: data bytes
+-- Caller must have called reaper.gmem_attach("MCPMidiEmitter") before the
+-- first write in a handler invocation — gmem_attach is not repeated here.
+-- Lua is single-threaded relative to JSFX block boundaries; no lock needed.
+-- IMPORTANT: slot bytes (2+slot*3) must be written BEFORE advancing write_head
+-- (gmem[0]). The JSFX reads write_head first; advancing it early exposes an
+-- incompletely-written slot to the audio thread.
+local function write_midi_to_ring(status, d1, d2)
+  local slot = math.floor(reaper.gmem_read(0)) % 16
+  reaper.gmem_write(2 + slot*3 + 0, status)
+  reaper.gmem_write(2 + slot*3 + 1, d1)
+  reaper.gmem_write(2 + slot*3 + 2, d2)
+  reaper.gmem_write(0, (slot + 1) % 16)
+end
+
+function handlers.send_midi_cc(params)
+  local idx = params.trackIndex
+  if idx == nil then return nil, "trackIndex required" end
+  if params.cc == nil then return nil, "cc required" end
+  if params.value == nil then return nil, "value required" end
+
+  local track = reaper.GetTrack(0, idx)
+  if not track then return nil, "Track " .. idx .. " not found" end
+
+  local channel = math.max(0, math.min(15, math.floor(params.channel or 0)))
+  local ok, err = ensure_jsfx_on_track(track, MCP_MIDI_EMITTER_FX_NAME)
+  if not ok then return nil, err end
+
+  reaper.gmem_attach("MCPMidiEmitter")
+  -- status byte: 0xB0 = CC, OR with channel (0-15)
+  write_midi_to_ring(0xB0 | channel, math.floor(params.cc), math.floor(params.value))
+
+  -- timestampMs uses REAPER's internal high-resolution clock (not wall-clock epoch).
+  -- Suitable for round-trip latency measurement within a session.
+  return { sent = true, timestampMs = math.floor(reaper.time_precise() * 1000) }
+end
+
+function handlers.send_midi_pc(params)
+  local idx = params.trackIndex
+  if idx == nil then return nil, "trackIndex required" end
+  if params.program == nil then return nil, "program required" end
+
+  local track = reaper.GetTrack(0, idx)
+  if not track then return nil, "Track " .. idx .. " not found" end
+
+  local channel = math.max(0, math.min(15, math.floor(params.channel or 0)))
+  local ok, err = ensure_jsfx_on_track(track, MCP_MIDI_EMITTER_FX_NAME)
+  if not ok then return nil, err end
+
+  reaper.gmem_attach("MCPMidiEmitter")
+
+  -- Bank select CC0 (MSB) — use ~= nil so that bank byte value 0 is not dropped
+  if params.bankMsb ~= nil then
+    write_midi_to_ring(0xB0 | channel, 0, math.floor(params.bankMsb))
+  end
+
+  -- Bank select CC32 (LSB) — same nil-check rationale
+  if params.bankLsb ~= nil then
+    write_midi_to_ring(0xB0 | channel, 32, math.floor(params.bankLsb))
+  end
+
+  -- Program change: data2 is always 0 per MIDI 1.0 spec
+  write_midi_to_ring(0xC0 | channel, math.floor(params.program), 0)
+
+  return { sent = true, timestampMs = math.floor(reaper.time_precise() * 1000) }
+end
+
+function handlers.send_midi_note(params)
+  local idx = params.trackIndex
+  if idx == nil then return nil, "trackIndex required" end
+  if params.pitch == nil then return nil, "pitch required" end
+  if params.velocity == nil then return nil, "velocity required" end
+
+  local track = reaper.GetTrack(0, idx)
+  if not track then return nil, "Track " .. idx .. " not found" end
+
+  local channel = math.max(0, math.min(15, math.floor(params.channel or 0)))
+  local ok, err = ensure_jsfx_on_track(track, MCP_MIDI_EMITTER_FX_NAME)
+  if not ok then return nil, err end
+
+  local pitch    = math.floor(params.pitch)
+  local velocity = math.floor(params.velocity)
+
+  reaper.gmem_attach("MCPMidiEmitter")
+  -- Write note-on event: status 0x90 = note-on, OR with channel
+  write_midi_to_ring(0x90 | channel, pitch, velocity)
+
+  -- Schedule deferred note-off if durationMs is provided
+  if params.durationMs ~= nil then
+    local deadline = reaper.time_precise() + (params.durationMs / 1000.0)
+    local function note_off_callback()
+      if reaper.time_precise() >= deadline then
+        -- Re-attach gmem: deferred callbacks run outside the handler invocation.
+        reaper.gmem_attach("MCPMidiEmitter")
+        -- Write note-off event: status 0x80 = note-off, velocity 0
+        write_midi_to_ring(0x80 | channel, pitch, 0)
+      else
+        reaper.defer(note_off_callback)
+      end
+    end
+    reaper.defer(note_off_callback)
+  end
+
+  return { sent = true, timestampMs = math.floor(reaper.time_precise() * 1000) }
+end
+
 -- =============================================================================
 -- Bridge diagnostics handler
 -- =============================================================================

package/reaper/mcp_midi_emitter.jsfx

@@ -0,0 +1,44 @@
+desc:MCP MIDI Emitter
+// Real-time MIDI event emitter for MCP bridge integration.
+// Drains a 16-slot gmem ring buffer (written by the Lua bridge) and
+// emits each event via midisend() in @block.
+//
+// gmem layout (namespace MCPMidiEmitter):
+//   gmem[0]              = write_head  (Lua advances, 0..15 wrapping)
+//   gmem[1]              = read_head   (JSFX advances, 0..15 wrapping)
+//   gmem[2 + slot*3 + 0] = status byte (e.g. 0xB0 | channel for CC)
+//   gmem[2 + slot*3 + 1] = data1 byte  (CC number, note pitch, program number)
+//   gmem[2 + slot*3 + 2] = data2 byte  (CC value, velocity, 0 for PC)
+//
+// 16 slots total. Total gmem footprint: 2 + 16*3 = 50 cells.
+//
+// Ring overflow guard: not needed. Lua is single-threaded relative to JSFX
+// block boundaries. JSFX drains per block (~3ms at 256/48kHz). At realistic
+// AI-agent call rates, the ring never fills.
+//
+// No sliders needed. Passes audio through unmodified.
+
+options:gmem=MCPMidiEmitter
+
+@init
+  read_head = 0;
+  // Initialise read_head in gmem[1] so the first @block drain is consistent.
+  // write_head (gmem[0]) starts at 0 by JSFX spec (gmem cells default to 0).
+  gmem[1] = 0;
+
+@block
+  // Drain all pending MIDI events from the ring buffer.
+  // write_head is at gmem[0], read_head is at gmem[1].
+  write_head = gmem[0];
+  read_head  = gmem[1];
+  // EEL2 loop() takes a COUNT, not a condition — use while() for a drain loop.
+  while (read_head != write_head) (
+    status = gmem[2 + read_head*3 + 0];
+    d1     = gmem[2 + read_head*3 + 1];
+    d2     = gmem[2 + read_head*3 + 2];
+    midisend(0, status, d1, d2);
+    read_head = (read_head + 1) % 16;
+    gmem[1] = read_head;
+  );
+
+// No @sample section — passes audio through unmodified.