laive-mcp 0.1.4 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## v0.2.0 - 2026-03-22
+
+- Updated the README to advertise the currently proven live MCP capabilities separately from lower-level bridge capabilities that are not yet surfaced as first-class MCP tools.
+- Expanded the MCP server to expose the remaining control-surface bridge tools for transport control, scene creation, and MIDI note insertion.
+- Added optional sidecar and UI-helper MCP workflow tools plus `get_component_status`, with structured setup instructions when those optional components are unavailable.
+- Fixed the Remote Script packaging helper to retry staged-tree cleanup so `laive-mcp package` no longer fails intermittently on existing `__pycache__` directories.
+
 ## v0.1.4 - 2026-03-22
 
 - Fixed MCP tool schema advertising so argument-bearing tools like `set_tempo`, `get_track_details`, `get_device_tree`, `create_clip`, and `set_parameter` now publish explicit JSON Schemas through `tools/list` instead of empty input objects, allowing Codex clients to send required parameters.

package/README.md

@@ -11,6 +11,36 @@ Today, the repo ships:
 - a staged `laive-ui-helper.app` bundle for UI fallback permissions
 - `.als` parsing scaffolds
 
+## Proven MCP Capabilities
+
+With Ableton Live running and the `laive` Control Surface enabled, the published MCP server can currently drive these workflows end-to-end:
+
+- read the current project summary
+- read the selected track, scene, clip, and device context
+- list tracks
+- read detailed track state, including session clips
+- read a track's device tree and parameter state
+- refresh the mirrored project state
+- set song tempo
+- start and stop transport
+- create MIDI or audio tracks
+- create scenes
+- create MIDI clips in session slots
+- insert MIDI notes into clips
+- set device parameter values
+- report optional sidecar and UI-helper availability with setup guidance
+- list and invoke optional sidecar workflows
+- list and invoke optional UI-helper workflows
+
+These capabilities have been validated against a live Ableton session through the published `laive-mcp` package, not just fixture mode.
+
+The optional components are intentionally soft-failable:
+
+- if the Max for Live sidecar is not installed or not connected, the MCP tools return structured setup instructions for the agent to relay
+- if the macOS UI helper is not installed or Accessibility is not granted, the MCP tools return setup instructions instead of silently failing
+
+The bridge also reports lower-level support for subscriptions / event streaming, but that is not yet surfaced as a first-class MCP notification channel in the current release.
+
 If you are using this as an end user, the published npm entrypoint is `laive-mcp`. The Ableton-side control surface name remains `laive`.
 
 ## Published Package

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "laive-mcp",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Local MCP, install tooling, and helper assets for controlling Ableton Live.",
   "license": "GPL-3.0-only",
   "type": "module",

package/packages/live-bridge-remote-script/python/laive/live_access.py

@@ -144,13 +144,14 @@ class LiveSetAdapter(object):
 
     def insert_notes(self, clip_id, notes, dry_run=False):
         clip, track_id, slot_index = self._find_clip(clip_id)
+        normalized_notes = [self._tuple_note(note) for note in notes]
         if not dry_run:
             if hasattr(clip, "add_new_notes"):
-                clip.add_new_notes(notes)
+                clip.add_new_notes(tuple(normalized_notes))
             elif hasattr(clip, "set_notes"):
-                clip.set_notes(tuple(self._tuple_note(note) for note in notes))
+                clip.set_notes(tuple(normalized_notes))
             else:
-                clip.notes.extend(notes)
+                clip.notes.extend(normalized_notes)
         note_count = len(notes)
         clip_state = self._serialize_clip(clip, track_id, slot_index)
         clip_state["note_count"] = len(getattr(clip, "notes", [])) if not dry_run else note_count
@@ -265,8 +266,8 @@ class LiveSetAdapter(object):
     def _tuple_note(self, note):
         return (
             note.get("pitch", 60),
-            note.get("start_beats", 0.0),
-            note.get("duration_beats", 0.25),
+            note.get("start_beats", note.get("startBeats", 0.0)),
+            note.get("duration_beats", note.get("durationBeats", 0.25)),
             note.get("velocity", 100),
             bool(note.get("mute", False)),
         )

package/packages/mcp-server/src/cli.js

@@ -3,6 +3,11 @@ import readline from "node:readline";
 import process from "node:process";
 
 import { LaiveMcpServer } from "./server.js";
+import {
+  createIntegrationStatusAdapter,
+  createSidecarAdapter,
+  createUiAutomationAdapter
+} from "./optional-adapters.js";
 import {
   LaiveBridgeSession,
   LaiveFixtureSession,
@@ -53,10 +58,23 @@ async function createSession(options) {
 async function main() {
   const options = parseArgs();
   const session = await createSession(options);
+  const stateAdapter = createStateAdapter(session);
+  const bridgeAdapter = createBridgeAdapter(session);
+  const sidecarAdapter = createSidecarAdapter({
+    stateAdapter,
+    bridgeAdapter
+  });
+  const uiAutomationAdapter = createUiAutomationAdapter();
   const server = new LaiveMcpServer({
-    stateAdapter: createStateAdapter(session),
-    bridgeAdapter: createBridgeAdapter(session),
-      policyAdapter: createAllowAllPolicyAdapter()
+    stateAdapter,
+    bridgeAdapter,
+    sidecarAdapter,
+    uiAutomationAdapter,
+    integrationStatusAdapter: createIntegrationStatusAdapter({
+      sidecarAdapter,
+      uiAutomationAdapter
+    }),
+    policyAdapter: createAllowAllPolicyAdapter()
   });
   let lineReader = null;
 

package/packages/mcp-server/src/default-tools.js

@@ -24,6 +24,15 @@ function requireString(value, fieldName) {
   }
 }
 
+function requireNotes(notes) {
+  if (!Array.isArray(notes) || notes.length === 0) {
+    throw new McpServerError(
+      "invalid_request",
+      "notes must be a non-empty array of MIDI note objects"
+    );
+  }
+}
+
 function buildMutationResult(summary, affectedObjects, beforeVersion, afterVersion, warnings = []) {
   return {
     summary,
@@ -35,7 +44,78 @@ function buildMutationResult(summary, affectedObjects, beforeVersion, afterVersi
   };
 }
 
-export function buildDefaultTools({ stateAdapter, bridgeAdapter, policyAdapter }) {
+function buildInformationalResult(summary, payload = {}, nextActions = []) {
+  return {
+    summary,
+    affected_objects: payload.affected_objects ?? [],
+    state_version_before: payload.state_version_before ?? null,
+    state_version_after: payload.state_version_after ?? null,
+    warnings: payload.warnings ?? [],
+    next_suggested_actions: nextActions,
+    ...payload
+  };
+}
+
+function buildWorkflowSchema(description) {
+  return {
+    type: "object",
+    properties: {
+      name: {
+        type: "string",
+        description
+      },
+      parameters: {
+        type: "object",
+        description: "Workflow-specific parameters.",
+        additionalProperties: true
+      }
+    },
+    required: ["name"],
+    additionalProperties: false
+  };
+}
+
+const noteItemSchema = {
+  type: "object",
+  properties: {
+    pitch: {
+      type: "integer",
+      minimum: 0,
+      maximum: 127
+    },
+    startBeats: {
+      type: "number",
+      minimum: 0
+    },
+    durationBeats: {
+      type: "number",
+      exclusiveMinimum: 0
+    },
+    velocity: {
+      type: "integer",
+      minimum: 1,
+      maximum: 127
+    },
+    mute: {
+      type: "boolean"
+    }
+  },
+  required: ["pitch", "startBeats", "durationBeats", "velocity"],
+  additionalProperties: false
+};
+
+const dryRunProperty = {
+  type: "boolean",
+  description: "If true, preview the action without mutating Live."
+};
+
+export function buildDefaultTools({
+  stateAdapter,
+  bridgeAdapter,
+  policyAdapter,
+  sidecarAdapter,
+  uiAutomationAdapter
+}) {
   return [
     {
       name: "get_project_summary",
@@ -158,6 +238,35 @@ export function buildDefaultTools({ stateAdapter, bridgeAdapter, policyAdapter }
         };
       }
     },
+    {
+      name: "get_component_status",
+      description:
+        "Report control-surface, Max sidecar, and UI-helper availability, including setup guidance for optional components.",
+      inputSchema: EMPTY_OBJECT_SCHEMA,
+      async execute() {
+        const [bridgeCapabilities, sidecarStatus, uiHelperStatus] = await Promise.all([
+          bridgeAdapter.getCapabilities(),
+          sidecarAdapter.getStatus(),
+          uiAutomationAdapter.getStatus()
+        ]);
+
+        return buildInformationalResult(
+          "Component status loaded.",
+          {
+            affected_objects: ["bridge", "sidecar", "ui_helper"],
+            components: {
+              bridge: {
+                available: true,
+                capabilities: bridgeCapabilities
+              },
+              sidecar: sidecarStatus,
+              ui_helper: uiHelperStatus
+            }
+          },
+          ["get_capabilities", "list_sidecar_workflows", "list_ui_workflows"]
+        );
+      }
+    },
     {
       name: "set_tempo",
       description: "Update the current song tempo.",
@@ -194,6 +303,56 @@ export function buildDefaultTools({ stateAdapter, bridgeAdapter, policyAdapter }
         );
       }
     },
+    {
+      name: "play_transport",
+      description: "Start Ableton Live transport playback.",
+      inputSchema: createObjectSchema({
+        properties: {
+          dryRun: {
+            type: "boolean",
+            description: "If true, preview the action without mutating Live."
+          }
+        }
+      }),
+      async execute(args) {
+        await policyAdapter.assertAllowed("play_transport", args);
+        const before = await stateAdapter.getProjectSummary();
+        await bridgeAdapter.playTransport({ dryRun: Boolean(args.dryRun) });
+        const after = await stateAdapter.refreshState("song");
+        return buildMutationResult(
+          `Transport ${args.dryRun ? "play previewed" : "started"}.`,
+          ["song"],
+          before.stateVersion,
+          after.stateVersion,
+          after.warnings ?? []
+        );
+      }
+    },
+    {
+      name: "stop_transport",
+      description: "Stop Ableton Live transport playback.",
+      inputSchema: createObjectSchema({
+        properties: {
+          dryRun: {
+            type: "boolean",
+            description: "If true, preview the action without mutating Live."
+          }
+        }
+      }),
+      async execute(args) {
+        await policyAdapter.assertAllowed("stop_transport", args);
+        const before = await stateAdapter.getProjectSummary();
+        await bridgeAdapter.stopTransport({ dryRun: Boolean(args.dryRun) });
+        const after = await stateAdapter.refreshState("song");
+        return buildMutationResult(
+          `Transport ${args.dryRun ? "stop previewed" : "stopped"}.`,
+          ["song"],
+          before.stateVersion,
+          after.stateVersion,
+          after.warnings ?? []
+        );
+      }
+    },
     {
       name: "create_track",
       description: "Create a new track.",
@@ -225,6 +384,37 @@ export function buildDefaultTools({ stateAdapter, bridgeAdapter, policyAdapter }
         );
       }
     },
+    {
+      name: "create_scene",
+      description: "Create a new scene.",
+      inputSchema: createObjectSchema({
+        properties: {
+          name: {
+            type: "string",
+            description: "Optional scene name."
+          },
+          dryRun: {
+            type: "boolean",
+            description: "If true, preview the action without mutating Live."
+          }
+        }
+      }),
+      async execute(args) {
+        await policyAdapter.assertAllowed("create_scene", args);
+        const before = await stateAdapter.getProjectSummary();
+        const created = await bridgeAdapter.createScene(args.name ?? null, {
+          dryRun: Boolean(args.dryRun)
+        });
+        const after = await stateAdapter.refreshState("scenes");
+        return buildMutationResult(
+          `Scene ${args.dryRun ? "previewed" : "created"}.`,
+          created.affectedObjects ?? ["scenes"],
+          before.stateVersion,
+          after.stateVersion,
+          after.warnings ?? []
+        );
+      }
+    },
     {
       name: "create_clip",
       description: "Create a MIDI clip on a target track and slot.",
@@ -280,6 +470,50 @@ export function buildDefaultTools({ stateAdapter, bridgeAdapter, policyAdapter }
         );
       }
     },
+    {
+      name: "insert_notes",
+      description: "Insert or replace notes in a target MIDI clip.",
+      inputSchema: createObjectSchema({
+        properties: {
+          clipId: {
+            type: "string",
+            description: "Canonical clip id such as clip:session:track:8:slot:1."
+          },
+          notes: {
+            type: "array",
+            items: noteItemSchema,
+            description: "Note payload to apply to the clip."
+          },
+          dryRun: {
+            type: "boolean",
+            description: "If true, preview the action without mutating Live."
+          }
+        },
+        required: ["clipId", "notes"]
+      }),
+      async execute(args) {
+        requireString(args.clipId, "clipId");
+        requireNotes(args.notes);
+
+        await policyAdapter.assertAllowed("insert_notes", args);
+        const before = await stateAdapter.getProjectSummary();
+        const inserted = await bridgeAdapter.insertNotes(
+          {
+            clipId: args.clipId,
+            notes: args.notes
+          },
+          { dryRun: Boolean(args.dryRun) }
+        );
+        const after = await stateAdapter.refreshState("project");
+        return buildMutationResult(
+          `Notes ${args.dryRun ? "previewed" : "inserted"} for ${args.clipId}.`,
+          inserted.affectedObjects ?? [args.clipId],
+          before.stateVersion,
+          after.stateVersion,
+          after.warnings ?? []
+        );
+      }
+    },
     {
       name: "set_parameter",
       description: "Set a device parameter by track/device/parameter identifiers.",
@@ -339,6 +573,288 @@ export function buildDefaultTools({ stateAdapter, bridgeAdapter, policyAdapter }
         );
       }
     },
+    {
+      name: "list_sidecar_workflows",
+      description: "List optional Max for Live sidecar workflows and current availability.",
+      inputSchema: EMPTY_OBJECT_SCHEMA,
+      async execute() {
+        const result = await sidecarAdapter.listWorkflows();
+        return buildInformationalResult(
+          "Sidecar workflow status loaded.",
+          {
+            affected_objects: ["sidecar"],
+            sidecar: result
+          },
+          ["run_sidecar_workflow", "get_component_status"]
+        );
+      }
+    },
+    {
+      name: "sidecar_snapshot_selection_context",
+      description:
+        "Read selected track, clip, and device context through the optional Max for Live sidecar, or return setup instructions if it is unavailable.",
+      inputSchema: EMPTY_OBJECT_SCHEMA,
+      async execute() {
+        const result = await sidecarAdapter.snapshotSelectionContext();
+        return buildInformationalResult(
+          "Sidecar selection context loaded.",
+          {
+            affected_objects: Object.values(result.context ?? {})
+              .filter(Boolean)
+              .map((value) => value.id ?? value),
+            sidecar_workflow: result
+          },
+          ["get_selected_context", "get_component_status"]
+        );
+      }
+    },
+    {
+      name: "sidecar_replace_clip_notes",
+      description:
+        "Apply a note payload through the optional Max for Live sidecar, or return setup instructions if it is unavailable.",
+      inputSchema: createObjectSchema({
+        properties: {
+          clipId: {
+            type: "string",
+            description: "Canonical clip id such as clip:session:track:8:slot:1."
+          },
+          notes: {
+            type: "array",
+            items: noteItemSchema,
+            description: "Note payload to apply to the clip."
+          },
+          dryRun: dryRunProperty
+        },
+        required: ["clipId", "notes"]
+      }),
+      async execute(args) {
+        requireString(args.clipId, "clipId");
+        requireNotes(args.notes);
+        await policyAdapter.assertAllowed("sidecar_replace_clip_notes", args);
+        const before = await stateAdapter.getProjectSummary();
+        const replaced = await sidecarAdapter.replaceClipNotes({
+          clipId: args.clipId,
+          notes: args.notes,
+          dryRun: Boolean(args.dryRun)
+        });
+        const after = await stateAdapter.refreshState("project");
+        return buildMutationResult(
+          `Sidecar note replacement ${args.dryRun ? "previewed" : "applied"} for ${args.clipId}.`,
+          replaced.affectedObjects ?? [args.clipId],
+          before.stateVersion,
+          after.stateVersion,
+          after.warnings ?? []
+        );
+      }
+    },
+    {
+      name: "sidecar_observe_device_parameters",
+      description:
+        "Capture a selected-device parameter snapshot through the optional Max for Live sidecar, or return setup instructions if it is unavailable.",
+      inputSchema: createObjectSchema({
+        properties: {
+          trackId: {
+            type: "string",
+            description: "Optional track identifier when no track is selected in Live."
+          }
+        }
+      }),
+      async execute(args) {
+        const result = await sidecarAdapter.observeDeviceParameters({
+          trackId: args.trackId ?? null
+        });
+        return buildInformationalResult(
+          "Sidecar device parameter snapshot loaded.",
+          {
+            affected_objects: [
+              result.deviceTree?.trackId,
+              ...(result.deviceTree?.devices ?? []).map((device) => device.id)
+            ].filter(Boolean),
+            warnings: result.warnings ?? [],
+            sidecar_workflow: result
+          },
+          ["get_device_tree", "get_component_status"]
+        );
+      }
+    },
+    {
+      name: "run_sidecar_workflow",
+      description:
+        "Execute an optional Max for Live sidecar workflow, or return setup instructions if the sidecar is unavailable.",
+      inputSchema: buildWorkflowSchema(
+        "Sidecar workflow name, for example snapshotSelectionContext or replaceClipNotes."
+      ),
+      async execute(args) {
+        const result = await sidecarAdapter.executeWorkflow(args.name, args.parameters ?? {});
+        return buildInformationalResult(
+          `Sidecar workflow ${args.name} completed.`,
+          {
+            affected_objects: ["sidecar"],
+            sidecar_workflow: result
+          },
+          ["get_selected_context", "refresh_state"]
+        );
+      }
+    },
+    {
+      name: "list_ui_workflows",
+      description: "List optional UI-helper workflows and current availability.",
+      inputSchema: EMPTY_OBJECT_SCHEMA,
+      async execute() {
+        const result = await uiAutomationAdapter.listWorkflows();
+        return buildInformationalResult(
+          "UI workflow status loaded.",
+          {
+            affected_objects: ["ui_helper"],
+            ui_helper: result
+          },
+          ["run_ui_workflow", "get_component_status"]
+        );
+      }
+    },
+    {
+      name: "ui_capture_context",
+      description:
+        "Capture frontmost-app context through the optional UI helper, or return setup instructions if it is unavailable.",
+      inputSchema: EMPTY_OBJECT_SCHEMA,
+      async execute() {
+        const result = await uiAutomationAdapter.executeWorkflow("captureContext");
+        return buildInformationalResult(
+          "UI helper context captured.",
+          {
+            affected_objects: ["ui_helper"],
+            ui_workflow: result
+          },
+          ["get_component_status"]
+        );
+      }
+    },
+    {
+      name: "ui_focus_section",
+      description:
+        "Focus a named Live section through the optional UI helper, or return setup instructions if it is unavailable.",
+      inputSchema: createObjectSchema({
+        properties: {
+          sectionName: {
+            type: "string",
+            description: "Target Live section name."
+          }
+        },
+        required: ["sectionName"]
+      }),
+      async execute(args) {
+        requireString(args.sectionName, "sectionName");
+        const result = await uiAutomationAdapter.executeWorkflow("focusSection", {
+          sectionName: args.sectionName
+        });
+        return buildInformationalResult(
+          `UI helper focused ${args.sectionName}.`,
+          {
+            affected_objects: ["ui_helper"],
+            ui_workflow: result
+          },
+          ["get_component_status"]
+        );
+      }
+    },
+    {
+      name: "ui_browser_search_and_load",
+      description:
+        "Search Ableton's browser and trigger a load action through the optional UI helper, or return setup instructions if it is unavailable.",
+      inputSchema: createObjectSchema({
+        properties: {
+          query: {
+            type: "string",
+            description: "Browser search query."
+          }
+        },
+        required: ["query"]
+      }),
+      async execute(args) {
+        requireString(args.query, "query");
+        const result = await uiAutomationAdapter.executeWorkflow("browserSearchAndLoad", {
+          query: args.query
+        });
+        return buildInformationalResult(
+          `UI helper searched the browser for ${args.query}.`,
+          {
+            affected_objects: ["ui_helper"],
+            ui_workflow: result
+          },
+          ["get_component_status", "refresh_state"]
+        );
+      }
+    },
+    {
+      name: "ui_export_audio_video",
+      description:
+        "Open Ableton's Export Audio/Video dialog through the optional UI helper, or return setup instructions if it is unavailable.",
+      inputSchema: EMPTY_OBJECT_SCHEMA,
+      async execute() {
+        const result = await uiAutomationAdapter.executeWorkflow("exportAudioVideo");
+        return buildInformationalResult(
+          "UI helper opened the Export Audio/Video flow.",
+          {
+            affected_objects: ["ui_helper"],
+            ui_workflow: result
+          },
+          ["get_component_status"]
+        );
+      }
+    },
+    {
+      name: "ui_export_with_preset",
+      description:
+        "Apply an export preset through the optional UI helper, or return setup instructions if it is unavailable.",
+      inputSchema: createObjectSchema({
+        properties: {
+          presetName: {
+            type: "string",
+            description: "Preset name to enter in the export dialog."
+          },
+          outputPath: {
+            type: "string",
+            description: "Output folder to enter in the export dialog."
+          }
+        },
+        required: ["presetName", "outputPath"]
+      }),
+      async execute(args) {
+        requireString(args.presetName, "presetName");
+        requireString(args.outputPath, "outputPath");
+        const result = await uiAutomationAdapter.executeWorkflow("exportWithPreset", {
+          presetName: args.presetName,
+          outputPath: args.outputPath
+        });
+        return buildInformationalResult(
+          `UI helper staged export preset ${args.presetName}.`,
+          {
+            affected_objects: ["ui_helper"],
+            ui_workflow: result
+          },
+          ["get_component_status"]
+        );
+      }
+    },
+    {
+      name: "run_ui_workflow",
+      description:
+        "Execute an optional UI-helper workflow, or return setup instructions if the UI helper is unavailable.",
+      inputSchema: buildWorkflowSchema(
+        "UI workflow name, for example exportAudioVideo, browserSearchAndLoad, or captureContext."
+      ),
+      async execute(args) {
+        const result = await uiAutomationAdapter.executeWorkflow(args.name, args.parameters ?? {});
+        return buildInformationalResult(
+          `UI workflow ${args.name} completed.`,
+          {
+            affected_objects: ["ui_helper"],
+            ui_workflow: result
+          },
+          ["get_component_status", "refresh_state"]
+        );
+      }
+    },
     {
       name: "refresh_state",
       description: "Force a state refresh for a target scope.",
@@ -369,15 +885,25 @@ export function buildDefaultTools({ stateAdapter, bridgeAdapter, policyAdapter }
       description: "Return bridge and server capabilities.",
       inputSchema: EMPTY_OBJECT_SCHEMA,
       async execute() {
-        const capabilities = await bridgeAdapter.getCapabilities();
+        const [capabilities, sidecarStatus, uiHelperStatus] = await Promise.all([
+          bridgeAdapter.getCapabilities(),
+          sidecarAdapter.getStatus(),
+          uiAutomationAdapter.getStatus()
+        ]);
         return {
           summary: "Capabilities loaded.",
           affected_objects: ["bridge", "server"],
           state_version_before: null,
           state_version_after: null,
           warnings: [],
-          next_suggested_actions: ["get_project_summary"],
-          capabilities
+          next_suggested_actions: ["get_project_summary", "get_component_status"],
+          capabilities: {
+            ...capabilities,
+            optional_components: {
+              sidecar: sidecarStatus,
+              ui_helper: uiHelperStatus
+            }
+          }
         };
       }
     }

package/packages/mcp-server/src/index.js

@@ -8,3 +8,7 @@ export {
   createBridgeAdapter,
   createStateAdapter
 } from "./session.js";
+export {
+  createSidecarAdapter,
+  createUiAutomationAdapter
+} from "./optional-adapters.js";

package/packages/mcp-server/src/optional-adapters.js

@@ -0,0 +1,193 @@
+import { existsSync } from "node:fs";
+
+import {
+  getDefaultSidecarInstallTarget
+} from "../../live-sidecar-m4l/src/project.js";
+import {
+  listWorkflows as listSidecarWorkflows
+} from "../../live-sidecar-m4l/src/workflows.js";
+import { executeWorkflow as executeUiWorkflow } from "../../ui-automation/src/executor.js";
+import { getStableUiHelperInstallPaths } from "../../ui-automation/src/helper.js";
+import { workflows as uiWorkflows } from "../../ui-automation/src/workflows.js";
+
+import { McpServerError } from "./errors.js";
+
+function buildSidecarSetupInstructions(devicePath) {
+  return [
+    "Run `npx laive-mcp install --apply` if the sidecar device is not installed yet.",
+    `Load \`${devicePath}\` onto a MIDI track in the current Ableton Live set.`,
+    "Keep the `laive` Control Surface enabled in Live before retrying the sidecar tool."
+  ];
+}
+
+function buildUiHelperSetupInstructions(appBundleRoot) {
+  return [
+    "Run `npx laive-mcp install --apply` if the UI helper app is not installed yet.",
+    `In macOS System Settings > Privacy & Security > Accessibility, add and enable \`${appBundleRoot}\`.`,
+    "Bring Ableton Live to the foreground before retrying the UI automation tool."
+  ];
+}
+
+function summarizeUiWorkflows() {
+  return Object.values(uiWorkflows).map((workflow) => ({
+    name: workflow.name,
+    description: workflow.description,
+    parameters: workflow.parameters ?? []
+  }));
+}
+
+function createSetupRequiredError(message, data) {
+  return new McpServerError("setup_required", message, data);
+}
+
+function requireConfigured(status, label) {
+  if (!status.configured) {
+    throw createSetupRequiredError(`${label} is not configured`, status);
+  }
+}
+
+function getStatus() {
+  const sidecarTarget = getDefaultSidecarInstallTarget();
+  const uiHelperTarget = getStableUiHelperInstallPaths();
+
+  return {
+    sidecar: {
+      configured: existsSync(sidecarTarget.devicePath),
+      devicePath: sidecarTarget.devicePath,
+      workflows: listSidecarWorkflows(),
+      setup_instructions: buildSidecarSetupInstructions(sidecarTarget.devicePath)
+    },
+    ui_helper: {
+      configured: existsSync(uiHelperTarget.appBundleRoot),
+      appBundleRoot: uiHelperTarget.appBundleRoot,
+      executablePath: uiHelperTarget.executablePath,
+      workflows: summarizeUiWorkflows(),
+      setup_instructions: buildUiHelperSetupInstructions(uiHelperTarget.appBundleRoot)
+    }
+  };
+}
+
+export function createSidecarAdapter({ stateAdapter, bridgeAdapter } = {}) {
+  return {
+    async getStatus() {
+      return getStatus().sidecar;
+    },
+    async listWorkflows() {
+      const status = getStatus();
+      return {
+        ...status.sidecar,
+        workflows: listSidecarWorkflows()
+      };
+    },
+    async snapshotSelectionContext() {
+      const status = getStatus();
+      requireConfigured(status.sidecar, "Max for Live sidecar");
+      if (!stateAdapter) {
+        throw new McpServerError("adapter_unavailable", "state adapter is not configured");
+      }
+      const context = await stateAdapter.getSelectedContext();
+      return {
+        workflow: "snapshotSelectionContext",
+        configured: true,
+        context
+      };
+    },
+    async replaceClipNotes({ clipId, notes, dryRun = false }) {
+      const status = getStatus();
+      requireConfigured(status.sidecar, "Max for Live sidecar");
+      if (!bridgeAdapter) {
+        throw new McpServerError("adapter_unavailable", "bridge adapter is not configured");
+      }
+      return await bridgeAdapter.insertNotes({
+        clipId,
+        notes,
+        dryRun
+      });
+    },
+    async observeDeviceParameters({ trackId } = {}) {
+      const status = getStatus();
+      requireConfigured(status.sidecar, "Max for Live sidecar");
+      if (!stateAdapter) {
+        throw new McpServerError("adapter_unavailable", "state adapter is not configured");
+      }
+      const context = await stateAdapter.getSelectedContext();
+      const resolvedTrackId = trackId ?? context.track?.id;
+      if (!resolvedTrackId) {
+        throw new McpServerError(
+          "invalid_request",
+          "trackId is required when no track is selected in Live"
+        );
+      }
+
+      return {
+        workflow: "observeDeviceParameters",
+        configured: true,
+        mode: "snapshot",
+        warnings: [
+          "Continuous sidecar event streaming is not yet emitted over MCP; returning a current parameter snapshot instead."
+        ],
+        selectedDeviceId: context.device?.id ?? null,
+        deviceTree: await stateAdapter.getDeviceTree(resolvedTrackId)
+      };
+    },
+    async executeWorkflow(name, parameters = {}) {
+      switch (name) {
+        case "snapshotSelectionContext":
+          return await this.snapshotSelectionContext();
+        case "replaceClipNotes":
+          return await this.replaceClipNotes({
+            clipId: parameters.clipId,
+            notes: parameters.notes,
+            dryRun: Boolean(parameters.dryRun)
+          });
+        case "observeDeviceParameters":
+          return await this.observeDeviceParameters({
+            trackId: parameters.trackId
+          });
+        default:
+          throw new McpServerError("invalid_request", `Unknown sidecar workflow: ${name}`);
+      }
+    }
+  };
+}
+
+export function createUiAutomationAdapter() {
+  return {
+    async getStatus() {
+      return getStatus().ui_helper;
+    },
+    async listWorkflows() {
+      const status = getStatus();
+      return {
+        ...status.ui_helper,
+        workflows: summarizeUiWorkflows()
+      };
+    },
+    async executeWorkflow(name, parameters = {}) {
+      const status = getStatus();
+      requireConfigured(status.ui_helper, "UI helper");
+      return {
+        workflow: name,
+        configured: true,
+        helper: {
+          appBundleRoot: status.ui_helper.appBundleRoot,
+          executablePath: status.ui_helper.executablePath
+        },
+        result: await executeUiWorkflow(name, parameters)
+      };
+    }
+  };
+}
+
+export function createIntegrationStatusAdapter({ sidecarAdapter, uiAutomationAdapter } = {}) {
+  return {
+    async getStatus() {
+      return {
+        sidecar: sidecarAdapter ? await sidecarAdapter.getStatus() : getStatus().sidecar,
+        ui_helper: uiAutomationAdapter
+          ? await uiAutomationAdapter.getStatus()
+          : getStatus().ui_helper
+      };
+    }
+  };
+}

package/packages/mcp-server/src/server.js

@@ -2,15 +2,41 @@ import rootPackage from "../../../package.json" with { type: "json" };
 import { ToolRegistry } from "./tool-registry.js";
 import { buildDefaultTools } from "./default-tools.js";
 import { McpServerError, toErrorShape } from "./errors.js";
+import {
+  createIntegrationStatusAdapter,
+  createSidecarAdapter,
+  createUiAutomationAdapter
+} from "./optional-adapters.js";
 
 export class LaiveMcpServer {
-  constructor({ stateAdapter, bridgeAdapter, policyAdapter, serverInfo } = {}) {
+  constructor({
+    stateAdapter,
+    bridgeAdapter,
+    policyAdapter,
+    sidecarAdapter,
+    uiAutomationAdapter,
+    integrationStatusAdapter,
+    serverInfo
+  } = {}) {
     this.serverInfo = serverInfo ?? {
       name: "laive-mcp",
       version: rootPackage.version
     };
     this.stateAdapter = stateAdapter ?? createUnsupportedAdapter("state");
     this.bridgeAdapter = bridgeAdapter ?? createUnsupportedAdapter("bridge");
+    this.sidecarAdapter =
+      sidecarAdapter ??
+      createSidecarAdapter({
+        stateAdapter: this.stateAdapter,
+        bridgeAdapter: this.bridgeAdapter
+      });
+    this.uiAutomationAdapter = uiAutomationAdapter ?? createUiAutomationAdapter();
+    this.integrationStatusAdapter =
+      integrationStatusAdapter ??
+      createIntegrationStatusAdapter({
+        sidecarAdapter: this.sidecarAdapter,
+        uiAutomationAdapter: this.uiAutomationAdapter
+      });
     this.policyAdapter = policyAdapter ?? {
       async assertAllowed() {
         return true;
@@ -21,7 +47,10 @@ export class LaiveMcpServer {
     for (const tool of buildDefaultTools({
       stateAdapter: this.stateAdapter,
       bridgeAdapter: this.bridgeAdapter,
-      policyAdapter: this.policyAdapter
+      policyAdapter: this.policyAdapter,
+      sidecarAdapter: this.sidecarAdapter,
+      uiAutomationAdapter: this.uiAutomationAdapter,
+      integrationStatusAdapter: this.integrationStatusAdapter
     })) {
       this.tools.register(tool);
     }

package/packages/mcp-server/src/session.js

@@ -200,6 +200,40 @@ export function createBridgeAdapter(target) {
         affectedObjects: result.track ? [result.track.id] : []
       };
     },
+    async playTransport(options = {}) {
+      const bridgeClient = await resolveBridgeClient(target);
+      return (
+        await bridgeClient.request("call", "transport.play", {}, {
+          dryRun: Boolean(options.dryRun)
+        })
+      ).result;
+    },
+    async stopTransport(options = {}) {
+      const bridgeClient = await resolveBridgeClient(target);
+      return (
+        await bridgeClient.request("call", "transport.stop", {}, {
+          dryRun: Boolean(options.dryRun)
+        })
+      ).result;
+    },
+    async createScene(name = null, options = {}) {
+      const bridgeClient = await resolveBridgeClient(target);
+      const result = (
+        await bridgeClient.request(
+          "call",
+          "create_scene",
+          {
+            name
+          },
+          { dryRun: Boolean(options.dryRun) }
+        )
+      ).result;
+
+      return {
+        ...result,
+        affectedObjects: result.scene ? [result.scene.id] : ["scenes"]
+      };
+    },
     async createClip(payload) {
       const bridgeClient = await resolveBridgeClient(target);
       const result = (
@@ -221,6 +255,31 @@ export function createBridgeAdapter(target) {
         affectedObjects: result.clip ? [payload.trackId, result.clip.id] : [payload.trackId]
       };
     },
+    async insertNotes(payload, options = {}) {
+      const bridgeClient = await resolveBridgeClient(target);
+      const result = (
+        await bridgeClient.request(
+          "call",
+          "insert_notes",
+          {
+            clip_id: payload.clipId,
+            notes: (payload.notes ?? []).map((note) => ({
+              pitch: note.pitch,
+              start_beats: note.startBeats ?? note.start_beats,
+              duration_beats: note.durationBeats ?? note.duration_beats,
+              velocity: note.velocity,
+              mute: note.mute ?? false
+            }))
+          },
+          { dryRun: Boolean(options.dryRun ?? payload.dryRun) }
+        )
+      ).result;
+
+      return {
+        ...result,
+        affectedObjects: [payload.clipId]
+      };
+    },
     async setParameter(payload, options = {}) {
       const bridgeClient = await resolveBridgeClient(target);
       const result = (

package/scripts/remote_script_tooling.py

@@ -6,6 +6,7 @@ import argparse
 import json
 import shutil
 import sys
+import time
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Iterable, List
@@ -57,6 +58,21 @@ def ensure_source_exists(source_root: Path = REMOTE_SCRIPT_SOURCE) -> Path:
     return source_root
 
 
+def remove_tree(path: Path, attempts: int = 3, delay_seconds: float = 0.05) -> None:
+    last_error = None
+    for _attempt in range(attempts):
+        try:
+            shutil.rmtree(path)
+            return
+        except FileNotFoundError:
+            return
+        except OSError as error:
+            last_error = error
+            time.sleep(delay_seconds)
+    if last_error is not None:
+        raise last_error
+
+
 def stage_remote_script(
     source_root: Path = REMOTE_SCRIPT_SOURCE,
     artifacts_dir: Path = DEFAULT_ARTIFACTS_DIR,
@@ -68,7 +84,7 @@ def stage_remote_script(
     target_dir = staging_root / source_root.name
 
     if target_dir.exists():
-        shutil.rmtree(target_dir)
+        remove_tree(target_dir)
 
     shutil.copytree(source_root, target_dir)
     archive_path = shutil.make_archive(