laive-mcp 0.1.0

package/packages/live-bridge-remote-script/src/fixtures/default-live-set.json

@@ -0,0 +1,113 @@
+{
+  "live_version": "12.3.0",
+  "capabilities": {
+    "read_state": true,
+    "set_transport": true,
+    "create_track": true,
+    "create_scene": true,
+    "create_clip": true,
+    "insert_notes": true,
+    "set_parameter": true,
+    "subscribe": true
+  },
+  "song": {
+    "id": "song:current",
+    "name": "Fixture Set",
+    "tempo": 124,
+    "time_signature_numerator": 4,
+    "time_signature_denominator": 4,
+    "is_playing": false,
+    "arrangement_position_beats": 0,
+    "loop": {
+      "enabled": false,
+      "start_beats": 0,
+      "length_beats": 16
+    }
+  },
+  "scenes": [
+    {
+      "id": "scene:1",
+      "index": 0,
+      "name": "Intro"
+    },
+    {
+      "id": "scene:2",
+      "index": 1,
+      "name": "Drop"
+    }
+  ],
+  "tracks": [
+    {
+      "id": "track:1",
+      "index": 0,
+      "name": "Drums",
+      "type": "midi",
+      "color": 1,
+      "arm": false,
+      "mute": false,
+      "solo": false,
+      "devices": [
+        {
+          "id": "device:track:1:1",
+          "name": "Drum Rack",
+          "class_name": "InstrumentGroupDevice",
+          "parameters": [
+            {
+              "id": "parameter:device:track:1:1:1",
+              "name": "Macro 1",
+              "value": 0.5,
+              "min": 0,
+              "max": 1,
+              "display_value": "64"
+            }
+          ]
+        }
+      ],
+      "session_clips": [
+        {
+          "id": "clip:session:track:1:slot:1",
+          "slot_index": 0,
+          "name": "Beat A",
+          "length_beats": 4,
+          "is_playing": false,
+          "notes": [
+            {
+              "pitch": 36,
+              "start_beats": 0,
+              "duration_beats": 1,
+              "velocity": 100
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "track:2",
+      "index": 1,
+      "name": "Bass",
+      "type": "midi",
+      "color": 2,
+      "arm": false,
+      "mute": false,
+      "solo": false,
+      "devices": [
+        {
+          "id": "device:track:2:1",
+          "name": "Operator",
+          "class_name": "Operator",
+          "parameters": [
+            {
+              "id": "parameter:device:track:2:1:1",
+              "name": "Volume",
+              "value": 0.65,
+              "min": 0,
+              "max": 1,
+              "display_value": "-3.1 dB"
+            }
+          ]
+        }
+      ],
+      "session_clips": []
+    }
+  ]
+}

package/packages/live-bridge-remote-script/src/index.js

@@ -0,0 +1,3 @@
+export * from "./bridge/client.js";
+export * from "./bridge/server.js";
+export * from "./runtime/fixture-runtime.js";

package/packages/live-bridge-remote-script/src/runtime/fixture-runtime.js

@@ -0,0 +1,356 @@
+import { EventEmitter } from "node:events";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+const defaultFixturePath = fileURLToPath(
+  new URL("../fixtures/default-live-set.json", import.meta.url)
+);
+
+export class FixtureLiveRuntime extends EventEmitter {
+  constructor(fixtureState) {
+    super();
+    this.state = fixtureState;
+  }
+
+  static async fromFixture(fixturePath = defaultFixturePath) {
+    const payload = JSON.parse(await readFile(fixturePath, "utf8"));
+    return new FixtureLiveRuntime(payload);
+  }
+
+  get liveVersion() {
+    return this.state.live_version;
+  }
+
+  get capabilities() {
+    return clone(this.state.capabilities);
+  }
+
+  async execute(message) {
+    switch (message.operation) {
+      case "hello":
+        return {
+          bridge: "laive-fixture-runtime",
+          protocol_version: "0.1.0",
+          live_version: this.liveVersion
+        };
+      case "capabilities":
+        return this.capabilities;
+      case "health":
+        return {
+          status: "ok",
+          fixture_loaded: true,
+          track_count: this.state.tracks.length
+        };
+      case "get":
+        return this.handleGet(message.target, message.arguments);
+      case "set":
+        return this.handleSet(message.target, message.arguments, message.dry_run);
+      case "call":
+        return this.handleCall(message.target, message.arguments, message.dry_run);
+      default:
+        throw new Error(`Unsupported runtime operation: ${message.operation}`);
+    }
+  }
+
+  handleGet(target = "song") {
+    switch (target) {
+      case "song":
+        return clone(this.state.song);
+      case "tracks":
+        return clone(this.state.tracks);
+      case "scenes":
+        return clone(this.state.scenes);
+      default:
+        return this.lookupTarget(target);
+    }
+  }
+
+  handleSet(target, args, dryRun) {
+    if (target === "song.tempo") {
+      const tempo = Number(args.value);
+      if (!Number.isFinite(tempo) || tempo <= 0) {
+        throw new Error("tempo must be a positive number");
+      }
+      if (!dryRun) {
+        this.state.song.tempo = tempo;
+        this.emit("event", {
+          topic: "transport.changed",
+          payload: {
+            tempo
+          }
+        });
+      }
+      return {
+        target,
+        applied: !dryRun,
+        value: tempo
+      };
+    }
+
+    if (target?.startsWith("parameter:")) {
+      return this.setParameter(target, args, dryRun);
+    }
+
+    throw new Error(`Unsupported set target: ${target}`);
+  }
+
+  handleCall(target, args, dryRun) {
+    switch (target) {
+      case "transport.play":
+        if (!dryRun) {
+          this.state.song.is_playing = true;
+          this.emit("event", {
+            topic: "transport.changed",
+            payload: { is_playing: true }
+          });
+        }
+        return { target, applied: !dryRun, is_playing: true };
+      case "transport.stop":
+        if (!dryRun) {
+          this.state.song.is_playing = false;
+          this.emit("event", {
+            topic: "transport.changed",
+            payload: { is_playing: false }
+          });
+        }
+        return { target, applied: !dryRun, is_playing: false };
+      case "create_track":
+        return this.createTrack(args, dryRun);
+      case "create_scene":
+        return this.createScene(args, dryRun);
+      case "create_clip":
+        return this.createClip(args, dryRun);
+      case "insert_notes":
+        return this.insertNotes(args, dryRun);
+      case "fire_clip":
+        return this.fireClip(args, dryRun);
+      default:
+        throw new Error(`Unsupported call target: ${target}`);
+    }
+  }
+
+  lookupTarget(target) {
+    if (!target) {
+      throw new Error("target is required");
+    }
+
+    if (target.startsWith("track:")) {
+      return clone(this.findTrack(target));
+    }
+
+    if (target.startsWith("device:")) {
+      return clone(this.findDevice(target));
+    }
+
+    if (target.startsWith("parameter:")) {
+      return clone(this.findParameter(target));
+    }
+
+    if (target.startsWith("clip:")) {
+      return clone(this.findClip(target));
+    }
+
+    throw new Error(`Unknown target: ${target}`);
+  }
+
+  findTrack(trackId) {
+    const track = this.state.tracks.find((item) => item.id === trackId);
+    if (!track) {
+      throw new Error(`Track not found: ${trackId}`);
+    }
+    return track;
+  }
+
+  findDevice(deviceId) {
+    for (const track of this.state.tracks) {
+      const device = track.devices.find((item) => item.id === deviceId);
+      if (device) {
+        return device;
+      }
+    }
+    throw new Error(`Device not found: ${deviceId}`);
+  }
+
+  findParameter(parameterId) {
+    for (const track of this.state.tracks) {
+      for (const device of track.devices) {
+        const parameter = device.parameters.find((item) => item.id === parameterId);
+        if (parameter) {
+          return parameter;
+        }
+      }
+    }
+    throw new Error(`Parameter not found: ${parameterId}`);
+  }
+
+  findClip(clipId) {
+    for (const track of this.state.tracks) {
+      const clip = track.session_clips.find((item) => item.id === clipId);
+      if (clip) {
+        return clip;
+      }
+    }
+    throw new Error(`Clip not found: ${clipId}`);
+  }
+
+  setParameter(parameterId, args, dryRun) {
+    const parameter = this.findParameter(parameterId);
+    const value = Number(args.value);
+    if (!Number.isFinite(value)) {
+      throw new Error("parameter value must be numeric");
+    }
+    if (!dryRun) {
+      parameter.value = Math.min(parameter.max, Math.max(parameter.min, value));
+      this.emit("event", {
+        topic: "parameters.changed",
+        payload: { parameter_id: parameterId, value: parameter.value }
+      });
+    }
+    return {
+      target: parameterId,
+      applied: !dryRun,
+      value: Math.min(parameter.max, Math.max(parameter.min, value))
+    };
+  }
+
+  createTrack(args, dryRun) {
+    const nextIndex = this.state.tracks.length;
+    const nextId = `track:${nextIndex + 1}`;
+    const track = {
+      id: nextId,
+      index: nextIndex,
+      name: args.name ?? `Track ${nextIndex + 1}`,
+      type: args.type ?? "midi",
+      color: args.color ?? 0,
+      arm: false,
+      mute: false,
+      solo: false,
+      devices: [],
+      session_clips: []
+    };
+
+    if (!dryRun) {
+      this.state.tracks.push(track);
+      this.emit("event", {
+        topic: "tracks.changed",
+        payload: { action: "created", track }
+      });
+    }
+
+    return {
+      applied: !dryRun,
+      track
+    };
+  }
+
+  createScene(args, dryRun) {
+    const nextIndex = this.state.scenes.length;
+    const scene = {
+      id: `scene:${nextIndex + 1}`,
+      index: nextIndex,
+      name: args.name ?? `Scene ${nextIndex + 1}`
+    };
+
+    if (!dryRun) {
+      this.state.scenes.push(scene);
+      this.emit("event", {
+        topic: "clips.changed",
+        payload: { action: "scene-created", scene }
+      });
+    }
+
+    return {
+      applied: !dryRun,
+      scene
+    };
+  }
+
+  createClip(args, dryRun) {
+    const track = this.findTrack(args.track_id);
+    const nextIndex = track.session_clips.length;
+    const clip = {
+      id: `clip:session:${track.id}:slot:${nextIndex + 1}`,
+      slot_index: nextIndex,
+      name: args.name ?? `Clip ${nextIndex + 1}`,
+      length_beats: args.length_beats ?? 4,
+      is_playing: false,
+      notes: []
+    };
+
+    if (!dryRun) {
+      track.session_clips.push(clip);
+      this.emit("event", {
+        topic: "clips.changed",
+        payload: {
+          action: "clip-created",
+          track_id: track.id,
+          clip
+        }
+      });
+    }
+
+    return {
+      applied: !dryRun,
+      clip
+    };
+  }
+
+  insertNotes(args, dryRun) {
+    const clip = this.findClip(args.clip_id);
+    const notes = Array.isArray(args.notes) ? clone(args.notes) : [];
+
+    if (!dryRun) {
+      clip.notes.push(...notes);
+      this.emit("event", {
+        topic: "clips.changed",
+        payload: {
+          action: "notes-inserted",
+          clip_id: clip.id,
+          notes
+        }
+      });
+    }
+
+    return {
+      applied: !dryRun,
+      clip_id: clip.id,
+      note_count: clip.notes.length
+    };
+  }
+
+  fireClip(args, dryRun) {
+    const clip = this.findClip(args.clip_id);
+
+    if (!dryRun) {
+      for (const track of this.state.tracks) {
+        for (const candidate of track.session_clips) {
+          candidate.is_playing = candidate.id === clip.id;
+        }
+      }
+      this.emit("event", {
+        topic: "clips.changed",
+        payload: {
+          action: "clip-fired",
+          clip_id: clip.id
+        }
+      });
+    }
+
+    return {
+      applied: !dryRun,
+      clip_id: clip.id
+    };
+  }
+}
+
+export function resolveFixturePath(inputPath) {
+  if (!inputPath) {
+    return defaultFixturePath;
+  }
+  return path.resolve(process.cwd(), inputPath);
+}

package/packages/live-sidecar-m4l/README.md

@@ -0,0 +1,45 @@
+# `@laive/live-sidecar-m4l`
+
+This package contains the source assets and shipped `.amxd` for the `laive` Max MIDI Effect sidecar project.
+
+What is included:
+
+- a testable Node-side runtime core under `src/`
+- a source Max project under `project/`
+- a Node for Max entry script at `project/code/laive-sidecar-node.js`
+- a patcher source file at `project/patchers/laive-sidecar.maxpat`
+- a shipped Max for Live device at `device/laive-sidecar.amxd`
+- a staging helper that copies the sidecar project into a portable folder for delivery
+
+This package does **not** generate a finished `.amxd` automatically. The deliverable here is the importable source project and patcher assets that can be opened in Max / Max for Live, inspected, and saved as a device by the user.
+
+## Layout
+
+- `src/contracts.js`
+- `src/workflows.js`
+- `src/runtime.js`
+- `src/package-sidecar.js`
+- `project/laive-sidecar.maxproj`
+- `project/patchers/laive-sidecar.maxpat`
+- `project/code/laive-sidecar-node.js`
+- `project/data/laive-sidecar.manifest.json`
+- `device/laive-sidecar.amxd`
+
+## Package The Source Project
+
+From this package directory:
+
+```sh
+npm test
+npm run package:project
+```
+
+The staging helper copies the source project into the repository-level `artifacts/live-sidecar-m4l/`.
+
+## Manual Max For Live Steps
+
+1. Preferred end-user path: use the shipped `device/laive-sidecar.amxd`.
+2. Developer path: open the staged `laive-sidecar/laive-sidecar.maxproj` in Max if you need the source project.
+3. Open `laive-sidecar/patchers/laive-sidecar.maxpat` if you need the source patcher.
+4. Confirm the `node.script` object points at `../code/laive-sidecar-node.js`.
+5. Drop the `.amxd` onto a MIDI track in Live and validate transport, context, and note workflows.

package/packages/live-sidecar-m4l/project/code/laive-sidecar-node.js

@@ -0,0 +1,149 @@
+"use strict";
+
+function createCapabilityMap(overrides) {
+  return Object.assign(
+    {
+      noteEditing: true,
+      objectObservation: true,
+      deviceIntrospection: true,
+      realtimeAnalysis: false,
+      browserInsertion: false
+    },
+    overrides || {}
+  );
+}
+
+const workflows = {
+  snapshotSelectionContext: {
+    description: "Read selected track, clip, and device context from the official Live API.",
+    requiredCapabilities: ["objectObservation"],
+    queryPaths: ["live_set view selected_track", "live_set view detail_clip"]
+  },
+  replaceClipNotes: {
+    description: "Apply a note payload to a target MIDI clip in a single sidecar transaction.",
+    requiredCapabilities: ["noteEditing"],
+    target: "clip"
+  },
+  observeDeviceParameters: {
+    description: "Start a parameter observation stream for the selected device.",
+    requiredCapabilities: ["objectObservation", "deviceIntrospection"],
+    target: "device:selected"
+  }
+};
+
+function loadMaxApi() {
+  try {
+    return require("max-api");
+  } catch (_error) {
+    return {
+      post(message) {
+        process.stdout.write(String(message) + "\n");
+      },
+      outlet(message) {
+        process.stdout.write(JSON.stringify(message) + "\n");
+      },
+      addHandlers(handlers) {
+        global.__laiveMaxHandlers = handlers;
+      }
+    };
+  }
+}
+
+const Max = loadMaxApi();
+const capabilities = createCapabilityMap();
+
+function emit(type, payload) {
+  Max.outlet({
+    type,
+    payload
+  });
+}
+
+function normalizeMessage(rawMessage) {
+  if (typeof rawMessage !== "string") {
+    return rawMessage;
+  }
+
+  const trimmed = rawMessage.trim();
+  if (!trimmed) {
+    return {};
+  }
+
+  if (trimmed === "hello" || trimmed === "capabilities" || trimmed === "list_workflows") {
+    return {
+      command: trimmed
+    };
+  }
+
+  const looseCommandMatch = trimmed.match(/^\{\s*command\s*:\s*([A-Za-z0-9_:-]+)\s*\}$/);
+  if (looseCommandMatch) {
+    return {
+      command: looseCommandMatch[1]
+    };
+  }
+
+  return rawMessage;
+}
+
+async function handleMessage(rawMessage) {
+  let message = normalizeMessage(rawMessage);
+
+  if (typeof message === "string") {
+    try {
+      message = JSON.parse(message);
+    } catch (error) {
+      emit("error", {
+        code: "invalid_json",
+        message: error.message
+      });
+      return;
+    }
+  }
+
+  switch (message.command) {
+    case "hello":
+      emit("hello", {
+        runtime: "laive-sidecar-node",
+        version: "0.1.0"
+      });
+      return;
+    case "capabilities":
+      emit("capabilities", capabilities);
+      return;
+    case "list_workflows":
+      emit("query", {
+        workflows: Object.keys(workflows).map(function (name) {
+          return {
+            name: name,
+            description: workflows[name].description
+          };
+        })
+      });
+      return;
+    default:
+      emit("error", {
+        code: "unknown_command",
+        message: "Unknown command: " + message.command
+      });
+  }
+}
+
+Max.post("laive-sidecar Node for Max source loaded");
+Max.addHandlers({
+  message: handleMessage,
+  hello: function () {
+    return handleMessage("hello");
+  },
+  capabilities: function () {
+    return handleMessage("capabilities");
+  },
+  list_workflows: function () {
+    return handleMessage("list_workflows");
+  },
+  bang: function () {
+    emit("hello", {
+      runtime: "laive-sidecar-node",
+      version: "0.1.0"
+    });
+  }
+});

package/packages/live-sidecar-m4l/project/data/laive-sidecar.manifest.json

@@ -0,0 +1,8 @@
+{
+  "name": "laive-sidecar",
+  "project_file": "laive-sidecar.maxproj",
+  "patcher": "laive-sidecar.maxpat",
+  "node_script": "laive-sidecar-node.js",
+  "source_only": true,
+  "description": "Source project for the laive Max for Live sidecar."
+}

package/packages/live-sidecar-m4l/project/laive-sidecar.maxproj

@@ -0,0 +1,36 @@
+{
+  "name": "laive-sidecar",
+  "version": 1,
+  "creationdate": 3856982400,
+  "modificationdate": 3857056952,
+  "viewrect": [65.0, 101.0, 320.0, 220.0],
+  "autoorganize": 1,
+  "hideprojectwindow": 0,
+  "showdependencies": 1,
+  "autolocalize": 0,
+  "contents": {
+    "patchers": {
+      "laive-sidecar.maxpat": {
+        "kind": "patcher",
+        "local": 1,
+        "toplevel": 1
+      }
+    },
+    "code": {
+      "laive-sidecar-node.js": {
+        "kind": "javascript",
+        "local": 1
+      }
+    }
+  },
+  "layout": {},
+  "searchpath": {},
+  "detailsvisible": 0,
+  "amxdtype": 1835887981,
+  "readonly": 0,
+  "devpathtype": 0,
+  "devpath": ".",
+  "sortmode": 0,
+  "viewmode": 0,
+  "includepackages": 0
+}