@mthines/reaper-mcp 0.4.0 → 0.6.0-beta.3.1

package/main.js

@@ -517,6 +517,424 @@ function registerAnalysisTools(server) {
   );
 }
 
+// apps/reaper-mcp-server/src/tools/midi.ts
+import { z as z10 } from "zod/v4";
+function registerMidiTools(server) {
+  server.tool(
+    "create_midi_item",
+    "Create an empty MIDI item on a track at a given time range (seconds). Use this before inserting notes.",
+    {
+      trackIndex: z10.coerce.number().min(0).describe("0-based track index"),
+      startPosition: z10.coerce.number().min(0).describe("Start position in seconds from project start"),
+      endPosition: z10.coerce.number().min(0).describe("End position in seconds from project start")
+    },
+    async ({ trackIndex, startPosition, endPosition }) => {
+      const res = await sendCommand("create_midi_item", { trackIndex, startPosition, endPosition });
+      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(
+    "list_midi_items",
+    "List all MIDI items on a track with position, length, and note/CC counts",
+    {
+      trackIndex: z10.coerce.number().min(0).describe("0-based track index")
+    },
+    async ({ trackIndex }) => {
+      const res = await sendCommand("list_midi_items", { trackIndex });
+      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(
+    "get_midi_notes",
+    "Get all MIDI notes in a MIDI item. Returns pitch (0-127, 60=C4), velocity (0-127), position and duration in beats from item start.",
+    {
+      trackIndex: z10.coerce.number().min(0).describe("0-based track index"),
+      itemIndex: z10.coerce.number().min(0).describe("0-based item index on the track")
+    },
+    async ({ trackIndex, itemIndex }) => {
+      const res = await sendCommand("get_midi_notes", { trackIndex, itemIndex });
+      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(
+    "insert_midi_note",
+    "Insert a single MIDI note. Pitch: 0-127 (60=C4/Middle C, 48=C3, 72=C5). Velocity: 1-127 (64=medium, 100=strong, 127=max). Position/duration in beats from item start (1.0=quarter, 0.5=eighth, 0.25=sixteenth).",
+    {
+      trackIndex: z10.coerce.number().min(0).describe("0-based track index"),
+      itemIndex: z10.coerce.number().min(0).describe("0-based item index on the track"),
+      pitch: z10.coerce.number().min(0).max(127).describe("MIDI note number (60=C4/Middle C)"),
+      velocity: z10.coerce.number().min(1).max(127).describe("Note velocity (1-127)"),
+      startPosition: z10.coerce.number().min(0).describe("Start position in beats from item start"),
+      duration: z10.coerce.number().min(0).describe("Duration in beats (1.0=quarter note)"),
+      channel: z10.coerce.number().min(0).max(15).optional().describe("MIDI channel 0-15 (default 0)")
+    },
+    async ({ trackIndex, itemIndex, pitch, velocity, startPosition, duration, channel }) => {
+      const res = await sendCommand("insert_midi_note", {
+        trackIndex,
+        itemIndex,
+        pitch,
+        velocity,
+        startPosition,
+        duration,
+        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(
+    "insert_midi_notes",
+    'Batch insert multiple MIDI notes. Pass a JSON array of notes as a string. Each note: { "pitch": 60, "velocity": 100, "startPosition": 0.0, "duration": 1.0, "channel": 0 }. Positions/durations in beats from item start.',
+    {
+      trackIndex: z10.coerce.number().min(0).describe("0-based track index"),
+      itemIndex: z10.coerce.number().min(0).describe("0-based item index on the track"),
+      notes: z10.string().describe('JSON array string of notes: [{"pitch":60,"velocity":100,"startPosition":0,"duration":1,"channel":0}, ...]')
+    },
+    async ({ trackIndex, itemIndex, notes }) => {
+      const res = await sendCommand("insert_midi_notes", { trackIndex, itemIndex, notes });
+      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(
+    "edit_midi_note",
+    "Edit an existing MIDI note by index. Only provided fields are changed. Positions/durations in beats from item start.",
+    {
+      trackIndex: z10.coerce.number().min(0).describe("0-based track index"),
+      itemIndex: z10.coerce.number().min(0).describe("0-based item index on the track"),
+      noteIndex: z10.coerce.number().min(0).describe("0-based note index"),
+      pitch: z10.coerce.number().min(0).max(127).optional().describe("New pitch (0-127)"),
+      velocity: z10.coerce.number().min(1).max(127).optional().describe("New velocity (1-127)"),
+      startPosition: z10.coerce.number().min(0).optional().describe("New start position in beats from item start"),
+      duration: z10.coerce.number().min(0).optional().describe("New duration in beats"),
+      channel: z10.coerce.number().min(0).max(15).optional().describe("New MIDI channel (0-15)")
+    },
+    async ({ trackIndex, itemIndex, noteIndex, pitch, velocity, startPosition, duration, channel }) => {
+      const res = await sendCommand("edit_midi_note", {
+        trackIndex,
+        itemIndex,
+        noteIndex,
+        pitch,
+        velocity,
+        startPosition,
+        duration,
+        channel
+      });
+      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(
+    "delete_midi_note",
+    "Delete a MIDI note by index from a MIDI item",
+    {
+      trackIndex: z10.coerce.number().min(0).describe("0-based track index"),
+      itemIndex: z10.coerce.number().min(0).describe("0-based item index on the track"),
+      noteIndex: z10.coerce.number().min(0).describe("0-based note index to delete")
+    },
+    async ({ trackIndex, itemIndex, noteIndex }) => {
+      const res = await sendCommand("delete_midi_note", { trackIndex, itemIndex, noteIndex });
+      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(
+    "get_midi_cc",
+    "Get CC (continuous controller) events from a MIDI item. Optionally filter by CC number (e.g. 1=modulation, 7=volume, 10=pan, 11=expression, 64=sustain).",
+    {
+      trackIndex: z10.coerce.number().min(0).describe("0-based track index"),
+      itemIndex: z10.coerce.number().min(0).describe("0-based item index on the track"),
+      ccNumber: z10.coerce.number().min(0).max(127).optional().describe("Optional: filter by CC number (0-127)")
+    },
+    async ({ trackIndex, itemIndex, ccNumber }) => {
+      const res = await sendCommand("get_midi_cc", { trackIndex, itemIndex, ccNumber });
+      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(
+    "insert_midi_cc",
+    "Insert a CC (continuous controller) event. 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"),
+      itemIndex: z10.coerce.number().min(0).describe("0-based item index on the track"),
+      ccNumber: 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)"),
+      position: z10.coerce.number().min(0).describe("Position in beats from item start"),
+      channel: z10.coerce.number().min(0).max(15).optional().describe("MIDI channel 0-15 (default 0)")
+    },
+    async ({ trackIndex, itemIndex, ccNumber, value, position, channel }) => {
+      const res = await sendCommand("insert_midi_cc", {
+        trackIndex,
+        itemIndex,
+        ccNumber,
+        value,
+        position,
+        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(
+    "delete_midi_cc",
+    "Delete a CC event by index from a MIDI item",
+    {
+      trackIndex: z10.coerce.number().min(0).describe("0-based track index"),
+      itemIndex: z10.coerce.number().min(0).describe("0-based item index on the track"),
+      ccIndex: z10.coerce.number().min(0).describe("0-based CC event index to delete")
+    },
+    async ({ trackIndex, itemIndex, ccIndex }) => {
+      const res = await sendCommand("delete_midi_cc", { trackIndex, itemIndex, ccIndex });
+      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(
+    "get_midi_item_properties",
+    "Get detailed properties of a MIDI item including position, length, note count, CC count, mute state, and loop setting",
+    {
+      trackIndex: z10.coerce.number().min(0).describe("0-based track index"),
+      itemIndex: z10.coerce.number().min(0).describe("0-based item index on the track")
+    },
+    async ({ trackIndex, itemIndex }) => {
+      const res = await sendCommand("get_midi_item_properties", { trackIndex, itemIndex });
+      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_midi_item_properties",
+    "Set MIDI item properties: position (seconds), length (seconds), mute, loop source",
+    {
+      trackIndex: z10.coerce.number().min(0).describe("0-based track index"),
+      itemIndex: z10.coerce.number().min(0).describe("0-based item index on the track"),
+      position: z10.coerce.number().min(0).optional().describe("New position in seconds from project start"),
+      length: z10.coerce.number().min(0).optional().describe("New length in seconds"),
+      mute: z10.coerce.number().min(0).max(1).optional().describe("Mute state (0=unmuted, 1=muted)"),
+      loopSource: z10.coerce.number().min(0).max(1).optional().describe("Loop source (0=no loop, 1=loop)")
+    },
+    async ({ trackIndex, itemIndex, position, length, mute, loopSource }) => {
+      const res = await sendCommand("set_midi_item_properties", {
+        trackIndex,
+        itemIndex,
+        position,
+        length,
+        mute,
+        loopSource
+      });
+      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
+import { z as z11 } from "zod/v4";
+function registerMediaTools(server) {
+  server.tool(
+    "list_media_items",
+    "List all media items on a track with position, length, name, volume, mute state, and whether it is MIDI or audio",
+    {
+      trackIndex: z11.coerce.number().min(0).describe("0-based track index")
+    },
+    async ({ trackIndex }) => {
+      const res = await sendCommand("list_media_items", { trackIndex });
+      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(
+    "get_media_item_properties",
+    "Get detailed properties of a media item: position, length, volume, fades, play rate, take info, source file",
+    {
+      trackIndex: z11.coerce.number().min(0).describe("0-based track index"),
+      itemIndex: z11.coerce.number().min(0).describe("0-based item index on the track")
+    },
+    async ({ trackIndex, itemIndex }) => {
+      const res = await sendCommand("get_media_item_properties", { trackIndex, itemIndex });
+      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_media_item_properties",
+    "Set media item properties: position (seconds), length (seconds), volume (dB), mute, fade in/out lengths, play rate",
+    {
+      trackIndex: z11.coerce.number().min(0).describe("0-based track index"),
+      itemIndex: z11.coerce.number().min(0).describe("0-based item index on the track"),
+      position: z11.coerce.number().min(0).optional().describe("New position in seconds"),
+      length: z11.coerce.number().min(0).optional().describe("New length in seconds"),
+      volume: z11.coerce.number().optional().describe("New volume in dB (0 = unity gain)"),
+      mute: z11.coerce.number().min(0).max(1).optional().describe("Mute state (0=unmuted, 1=muted)"),
+      fadeInLength: z11.coerce.number().min(0).optional().describe("Fade-in length in seconds"),
+      fadeOutLength: z11.coerce.number().min(0).optional().describe("Fade-out length in seconds"),
+      playRate: z11.coerce.number().min(0.1).max(10).optional().describe("Playback rate (1.0=normal, 0.5=half, 2.0=double)")
+    },
+    async ({ trackIndex, itemIndex, position, length, volume, mute, fadeInLength, fadeOutLength, playRate }) => {
+      const res = await sendCommand("set_media_item_properties", {
+        trackIndex,
+        itemIndex,
+        position,
+        length,
+        volume,
+        mute,
+        fadeInLength,
+        fadeOutLength,
+        playRate
+      });
+      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(
+    "split_media_item",
+    "Split a media item at a given position (absolute project time in seconds). Returns info about both resulting items.",
+    {
+      trackIndex: z11.coerce.number().min(0).describe("0-based track index"),
+      itemIndex: z11.coerce.number().min(0).describe("0-based item index on the track"),
+      position: z11.coerce.number().min(0).describe("Split position in seconds (absolute project time)")
+    },
+    async ({ trackIndex, itemIndex, position }) => {
+      const res = await sendCommand("split_media_item", { trackIndex, itemIndex, position });
+      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(
+    "delete_media_item",
+    "Delete a media item from a track",
+    {
+      trackIndex: z11.coerce.number().min(0).describe("0-based track index"),
+      itemIndex: z11.coerce.number().min(0).describe("0-based item index on the track")
+    },
+    async ({ trackIndex, itemIndex }) => {
+      const res = await sendCommand("delete_media_item", { trackIndex, itemIndex });
+      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(
+    "move_media_item",
+    "Move a media item to a new position and/or a different track",
+    {
+      trackIndex: z11.coerce.number().min(0).describe("0-based track index (current track)"),
+      itemIndex: z11.coerce.number().min(0).describe("0-based item index on the track"),
+      newPosition: z11.coerce.number().min(0).optional().describe("New position in seconds"),
+      newTrackIndex: z11.coerce.number().min(0).optional().describe("Move to this track (0-based index)")
+    },
+    async ({ trackIndex, itemIndex, newPosition, newTrackIndex }) => {
+      const res = await sendCommand("move_media_item", { trackIndex, itemIndex, newPosition, newTrackIndex });
+      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(
+    "trim_media_item",
+    "Trim a media item edges. Positive trimStart trims from the beginning (makes item shorter/later). Positive trimEnd trims from the end (makes item shorter). Negative values extend.",
+    {
+      trackIndex: z11.coerce.number().min(0).describe("0-based track index"),
+      itemIndex: z11.coerce.number().min(0).describe("0-based item index on the track"),
+      trimStart: z11.coerce.number().optional().describe("Seconds to trim from start (positive=trim in, negative=extend)"),
+      trimEnd: z11.coerce.number().optional().describe("Seconds to trim from end (positive=trim in, negative=extend)")
+    },
+    async ({ trackIndex, itemIndex, trimStart, trimEnd }) => {
+      const res = await sendCommand("trim_media_item", { trackIndex, itemIndex, trimStart, trimEnd });
+      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(
+    "add_stretch_marker",
+    "Add a stretch marker to a media item for time-stretching audio. Position is within the item (seconds from item start). Source position is the corresponding position in the original audio.",
+    {
+      trackIndex: z11.coerce.number().min(0).describe("0-based track index"),
+      itemIndex: z11.coerce.number().min(0).describe("0-based item index on the track"),
+      position: z11.coerce.number().min(0).describe("Position within the item in seconds (from item start)"),
+      sourcePosition: z11.coerce.number().min(0).optional().describe("Position in source audio in seconds (defaults to same as position)")
+    },
+    async ({ trackIndex, itemIndex, position, sourcePosition }) => {
+      const res = await sendCommand("add_stretch_marker", { trackIndex, itemIndex, position, sourcePosition });
+      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(
+    "get_stretch_markers",
+    "List all stretch markers in a media item with their positions and source positions",
+    {
+      trackIndex: z11.coerce.number().min(0).describe("0-based track index"),
+      itemIndex: z11.coerce.number().min(0).describe("0-based item index on the track")
+    },
+    async ({ trackIndex, itemIndex }) => {
+      const res = await sendCommand("get_stretch_markers", { trackIndex, itemIndex });
+      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(
+    "delete_stretch_marker",
+    "Delete a stretch marker by index from a media item",
+    {
+      trackIndex: z11.coerce.number().min(0).describe("0-based track index"),
+      itemIndex: z11.coerce.number().min(0).describe("0-based item index on the track"),
+      markerIndex: z11.coerce.number().min(0).describe("0-based stretch marker index")
+    },
+    async ({ trackIndex, itemIndex, markerIndex }) => {
+      const res = await sendCommand("delete_stretch_marker", { trackIndex, itemIndex, markerIndex });
+      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/server.ts
 function createServer() {
   const server = new McpServer({
@@ -533,6 +951,8 @@ function createServer() {
   registerSnapshotTools(server);
   registerRoutingTools(server);
   registerAnalysisTools(server);
+  registerMidiTools(server);
+  registerMediaTools(server);
   return server;
 }
 
@@ -631,7 +1051,7 @@ async function setup() {
   console.log("  2. Actions > Show action list > Load ReaScript");
   console.log(`  3. Select: ${luaDest}`);
   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: reaper-mcp doctor)");
+  console.log("  5. Add reaper-mcp to your Claude Code config (see: npx @mthines/reaper-mcp doctor)");
 }
 async function installSkills() {
   console.log("REAPER MCP \u2014 Install AI Mix Engineer Skills\n");
@@ -691,22 +1111,22 @@ async function doctor() {
   const bridgeRunning = await isBridgeRunning();
   console.log(`Lua bridge:    ${bridgeRunning ? "\u2713 Connected" : "\u2717 Not detected"}`);
   if (!bridgeRunning) {
-    console.log('  \u2192 Run "reaper-mcp setup" then load mcp_bridge.lua in REAPER');
+    console.log('  \u2192 Run "npx @mthines/reaper-mcp setup" then load mcp_bridge.lua in REAPER');
   }
   const agentsExist = existsSync2(join3(process.cwd(), ".claude", "agents"));
   console.log(`Mix agents:    ${agentsExist ? "\u2713 Found (.claude/agents/)" : "\u2717 Not installed"}`);
   if (!agentsExist) {
-    console.log('  \u2192 Run "reaper-mcp install-skills" in your project directory');
+    console.log('  \u2192 Run "npx @mthines/reaper-mcp install-skills" in your project directory');
   }
   const knowledgeExists = existsSync2(join3(process.cwd(), "knowledge"));
   console.log(`Knowledge base: ${knowledgeExists ? "\u2713 Found in project" : "\u2717 Not installed"}`);
   if (!knowledgeExists) {
-    console.log('  \u2192 Run "reaper-mcp install-skills" in your project directory');
+    console.log('  \u2192 Run "npx @mthines/reaper-mcp install-skills" in your project directory');
   }
   const mcpJsonExists = existsSync2(join3(process.cwd(), ".mcp.json"));
   console.log(`MCP config:    ${mcpJsonExists ? "\u2713 .mcp.json found" : "\u2717 .mcp.json missing"}`);
   if (!mcpJsonExists) {
-    console.log('  \u2192 Run "reaper-mcp install-skills" to create .mcp.json');
+    console.log('  \u2192 Run "npx @mthines/reaper-mcp install-skills" 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");
@@ -725,7 +1145,7 @@ async function serve() {
   if (!bridgeRunning) {
     log("WARNING: Lua bridge does not appear to be running in REAPER.");
     log("Commands will timeout until the bridge script is started.");
-    log('Run "reaper-mcp setup" for installation instructions.');
+    log('Run "npx @mthines/reaper-mcp setup" for installation instructions.');
   } else {
     log("Lua bridge detected \u2014 connected to REAPER");
   }
@@ -773,18 +1193,22 @@ switch (command) {
     console.log(`reaper-mcp \u2014 AI-powered mixing for REAPER DAW
 
 Usage:
-  reaper-mcp                  Start MCP server (stdio mode)
-  reaper-mcp serve            Start MCP server (stdio mode)
-  reaper-mcp setup            Install Lua bridge + JSFX analyzers into REAPER
-  reaper-mcp install-skills   Install AI mix engineer knowledge into your project
-  reaper-mcp doctor           Check that everything is configured correctly
-  reaper-mcp status           Check if Lua bridge is running in REAPER
+  npx @mthines/reaper-mcp                  Start MCP server (stdio mode)
+  npx @mthines/reaper-mcp serve            Start MCP server (stdio mode)
+  npx @mthines/reaper-mcp setup            Install Lua bridge + JSFX analyzers into REAPER
+  npx @mthines/reaper-mcp install-skills   Install AI mix engineer knowledge + agents into your project
+  npx @mthines/reaper-mcp doctor           Check that everything is configured correctly
+  npx @mthines/reaper-mcp status           Check if Lua bridge is running in REAPER
 
 Quick Start:
-  1. reaper-mcp setup            # install REAPER components
+  1. npx @mthines/reaper-mcp setup            # install REAPER components
   2. Load mcp_bridge.lua in REAPER (Actions > Load ReaScript > Run)
-  3. reaper-mcp install-skills   # install AI knowledge in your project
-  4. Open Claude Code \u2014 REAPER tools + mix engineer brain are ready
+  3. npx @mthines/reaper-mcp install-skills   # install AI knowledge + agents
+  4. Open Claude Code \u2014 REAPER tools + mix engineer agents are ready
+
+Tip: install globally for shorter commands:
+  npm install -g @mthines/reaper-mcp
+  reaper-mcp setup
 `);
     break;
 }

package/package.json

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

@@ -1009,6 +1009,781 @@ function handlers.read_track_crest(params)
   }
 end
 
+-- =============================================================================
+-- MIDI editing handlers
+-- =============================================================================
+
+-- Helper: get a MIDI take from track/item indices, with validation
+local function get_midi_take(params)
+  local track_idx = params.trackIndex
+  local item_idx = params.itemIndex
+  if track_idx == nil then return nil, nil, nil, "trackIndex required" end
+  if item_idx == nil then return nil, nil, nil, "itemIndex required" end
+
+  local track = reaper.GetTrack(0, track_idx)
+  if not track then return nil, nil, nil, "Track " .. track_idx .. " not found" end
+
+  local item_count = reaper.CountTrackMediaItems(track)
+  if item_idx >= item_count then
+    return nil, nil, nil, "Item " .. item_idx .. " not found (track has " .. item_count .. " items)"
+  end
+
+  local item = reaper.GetTrackMediaItem(track, item_idx)
+  if not item then return nil, nil, nil, "Item " .. item_idx .. " not found" end
+
+  local take = reaper.GetActiveTake(item)
+  if not take then return nil, nil, nil, "Item has no active take" end
+
+  if not reaper.TakeIsMIDI(take) then
+    return nil, nil, nil, "Item is not a MIDI item"
+  end
+
+  return track, item, take, nil
+end
+
+-- Helper: get a media item from track/item indices, with validation
+local function get_media_item(params)
+  local track_idx = params.trackIndex
+  local item_idx = params.itemIndex
+  if track_idx == nil then return nil, nil, "trackIndex required" end
+  if item_idx == nil then return nil, nil, "itemIndex required" end
+
+  local track = reaper.GetTrack(0, track_idx)
+  if not track then return nil, nil, "Track " .. track_idx .. " not found" end
+
+  local item_count = reaper.CountTrackMediaItems(track)
+  if item_idx >= item_count then
+    return nil, nil, "Item " .. item_idx .. " not found (track has " .. item_count .. " items)"
+  end
+
+  local item = reaper.GetTrackMediaItem(track, item_idx)
+  if not item then return nil, nil, "Item " .. item_idx .. " not found" end
+
+  return track, item, nil
+end
+
+-- Helper: convert beats from item start to PPQ ticks
+local function beats_to_ppq(take, item, beats)
+  local item_start = reaper.GetMediaItemInfo_Value(item, "D_POSITION")
+  -- Convert beats to project time (using project tempo), then to PPQ
+  local proj_time = item_start + reaper.TimeMap2_QNToTime(0, reaper.TimeMap2_timeToQN(0, item_start) + beats) - item_start
+  return reaper.MIDI_GetPPQPosFromProjTime(take, proj_time)
+end
+
+-- Helper: convert PPQ ticks to beats from item start
+local function ppq_to_beats(take, item)
+  local item_start = reaper.GetMediaItemInfo_Value(item, "D_POSITION")
+  local item_start_qn = reaper.TimeMap2_timeToQN(0, item_start)
+  return function(ppq)
+    local proj_time = reaper.MIDI_GetProjTimeFromPPQPos(take, ppq)
+    local proj_qn = reaper.TimeMap2_timeToQN(0, proj_time)
+    return proj_qn - item_start_qn
+  end
+end
+
+function handlers.create_midi_item(params)
+  local track_idx = params.trackIndex
+  local start_pos = params.startPosition
+  local end_pos = params.endPosition
+  if track_idx == nil then return nil, "trackIndex required" end
+  if not start_pos or not end_pos then return nil, "startPosition and endPosition required" end
+  if end_pos <= start_pos then return nil, "endPosition must be greater than startPosition" end
+
+  local track = reaper.GetTrack(0, track_idx)
+  if not track then return nil, "Track " .. track_idx .. " not found" end
+
+  reaper.Undo_BeginBlock()
+  local item = reaper.CreateNewMIDIItemInProj(track, start_pos, end_pos)
+  reaper.Undo_EndBlock("MCP: Create MIDI item", -1)
+
+  if not item then return nil, "Failed to create MIDI item" end
+
+  -- Find the index of the new item on the track
+  local item_count = reaper.CountTrackMediaItems(track)
+  local new_idx = -1
+  for i = 0, item_count - 1 do
+    if reaper.GetTrackMediaItem(track, i) == item then
+      new_idx = i
+      break
+    end
+  end
+
+  reaper.UpdateArrange()
+
+  return {
+    trackIndex = track_idx,
+    itemIndex = new_idx,
+    position = start_pos,
+    length = end_pos - start_pos,
+  }
+end
+
+function handlers.list_midi_items(params)
+  local track_idx = params.trackIndex
+  if track_idx == nil then return nil, "trackIndex required" end
+
+  local track = reaper.GetTrack(0, track_idx)
+  if not track then return nil, "Track " .. track_idx .. " not found" end
+
+  local items = {}
+  local item_count = reaper.CountTrackMediaItems(track)
+  for i = 0, item_count - 1 do
+    local item = reaper.GetTrackMediaItem(track, i)
+    local take = reaper.GetActiveTake(item)
+    if take and reaper.TakeIsMIDI(take) then
+      local _, note_cnt, cc_cnt, _ = reaper.MIDI_CountEvts(take)
+      items[#items + 1] = {
+        itemIndex = i,
+        position = reaper.GetMediaItemInfo_Value(item, "D_POSITION"),
+        length = reaper.GetMediaItemInfo_Value(item, "D_LENGTH"),
+        noteCount = note_cnt,
+        ccCount = cc_cnt,
+        muted = reaper.GetMediaItemInfo_Value(item, "B_MUTE") ~= 0,
+      }
+    end
+  end
+
+  return { trackIndex = track_idx, items = items, total = #items }
+end
+
+function handlers.get_midi_notes(params)
+  local track, item, take, err = get_midi_take(params)
+  if err then return nil, err end
+
+  local _, note_cnt, _, _ = reaper.MIDI_CountEvts(take)
+  local to_beats = ppq_to_beats(take, item)
+  local notes = {}
+
+  for i = 0, note_cnt - 1 do
+    local _, sel, muted, start_ppq, end_ppq, chan, pitch, vel = reaper.MIDI_GetNote(take, i)
+    local start_beats = to_beats(start_ppq)
+    local end_beats = to_beats(end_ppq)
+    notes[#notes + 1] = {
+      noteIndex = i,
+      pitch = pitch,
+      velocity = vel,
+      startPosition = start_beats,
+      duration = end_beats - start_beats,
+      channel = chan,
+      selected = sel,
+      muted = muted,
+    }
+  end
+
+  return { trackIndex = params.trackIndex, itemIndex = params.itemIndex, notes = notes, total = #notes }
+end
+
+function handlers.insert_midi_note(params)
+  local track, item, take, err = get_midi_take(params)
+  if err then return nil, err end
+
+  local pitch = params.pitch
+  local vel = params.velocity
+  local start_pos = params.startPosition
+  local dur = params.duration
+  local chan = params.channel or 0
+
+  if not pitch or not vel or not start_pos or not dur then
+    return nil, "pitch, velocity, startPosition, and duration required"
+  end
+
+  -- Clamp values
+  pitch = math.max(0, math.min(127, math.floor(pitch)))
+  vel = math.max(1, math.min(127, math.floor(vel)))
+  chan = math.max(0, math.min(15, math.floor(chan)))
+
+  local start_ppq = beats_to_ppq(take, item, start_pos)
+  local end_ppq = beats_to_ppq(take, item, start_pos + dur)
+
+  reaper.Undo_BeginBlock()
+  reaper.MIDI_InsertNote(take, false, false, start_ppq, end_ppq, chan, pitch, vel, false)
+  reaper.MIDI_Sort(take)
+  reaper.Undo_EndBlock("MCP: Insert MIDI note", -1)
+
+  reaper.UpdateArrange()
+
+  local _, note_cnt, _, _ = reaper.MIDI_CountEvts(take)
+  return { success = true, noteCount = note_cnt }
+end
+
+function handlers.insert_midi_notes(params)
+  local track, item, take, err = get_midi_take(params)
+  if err then return nil, err end
+
+  local notes_str = params.notes
+  if not notes_str or notes_str == "" then return nil, "notes JSON string required" end
+
+  -- Parse notes JSON array
+  local notes_data = json_decode(notes_str)
+  if not notes_data then return nil, "Failed to parse notes JSON" end
+
+  -- Handle both array-style and object-style parsed data
+  local notes_list = {}
+  if notes_data[1] then
+    notes_list = notes_data
+  else
+    -- Try to extract from numbered keys (fallback parser)
+    return nil, "Notes must be a JSON array. Ensure REAPER 7+ with CF_Json_Parse for array support."
+  end
+
+  reaper.Undo_BeginBlock()
+  local inserted = 0
+  for _, note in ipairs(notes_list) do
+    local pitch = note.pitch
+    local vel = note.velocity
+    local start_pos = note.startPosition
+    local dur = note.duration
+    local chan = note.channel or 0
+
+    if pitch and vel and start_pos and dur then
+      pitch = math.max(0, math.min(127, math.floor(pitch)))
+      vel = math.max(1, math.min(127, math.floor(vel)))
+      chan = math.max(0, math.min(15, math.floor(chan)))
+
+      local start_ppq = beats_to_ppq(take, item, start_pos)
+      local end_ppq = beats_to_ppq(take, item, start_pos + dur)
+
+      reaper.MIDI_InsertNote(take, false, false, start_ppq, end_ppq, chan, pitch, vel, true)
+      inserted = inserted + 1
+    end
+  end
+  reaper.MIDI_Sort(take)
+  reaper.Undo_EndBlock("MCP: Insert " .. inserted .. " MIDI notes", -1)
+
+  reaper.UpdateArrange()
+
+  local _, note_cnt, _, _ = reaper.MIDI_CountEvts(take)
+  return { success = true, inserted = inserted, noteCount = note_cnt }
+end
+
+function handlers.edit_midi_note(params)
+  local track, item, take, err = get_midi_take(params)
+  if err then return nil, err end
+
+  local note_idx = params.noteIndex
+  if note_idx == nil then return nil, "noteIndex required" end
+
+  local _, note_cnt, _, _ = reaper.MIDI_CountEvts(take)
+  if note_idx >= note_cnt then
+    return nil, "Note index " .. note_idx .. " out of range (item has " .. note_cnt .. " notes)"
+  end
+
+  -- Get current note values
+  local _, sel, muted, cur_start_ppq, cur_end_ppq, cur_chan, cur_pitch, cur_vel = reaper.MIDI_GetNote(take, note_idx)
+
+  -- Apply changes (nil means keep current)
+  local new_pitch = params.pitch and math.max(0, math.min(127, math.floor(params.pitch))) or nil
+  local new_vel = params.velocity and math.max(1, math.min(127, math.floor(params.velocity))) or nil
+  local new_chan = params.channel and math.max(0, math.min(15, math.floor(params.channel))) or nil
+
+  local new_start_ppq = nil
+  local new_end_ppq = nil
+  if params.startPosition ~= nil then
+    new_start_ppq = beats_to_ppq(take, item, params.startPosition)
+    if params.duration ~= nil then
+      new_end_ppq = beats_to_ppq(take, item, params.startPosition + params.duration)
+    else
+      -- Keep same duration
+      local dur_ppq = cur_end_ppq - cur_start_ppq
+      new_end_ppq = new_start_ppq + dur_ppq
+    end
+  elseif params.duration ~= nil then
+    -- Change duration only, keep start
+    local to_beats = ppq_to_beats(take, item)
+    local cur_start_beats = to_beats(cur_start_ppq)
+    new_end_ppq = beats_to_ppq(take, item, cur_start_beats + params.duration)
+  end
+
+  reaper.Undo_BeginBlock()
+  reaper.MIDI_SetNote(take, note_idx, sel, muted, new_start_ppq, new_end_ppq, new_chan, new_pitch, new_vel, false)
+  reaper.MIDI_Sort(take)
+  reaper.Undo_EndBlock("MCP: Edit MIDI note " .. note_idx, -1)
+
+  reaper.UpdateArrange()
+
+  return { success = true, noteIndex = note_idx }
+end
+
+function handlers.delete_midi_note(params)
+  local track, item, take, err = get_midi_take(params)
+  if err then return nil, err end
+
+  local note_idx = params.noteIndex
+  if note_idx == nil then return nil, "noteIndex required" end
+
+  local _, note_cnt, _, _ = reaper.MIDI_CountEvts(take)
+  if note_idx >= note_cnt then
+    return nil, "Note index " .. note_idx .. " out of range (item has " .. note_cnt .. " notes)"
+  end
+
+  reaper.Undo_BeginBlock()
+  reaper.MIDI_DeleteNote(take, note_idx)
+  reaper.MIDI_Sort(take)
+  reaper.Undo_EndBlock("MCP: Delete MIDI note " .. note_idx, -1)
+
+  reaper.UpdateArrange()
+
+  local _, new_cnt, _, _ = reaper.MIDI_CountEvts(take)
+  return { success = true, noteCount = new_cnt }
+end
+
+function handlers.get_midi_cc(params)
+  local track, item, take, err = get_midi_take(params)
+  if err then return nil, err end
+
+  local _, _, cc_cnt, _ = reaper.MIDI_CountEvts(take)
+  local to_beats = ppq_to_beats(take, item)
+  local cc_filter = params.ccNumber
+  local events = {}
+
+  for i = 0, cc_cnt - 1 do
+    local _, sel, muted, ppq, chanmsg, chan, msg2, msg3 = reaper.MIDI_GetCC(take, i)
+    -- msg2 = CC number, msg3 = CC value (for standard CC messages, chanmsg=176)
+    if chanmsg == 176 then -- standard CC
+      if cc_filter == nil or msg2 == cc_filter then
+        events[#events + 1] = {
+          ccIndex = i,
+          ccNumber = msg2,
+          value = msg3,
+          position = to_beats(ppq),
+          channel = chan,
+        }
+      end
+    end
+  end
+
+  return { trackIndex = params.trackIndex, itemIndex = params.itemIndex, events = events, total = #events }
+end
+
+function handlers.insert_midi_cc(params)
+  local track, item, take, err = get_midi_take(params)
+  if err then return nil, err end
+
+  local cc_num = params.ccNumber
+  local value = params.value
+  local pos = params.position
+  local chan = params.channel or 0
+
+  if not cc_num or not value or not pos then
+    return nil, "ccNumber, value, and position required"
+  end
+
+  cc_num = math.max(0, math.min(127, math.floor(cc_num)))
+  value = math.max(0, math.min(127, math.floor(value)))
+  chan = math.max(0, math.min(15, math.floor(chan)))
+
+  local ppq = beats_to_ppq(take, item, pos)
+
+  reaper.Undo_BeginBlock()
+  -- chanmsg 176 = 0xB0 = CC message
+  reaper.MIDI_InsertCC(take, false, false, ppq, 176, chan, cc_num, value)
+  reaper.MIDI_Sort(take)
+  reaper.Undo_EndBlock("MCP: Insert MIDI CC " .. cc_num, -1)
+
+  reaper.UpdateArrange()
+
+  local _, _, cc_cnt, _ = reaper.MIDI_CountEvts(take)
+  return { success = true, ccCount = cc_cnt }
+end
+
+function handlers.delete_midi_cc(params)
+  local track, item, take, err = get_midi_take(params)
+  if err then return nil, err end
+
+  local cc_idx = params.ccIndex
+  if cc_idx == nil then return nil, "ccIndex required" end
+
+  local _, _, cc_cnt, _ = reaper.MIDI_CountEvts(take)
+  if cc_idx >= cc_cnt then
+    return nil, "CC index " .. cc_idx .. " out of range (item has " .. cc_cnt .. " CC events)"
+  end
+
+  reaper.Undo_BeginBlock()
+  reaper.MIDI_DeleteCC(take, cc_idx)
+  reaper.MIDI_Sort(take)
+  reaper.Undo_EndBlock("MCP: Delete MIDI CC " .. cc_idx, -1)
+
+  reaper.UpdateArrange()
+
+  local _, _, new_cnt, _ = reaper.MIDI_CountEvts(take)
+  return { success = true, ccCount = new_cnt }
+end
+
+function handlers.get_midi_item_properties(params)
+  local track, item, take, err = get_midi_take(params)
+  if err then return nil, err end
+
+  local _, note_cnt, cc_cnt, _ = reaper.MIDI_CountEvts(take)
+
+  return {
+    trackIndex = params.trackIndex,
+    itemIndex = params.itemIndex,
+    position = reaper.GetMediaItemInfo_Value(item, "D_POSITION"),
+    length = reaper.GetMediaItemInfo_Value(item, "D_LENGTH"),
+    noteCount = note_cnt,
+    ccCount = cc_cnt,
+    muted = reaper.GetMediaItemInfo_Value(item, "B_MUTE") ~= 0,
+    loopSource = reaper.GetMediaItemInfo_Value(item, "B_LOOPSRC") ~= 0,
+  }
+end
+
+function handlers.set_midi_item_properties(params)
+  local track, item, take, err = get_midi_take(params)
+  if err then return nil, err end
+
+  reaper.Undo_BeginBlock()
+
+  if params.position ~= nil then
+    reaper.SetMediaItemInfo_Value(item, "D_POSITION", params.position)
+  end
+  if params.length ~= nil then
+    reaper.SetMediaItemInfo_Value(item, "D_LENGTH", params.length)
+  end
+  if params.mute ~= nil then
+    reaper.SetMediaItemInfo_Value(item, "B_MUTE", params.mute)
+  end
+  if params.loopSource ~= nil then
+    reaper.SetMediaItemInfo_Value(item, "B_LOOPSRC", params.loopSource)
+  end
+
+  reaper.Undo_EndBlock("MCP: Set MIDI item properties", -1)
+  reaper.UpdateArrange()
+
+  return { success = true, trackIndex = params.trackIndex, itemIndex = params.itemIndex }
+end
+
+-- =============================================================================
+-- Media item editing handlers
+-- =============================================================================
+
+function handlers.list_media_items(params)
+  local track_idx = params.trackIndex
+  if track_idx == nil then return nil, "trackIndex required" end
+
+  local track = reaper.GetTrack(0, track_idx)
+  if not track then return nil, "Track " .. track_idx .. " not found" end
+
+  local items = {}
+  local item_count = reaper.CountTrackMediaItems(track)
+  for i = 0, item_count - 1 do
+    local item = reaper.GetTrackMediaItem(track, i)
+    local take = reaper.GetActiveTake(item)
+    local take_name = ""
+    local is_midi = false
+    if take then
+      take_name = reaper.GetTakeName(take) or ""
+      is_midi = reaper.TakeIsMIDI(take)
+    end
+
+    local vol_raw = reaper.GetMediaItemInfo_Value(item, "D_VOL")
+    items[#items + 1] = {
+      itemIndex = i,
+      position = reaper.GetMediaItemInfo_Value(item, "D_POSITION"),
+      length = reaper.GetMediaItemInfo_Value(item, "D_LENGTH"),
+      name = take_name,
+      volume = to_db(vol_raw),
+      muted = reaper.GetMediaItemInfo_Value(item, "B_MUTE") ~= 0,
+      fadeInLength = reaper.GetMediaItemInfo_Value(item, "D_FADEINLEN"),
+      fadeOutLength = reaper.GetMediaItemInfo_Value(item, "D_FADEOUTLEN"),
+      playRate = take and reaper.GetMediaItemTakeInfo_Value(take, "D_PLAYRATE") or 1.0,
+      isMidi = is_midi,
+      takeName = take_name,
+    }
+  end
+
+  return { trackIndex = track_idx, items = items, total = #items }
+end
+
+function handlers.get_media_item_properties(params)
+  local track, item, err = get_media_item(params)
+  if err then return nil, err end
+
+  local take = reaper.GetActiveTake(item)
+  local take_name = ""
+  local is_midi = false
+  local play_rate = 1.0
+  local pitch = 0.0
+  local start_offset = 0.0
+  local source_file = ""
+
+  if take then
+    take_name = reaper.GetTakeName(take) or ""
+    is_midi = reaper.TakeIsMIDI(take)
+    play_rate = reaper.GetMediaItemTakeInfo_Value(take, "D_PLAYRATE")
+    pitch = reaper.GetMediaItemTakeInfo_Value(take, "D_PITCH")
+    start_offset = reaper.GetMediaItemTakeInfo_Value(take, "D_STARTOFFS")
+    local source = reaper.GetMediaItemTake_Source(take)
+    if source then
+      source_file = reaper.GetMediaSourceFileName(source) or ""
+    end
+  end
+
+  local vol_raw = reaper.GetMediaItemInfo_Value(item, "D_VOL")
+
+  return {
+    trackIndex = params.trackIndex,
+    itemIndex = params.itemIndex,
+    position = reaper.GetMediaItemInfo_Value(item, "D_POSITION"),
+    length = reaper.GetMediaItemInfo_Value(item, "D_LENGTH"),
+    name = take_name,
+    volume = to_db(vol_raw),
+    volumeRaw = vol_raw,
+    muted = reaper.GetMediaItemInfo_Value(item, "B_MUTE") ~= 0,
+    fadeInLength = reaper.GetMediaItemInfo_Value(item, "D_FADEINLEN"),
+    fadeOutLength = reaper.GetMediaItemInfo_Value(item, "D_FADEOUTLEN"),
+    fadeInShape = reaper.GetMediaItemInfo_Value(item, "C_FADEINSHAPE"),
+    fadeOutShape = reaper.GetMediaItemInfo_Value(item, "C_FADEOUTSHAPE"),
+    playRate = play_rate,
+    pitch = pitch,
+    startOffset = start_offset,
+    loopSource = reaper.GetMediaItemInfo_Value(item, "B_LOOPSRC") ~= 0,
+    isMidi = is_midi,
+    takeName = take_name,
+    sourceFile = source_file,
+    locked = reaper.GetMediaItemInfo_Value(item, "C_LOCK") ~= 0,
+  }
+end
+
+function handlers.set_media_item_properties(params)
+  local track, item, err = get_media_item(params)
+  if err then return nil, err end
+
+  reaper.Undo_BeginBlock()
+
+  if params.position ~= nil then
+    reaper.SetMediaItemInfo_Value(item, "D_POSITION", params.position)
+  end
+  if params.length ~= nil then
+    reaper.SetMediaItemInfo_Value(item, "D_LENGTH", params.length)
+  end
+  if params.volume ~= nil then
+    reaper.SetMediaItemInfo_Value(item, "D_VOL", from_db(params.volume))
+  end
+  if params.mute ~= nil then
+    reaper.SetMediaItemInfo_Value(item, "B_MUTE", params.mute)
+  end
+  if params.fadeInLength ~= nil then
+    reaper.SetMediaItemInfo_Value(item, "D_FADEINLEN", params.fadeInLength)
+  end
+  if params.fadeOutLength ~= nil then
+    reaper.SetMediaItemInfo_Value(item, "D_FADEOUTLEN", params.fadeOutLength)
+  end
+  if params.playRate ~= nil then
+    local take = reaper.GetActiveTake(item)
+    if take then
+      reaper.SetMediaItemTakeInfo_Value(take, "D_PLAYRATE", params.playRate)
+    end
+  end
+
+  reaper.Undo_EndBlock("MCP: Set media item properties", -1)
+  reaper.UpdateArrange()
+
+  return { success = true, trackIndex = params.trackIndex, itemIndex = params.itemIndex }
+end
+
+function handlers.split_media_item(params)
+  local track, item, err = get_media_item(params)
+  if err then return nil, err end
+
+  local position = params.position
+  if not position then return nil, "position required" end
+
+  local item_start = reaper.GetMediaItemInfo_Value(item, "D_POSITION")
+  local item_end = item_start + reaper.GetMediaItemInfo_Value(item, "D_LENGTH")
+  if position <= item_start or position >= item_end then
+    return nil, "Split position must be within item bounds (" .. item_start .. "s - " .. item_end .. "s)"
+  end
+
+  reaper.Undo_BeginBlock()
+  local right_item = reaper.SplitMediaItem(item, position)
+  reaper.Undo_EndBlock("MCP: Split media item", -1)
+
+  if not right_item then return nil, "Failed to split item at position " .. position end
+
+  reaper.UpdateArrange()
+
+  return {
+    success = true,
+    leftItem = {
+      position = reaper.GetMediaItemInfo_Value(item, "D_POSITION"),
+      length = reaper.GetMediaItemInfo_Value(item, "D_LENGTH"),
+    },
+    rightItem = {
+      position = reaper.GetMediaItemInfo_Value(right_item, "D_POSITION"),
+      length = reaper.GetMediaItemInfo_Value(right_item, "D_LENGTH"),
+    },
+  }
+end
+
+function handlers.delete_media_item(params)
+  local track, item, err = get_media_item(params)
+  if err then return nil, err end
+
+  reaper.Undo_BeginBlock()
+  local ok = reaper.DeleteTrackMediaItem(track, item)
+  reaper.Undo_EndBlock("MCP: Delete media item", -1)
+
+  if not ok then return nil, "Failed to delete item" end
+
+  reaper.UpdateArrange()
+
+  return { success = true, trackIndex = params.trackIndex, itemIndex = params.itemIndex }
+end
+
+function handlers.move_media_item(params)
+  local track, item, err = get_media_item(params)
+  if err then return nil, err end
+
+  reaper.Undo_BeginBlock()
+
+  if params.newPosition ~= nil then
+    reaper.SetMediaItemInfo_Value(item, "D_POSITION", params.newPosition)
+  end
+
+  if params.newTrackIndex ~= nil then
+    local dest_track = reaper.GetTrack(0, params.newTrackIndex)
+    if not dest_track then
+      reaper.Undo_EndBlock("MCP: Move media item (failed)", -1)
+      return nil, "Destination track " .. params.newTrackIndex .. " not found"
+    end
+    reaper.MoveMediaItemToTrack(item, dest_track)
+  end
+
+  reaper.Undo_EndBlock("MCP: Move media item", -1)
+  reaper.UpdateArrange()
+
+  return {
+    success = true,
+    position = reaper.GetMediaItemInfo_Value(item, "D_POSITION"),
+    trackIndex = params.newTrackIndex or params.trackIndex,
+  }
+end
+
+function handlers.trim_media_item(params)
+  local track, item, err = get_media_item(params)
+  if err then return nil, err end
+
+  reaper.Undo_BeginBlock()
+
+  local pos = reaper.GetMediaItemInfo_Value(item, "D_POSITION")
+  local len = reaper.GetMediaItemInfo_Value(item, "D_LENGTH")
+  local take = reaper.GetActiveTake(item)
+
+  if params.trimStart ~= nil and params.trimStart ~= 0 then
+    local new_pos = pos + params.trimStart
+    local new_len = len - params.trimStart
+    if new_len <= 0 then
+      reaper.Undo_EndBlock("MCP: Trim media item (failed)", -1)
+      return nil, "trimStart would result in zero or negative length"
+    end
+    reaper.SetMediaItemInfo_Value(item, "D_POSITION", new_pos)
+    reaper.SetMediaItemInfo_Value(item, "D_LENGTH", new_len)
+    -- Adjust take start offset
+    if take then
+      local offset = reaper.GetMediaItemTakeInfo_Value(take, "D_STARTOFFS")
+      reaper.SetMediaItemTakeInfo_Value(take, "D_STARTOFFS", offset + params.trimStart)
+    end
+    pos = new_pos
+    len = new_len
+  end
+
+  if params.trimEnd ~= nil and params.trimEnd ~= 0 then
+    local new_len = len - params.trimEnd
+    if new_len <= 0 then
+      reaper.Undo_EndBlock("MCP: Trim media item (failed)", -1)
+      return nil, "trimEnd would result in zero or negative length"
+    end
+    reaper.SetMediaItemInfo_Value(item, "D_LENGTH", new_len)
+    len = new_len
+  end
+
+  reaper.Undo_EndBlock("MCP: Trim media item", -1)
+  reaper.UpdateArrange()
+
+  return {
+    success = true,
+    position = pos,
+    length = len,
+  }
+end
+
+function handlers.add_stretch_marker(params)
+  local track, item, err = get_media_item(params)
+  if err then return nil, err end
+
+  local position = params.position
+  if not position then return nil, "position required" end
+
+  local take = reaper.GetActiveTake(item)
+  if not take then return nil, "Item has no active take" end
+
+  local src_pos = params.sourcePosition or position
+
+  reaper.Undo_BeginBlock()
+  local idx = reaper.SetTakeStretchMarker(take, -1, position, src_pos)
+  reaper.Undo_EndBlock("MCP: Add stretch marker", -1)
+
+  if idx < 0 then return nil, "Failed to add stretch marker" end
+
+  reaper.UpdateItemInProject(item)
+  reaper.UpdateArrange()
+
+  return {
+    success = true,
+    markerIndex = idx,
+    position = position,
+    sourcePosition = src_pos,
+    totalMarkers = reaper.GetTakeNumStretchMarkers(take),
+  }
+end
+
+function handlers.get_stretch_markers(params)
+  local track, item, err = get_media_item(params)
+  if err then return nil, err end
+
+  local take = reaper.GetActiveTake(item)
+  if not take then return nil, "Item has no active take" end
+
+  local count = reaper.GetTakeNumStretchMarkers(take)
+  local markers = {}
+
+  for i = 0, count - 1 do
+    local _, pos, src_pos = reaper.GetTakeStretchMarker(take, i)
+    markers[#markers + 1] = {
+      index = i,
+      position = pos,
+      sourcePosition = src_pos,
+    }
+  end
+
+  return { trackIndex = params.trackIndex, itemIndex = params.itemIndex, markers = markers, total = count }
+end
+
+function handlers.delete_stretch_marker(params)
+  local track, item, err = get_media_item(params)
+  if err then return nil, err end
+
+  local marker_idx = params.markerIndex
+  if marker_idx == nil then return nil, "markerIndex required" end
+
+  local take = reaper.GetActiveTake(item)
+  if not take then return nil, "Item has no active take" end
+
+  local count = reaper.GetTakeNumStretchMarkers(take)
+  if marker_idx >= count then
+    return nil, "Marker index " .. marker_idx .. " out of range (item has " .. count .. " markers)"
+  end
+
+  reaper.Undo_BeginBlock()
+  reaper.DeleteTakeStretchMarkers(take, marker_idx, 1)
+  reaper.Undo_EndBlock("MCP: Delete stretch marker", -1)
+
+  reaper.UpdateItemInProject(item)
+  reaper.UpdateArrange()
+
+  return { success = true, totalMarkers = reaper.GetTakeNumStretchMarkers(take) }
+end
+
 -- =============================================================================
 -- Command dispatcher
 -- =============================================================================