livepilot 1.1.0

package/mcp_server/tools/browser.py

@@ -0,0 +1,78 @@
+"""Browser MCP tools — browse, search, and load instruments/effects.
+
+4 tools matching the Remote Script browser domain.
+"""
+
+from fastmcp import Context
+
+from ..server import mcp
+
+
+def _get_ableton(ctx: Context):
+    """Extract AbletonConnection from lifespan context."""
+    return ctx.lifespan_context["ableton"]
+
+
+def _validate_track_index(track_index: int):
+    if track_index < 0:
+        raise ValueError("track_index must be >= 0")
+
+
+@mcp.tool()
+def get_browser_tree(ctx: Context, category_type: str = "all") -> dict:
+    """Get an overview of browser categories and their children."""
+    return _get_ableton(ctx).send_command("get_browser_tree", {
+        "category_type": category_type,
+    })
+
+
+@mcp.tool()
+def get_browser_items(ctx: Context, path: str) -> dict:
+    """List items at a browser path (e.g., 'instruments/Analog')."""
+    if not path.strip():
+        raise ValueError("Path cannot be empty")
+    return _get_ableton(ctx).send_command("get_browser_items", {"path": path})
+
+
+@mcp.tool()
+def search_browser(
+    ctx: Context,
+    path: str,
+    name_filter: str | None = None,
+    loadable_only: bool = False,
+    max_depth: int = 8,
+    max_results: int = 100,
+) -> dict:
+    """Search the browser tree under a path, optionally filtering by name.
+
+    max_depth:   how deep to recurse into subfolders (default 8)
+    max_results: maximum number of results to return (default 100)
+    """
+    if not path.strip():
+        raise ValueError("Path cannot be empty")
+    if max_depth < 1:
+        raise ValueError("max_depth must be >= 1")
+    if max_results < 1:
+        raise ValueError("max_results must be >= 1")
+    params: dict = {"path": path}
+    if name_filter is not None:
+        params["name_filter"] = name_filter
+    if loadable_only:
+        params["loadable_only"] = loadable_only
+    if max_depth != 8:
+        params["max_depth"] = max_depth
+    if max_results != 100:
+        params["max_results"] = max_results
+    return _get_ableton(ctx).send_command("search_browser", params)
+
+
+@mcp.tool()
+def load_browser_item(ctx: Context, track_index: int, uri: str) -> dict:
+    """Load a browser item (instrument/effect) onto a track by URI."""
+    _validate_track_index(track_index)
+    if not uri.strip():
+        raise ValueError("URI cannot be empty")
+    return _get_ableton(ctx).send_command("load_browser_item", {
+        "track_index": track_index,
+        "uri": uri,
+    })

package/mcp_server/tools/clips.py

@@ -0,0 +1,187 @@
+"""Clip MCP tools — info, create, delete, duplicate, fire, stop, properties.
+
+10 tools matching the Remote Script clips domain.
+"""
+
+from fastmcp import Context
+
+from ..server import mcp
+
+
+def _get_ableton(ctx: Context):
+    """Extract AbletonConnection from lifespan context."""
+    return ctx.lifespan_context["ableton"]
+
+
+def _validate_track_index(track_index: int):
+    if track_index < 0:
+        raise ValueError("track_index must be >= 0")
+
+
+def _validate_clip_index(clip_index: int):
+    if clip_index < 0:
+        raise ValueError("clip_index must be >= 0")
+
+
+def _validate_color_index(color_index: int):
+    if not 0 <= color_index <= 69:
+        raise ValueError("color_index must be between 0 and 69")
+
+
+@mcp.tool()
+def get_clip_info(ctx: Context, track_index: int, clip_index: int) -> dict:
+    """Get detailed info about a clip: name, length, loop, launch settings."""
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
+    return _get_ableton(ctx).send_command("get_clip_info", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+    })
+
+
+@mcp.tool()
+def create_clip(ctx: Context, track_index: int, clip_index: int, length: float) -> dict:
+    """Create an empty MIDI clip in a clip slot (length in beats)."""
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
+    if length <= 0:
+        raise ValueError("length must be > 0")
+    return _get_ableton(ctx).send_command("create_clip", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "length": length,
+    })
+
+
+@mcp.tool()
+def delete_clip(ctx: Context, track_index: int, clip_index: int) -> dict:
+    """Delete a clip from a clip slot. This removes all notes and automation. Use undo to revert."""
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
+    return _get_ableton(ctx).send_command("delete_clip", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+    })
+
+
+@mcp.tool()
+def duplicate_clip(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    target_track: int,
+    target_clip: int,
+) -> dict:
+    """Duplicate a clip from one slot to another."""
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
+    _validate_track_index(target_track)
+    _validate_clip_index(target_clip)
+    return _get_ableton(ctx).send_command("duplicate_clip", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "target_track": target_track,
+        "target_clip": target_clip,
+    })
+
+
+@mcp.tool()
+def fire_clip(ctx: Context, track_index: int, clip_index: int) -> dict:
+    """Launch/fire a clip slot."""
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
+    return _get_ableton(ctx).send_command("fire_clip", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+    })
+
+
+@mcp.tool()
+def stop_clip(ctx: Context, track_index: int, clip_index: int) -> dict:
+    """Stop a playing clip."""
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
+    return _get_ableton(ctx).send_command("stop_clip", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+    })
+
+
+@mcp.tool()
+def set_clip_name(ctx: Context, track_index: int, clip_index: int, name: str) -> dict:
+    """Rename a clip."""
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
+    if not name.strip():
+        raise ValueError("Clip name cannot be empty")
+    return _get_ableton(ctx).send_command("set_clip_name", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "name": name,
+    })
+
+
+@mcp.tool()
+def set_clip_color(ctx: Context, track_index: int, clip_index: int, color_index: int) -> dict:
+    """Set clip color (0-69, Ableton's color palette)."""
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
+    _validate_color_index(color_index)
+    return _get_ableton(ctx).send_command("set_clip_color", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "color_index": color_index,
+    })
+
+
+@mcp.tool()
+def set_clip_loop(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    enabled: bool,
+    start: float | None = None,
+    end: float | None = None,
+) -> dict:
+    """Enable/disable clip looping and optionally set loop start/end (in beats)."""
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
+    params = {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "enabled": enabled,
+    }
+    if start is not None:
+        if start < 0:
+            raise ValueError("Loop start must be >= 0")
+        params["start"] = start
+    if end is not None:
+        if end <= 0:
+            raise ValueError("Loop end must be > 0")
+        params["end"] = end
+    if start is not None and end is not None and start >= end:
+        raise ValueError("Loop start must be less than loop end")
+    return _get_ableton(ctx).send_command("set_clip_loop", params)
+
+
+@mcp.tool()
+def set_clip_launch(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    mode: int,
+    quantization: int | None = None,
+) -> dict:
+    """Set clip launch mode (0=Trigger, 1=Gate, 2=Toggle, 3=Repeat) and optional quantization."""
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
+    if not 0 <= mode <= 3:
+        raise ValueError("Launch mode must be 0-3 (Trigger, Gate, Toggle, Repeat)")
+    params = {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "mode": mode,
+    }
+    if quantization is not None:
+        params["quantization"] = quantization
+    return _get_ableton(ctx).send_command("set_clip_launch", params)

package/mcp_server/tools/devices.py

@@ -0,0 +1,238 @@
+"""Device MCP tools — parameters, racks, browser loading.
+
+12 tools matching the Remote Script devices domain.
+"""
+
+import json
+from typing import Any
+
+from fastmcp import Context
+
+from ..server import mcp
+
+
+def _ensure_list(value: Any) -> list:
+    """Parse JSON strings into lists. MCP clients may serialize list params as strings."""
+    if isinstance(value, str):
+        return json.loads(value)
+    return value
+
+
+def _get_ableton(ctx: Context):
+    """Extract AbletonConnection from lifespan context."""
+    return ctx.lifespan_context["ableton"]
+
+
+def _validate_track_index(track_index: int):
+    if track_index < 0:
+        raise ValueError("track_index must be >= 0")
+
+
+def _validate_device_index(device_index: int):
+    if device_index < 0:
+        raise ValueError("device_index must be >= 0")
+
+
+def _validate_chain_index(chain_index: int):
+    if chain_index < 0:
+        raise ValueError("chain_index must be >= 0")
+
+
+@mcp.tool()
+def get_device_info(ctx: Context, track_index: int, device_index: int) -> dict:
+    """Get info about a device: name, class, type, active state, parameter count."""
+    _validate_track_index(track_index)
+    _validate_device_index(device_index)
+    return _get_ableton(ctx).send_command("get_device_info", {
+        "track_index": track_index,
+        "device_index": device_index,
+    })
+
+
+@mcp.tool()
+def get_device_parameters(ctx: Context, track_index: int, device_index: int) -> dict:
+    """Get all parameters for a device with names, values, and ranges."""
+    _validate_track_index(track_index)
+    _validate_device_index(device_index)
+    return _get_ableton(ctx).send_command("get_device_parameters", {
+        "track_index": track_index,
+        "device_index": device_index,
+    })
+
+
+@mcp.tool()
+def set_device_parameter(
+    ctx: Context,
+    track_index: int,
+    device_index: int,
+    value: float,
+    parameter_name: str | None = None,
+    parameter_index: int | None = None,
+) -> dict:
+    """Set a device parameter by name or index."""
+    _validate_track_index(track_index)
+    _validate_device_index(device_index)
+    if parameter_name is None and parameter_index is None:
+        raise ValueError("Must provide parameter_name or parameter_index")
+    if parameter_index is not None and parameter_index < 0:
+        raise ValueError("parameter_index must be >= 0")
+    params = {
+        "track_index": track_index,
+        "device_index": device_index,
+        "value": value,
+    }
+    if parameter_name is not None:
+        params["parameter_name"] = parameter_name
+    if parameter_index is not None:
+        params["parameter_index"] = parameter_index
+    return _get_ableton(ctx).send_command("set_device_parameter", params)
+
+
+@mcp.tool()
+def batch_set_parameters(
+    ctx: Context,
+    track_index: int,
+    device_index: int,
+    parameters: Any,
+) -> dict:
+    """Set multiple device parameters in one call. parameters is a JSON array: [{name_or_index, value}]."""
+    _validate_track_index(track_index)
+    _validate_device_index(device_index)
+    parameters = _ensure_list(parameters)
+    if not parameters:
+        raise ValueError("parameters list cannot be empty")
+    for entry in parameters:
+        if "name_or_index" not in entry or "value" not in entry:
+            raise ValueError("Each parameter must have 'name_or_index' and 'value'")
+    return _get_ableton(ctx).send_command("batch_set_parameters", {
+        "track_index": track_index,
+        "device_index": device_index,
+        "parameters": parameters,
+    })
+
+
+@mcp.tool()
+def toggle_device(ctx: Context, track_index: int, device_index: int, active: bool) -> dict:
+    """Enable or disable a device."""
+    _validate_track_index(track_index)
+    _validate_device_index(device_index)
+    return _get_ableton(ctx).send_command("toggle_device", {
+        "track_index": track_index,
+        "device_index": device_index,
+        "active": active,
+    })
+
+
+@mcp.tool()
+def delete_device(ctx: Context, track_index: int, device_index: int) -> dict:
+    """Delete a device from a track. Use undo to revert if needed."""
+    _validate_track_index(track_index)
+    _validate_device_index(device_index)
+    return _get_ableton(ctx).send_command("delete_device", {
+        "track_index": track_index,
+        "device_index": device_index,
+    })
+
+
+@mcp.tool()
+def load_device_by_uri(ctx: Context, track_index: int, uri: str) -> dict:
+    """Load a device onto a track using a browser URI string."""
+    _validate_track_index(track_index)
+    if not uri.strip():
+        raise ValueError("URI cannot be empty")
+    return _get_ableton(ctx).send_command("load_device_by_uri", {
+        "track_index": track_index,
+        "uri": uri,
+    })
+
+
+@mcp.tool()
+def find_and_load_device(ctx: Context, track_index: int, device_name: str) -> dict:
+    """Search the browser for a device by name and load it onto a track."""
+    _validate_track_index(track_index)
+    if not device_name.strip():
+        raise ValueError("device_name cannot be empty")
+    return _get_ableton(ctx).send_command("find_and_load_device", {
+        "track_index": track_index,
+        "device_name": device_name,
+    })
+
+
+@mcp.tool()
+def set_simpler_playback_mode(
+    ctx: Context,
+    track_index: int,
+    device_index: int,
+    playback_mode: int,
+    slice_by: int | None = None,
+    sensitivity: float | None = None,
+) -> dict:
+    """Set Simpler's playback mode. playback_mode: 0=Classic, 1=One-Shot, 2=Slice. slice_by (Slice only): 0=Transient, 1=Beat, 2=Region, 3=Manual. sensitivity (0.0-1.0, Transient only)."""
+    _validate_track_index(track_index)
+    _validate_device_index(device_index)
+    if playback_mode not in (0, 1, 2):
+        raise ValueError("playback_mode must be 0 (Classic), 1 (One-Shot), or 2 (Slice)")
+    params = {
+        "track_index": track_index,
+        "device_index": device_index,
+        "playback_mode": playback_mode,
+    }
+    if slice_by is not None:
+        params["slice_by"] = slice_by
+    if sensitivity is not None:
+        params["sensitivity"] = sensitivity
+    return _get_ableton(ctx).send_command("set_simpler_playback_mode", params)
+
+
+@mcp.tool()
+def get_rack_chains(ctx: Context, track_index: int, device_index: int) -> dict:
+    """Get all chains in a rack device with volume, pan, mute, solo."""
+    _validate_track_index(track_index)
+    _validate_device_index(device_index)
+    return _get_ableton(ctx).send_command("get_rack_chains", {
+        "track_index": track_index,
+        "device_index": device_index,
+    })
+
+
+@mcp.tool()
+def set_chain_volume(
+    ctx: Context,
+    track_index: int,
+    device_index: int,
+    chain_index: int,
+    volume: float | None = None,
+    pan: float | None = None,
+) -> dict:
+    """Set volume and/or pan for a chain in a rack device."""
+    _validate_track_index(track_index)
+    _validate_device_index(device_index)
+    _validate_chain_index(chain_index)
+    if volume is not None and not 0.0 <= volume <= 1.0:
+        raise ValueError("volume must be between 0.0 and 1.0")
+    if pan is not None and not -1.0 <= pan <= 1.0:
+        raise ValueError("pan must be between -1.0 and 1.0")
+    if volume is None and pan is None:
+        raise ValueError("Must provide volume and/or pan")
+    params = {
+        "track_index": track_index,
+        "device_index": device_index,
+        "chain_index": chain_index,
+    }
+    if volume is not None:
+        params["volume"] = volume
+    if pan is not None:
+        params["pan"] = pan
+    return _get_ableton(ctx).send_command("set_chain_volume", params)
+
+
+@mcp.tool()
+def get_device_presets(ctx: Context, device_name: str) -> dict:
+    """List available presets for an Ableton device (e.g. 'Corpus', 'Drum Buss', 'Wavetable').
+    Searches audio_effects, instruments, and midi_effects categories.
+    Returns preset names and URIs that can be loaded with load_device_by_uri."""
+    if not device_name.strip():
+        raise ValueError("device_name cannot be empty")
+    return _get_ableton(ctx).send_command("get_device_presets", {
+        "device_name": device_name,
+    })

package/mcp_server/tools/mixing.py

@@ -0,0 +1,113 @@
+"""Mixing MCP tools — volume, pan, sends, routing, master.
+
+8 tools matching the Remote Script mixing domain.
+"""
+
+from fastmcp import Context
+
+from ..server import mcp
+
+
+def _get_ableton(ctx: Context):
+    """Extract AbletonConnection from lifespan context."""
+    return ctx.lifespan_context["ableton"]
+
+
+def _validate_track_index(track_index: int):
+    if track_index < 0:
+        raise ValueError("track_index must be >= 0")
+
+
+@mcp.tool()
+def set_track_volume(ctx: Context, track_index: int, volume: float) -> dict:
+    """Set a track's volume (0.0-1.0)."""
+    _validate_track_index(track_index)
+    if not 0.0 <= volume <= 1.0:
+        raise ValueError("Volume must be between 0.0 and 1.0")
+    return _get_ableton(ctx).send_command("set_track_volume", {
+        "track_index": track_index,
+        "volume": volume,
+    })
+
+
+@mcp.tool()
+def set_track_pan(ctx: Context, track_index: int, pan: float) -> dict:
+    """Set a track's panning (-1.0 left to 1.0 right)."""
+    _validate_track_index(track_index)
+    if not -1.0 <= pan <= 1.0:
+        raise ValueError("Pan must be between -1.0 and 1.0")
+    return _get_ableton(ctx).send_command("set_track_pan", {
+        "track_index": track_index,
+        "pan": pan,
+    })
+
+
+@mcp.tool()
+def set_track_send(
+    ctx: Context, track_index: int, send_index: int, value: float
+) -> dict:
+    """Set a send level on a track (0.0-1.0)."""
+    _validate_track_index(track_index)
+    if send_index < 0:
+        raise ValueError("send_index must be >= 0")
+    if not 0.0 <= value <= 1.0:
+        raise ValueError("Send value must be between 0.0 and 1.0")
+    return _get_ableton(ctx).send_command("set_track_send", {
+        "track_index": track_index,
+        "send_index": send_index,
+        "value": value,
+    })
+
+
+@mcp.tool()
+def get_return_tracks(ctx: Context) -> dict:
+    """Get info about all return tracks: name, volume, panning."""
+    return _get_ableton(ctx).send_command("get_return_tracks")
+
+
+@mcp.tool()
+def get_master_track(ctx: Context) -> dict:
+    """Get master track info: volume, panning, devices."""
+    return _get_ableton(ctx).send_command("get_master_track")
+
+
+@mcp.tool()
+def set_master_volume(ctx: Context, volume: float) -> dict:
+    """Set the master track volume (0.0-1.0)."""
+    if not 0.0 <= volume <= 1.0:
+        raise ValueError("Volume must be between 0.0 and 1.0")
+    return _get_ableton(ctx).send_command("set_master_volume", {"volume": volume})
+
+
+@mcp.tool()
+def get_track_routing(ctx: Context, track_index: int) -> dict:
+    """Get input/output routing info for a track."""
+    _validate_track_index(track_index)
+    return _get_ableton(ctx).send_command("get_track_routing", {
+        "track_index": track_index,
+    })
+
+
+@mcp.tool()
+def set_track_routing(
+    ctx: Context,
+    track_index: int,
+    input_type: str | None = None,
+    input_channel: str | None = None,
+    output_type: str | None = None,
+    output_channel: str | None = None,
+) -> dict:
+    """Set input/output routing for a track by display name."""
+    _validate_track_index(track_index)
+    params = {"track_index": track_index}
+    if input_type is not None:
+        params["input_type"] = input_type
+    if input_channel is not None:
+        params["input_channel"] = input_channel
+    if output_type is not None:
+        params["output_type"] = output_type
+    if output_channel is not None:
+        params["output_channel"] = output_channel
+    if len(params) == 1:
+        raise ValueError("At least one routing parameter must be provided")
+    return _get_ableton(ctx).send_command("set_track_routing", params)