livepilot 1.0.0

package/mcp_server/tools/clips.py

@@ -0,0 +1,218 @@
+"""Clip MCP tools — info, create, delete, duplicate, fire, stop, properties, warp.
+
+11 tools matching the Remote Script clips domain.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+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):
+    """Validate track index. Must be >= 0 for regular tracks."""
+    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: Optional[float] = None,
+    end: Optional[float] = 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: Optional[int] = 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)
+
+
+_VALID_WARP_MODES = {0, 1, 2, 3, 4, 6}
+
+
+@mcp.tool()
+def set_clip_warp_mode(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    mode: int,
+    warping: Optional[bool] = None,
+) -> dict:
+    """Set warp mode for an audio clip (0=Beats, 1=Tones, 2=Texture, 3=Re-Pitch, 4=Complex, 6=Complex Pro)."""
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
+    if mode not in _VALID_WARP_MODES:
+        raise ValueError("Warp mode must be one of: 0=Beats, 1=Tones, 2=Texture, 3=Re-Pitch, 4=Complex, 6=Complex Pro")
+    params = {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "mode": mode,
+    }
+    if warping is not None:
+        params["warping"] = warping
+    return _get_ableton(ctx).send_command("set_clip_warp_mode", params)

package/mcp_server/tools/devices.py

@@ -0,0 +1,256 @@
+"""Device MCP tools — parameters, racks, browser loading.
+
+12 tools matching the Remote Script devices domain.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+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"]
+
+
+MASTER_TRACK_INDEX = -1000
+
+
+def _validate_track_index(track_index: int):
+    if track_index < 0 and track_index != MASTER_TRACK_INDEX:
+        if track_index < -100:
+            raise ValueError(
+                "track_index must be >= 0 for regular tracks, "
+                "negative for return tracks (-1=A, -2=B), or -1000 for master"
+            )
+        # Negative values -1..-99 are valid return track indices
+
+
+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.
+    track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master."""
+    _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.
+    track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master."""
+    _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: Optional[str] = None,
+    parameter_index: Optional[int] = None,
+) -> dict:
+    """Set a device parameter by name or index.
+    track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master."""
+    _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: list,
+) -> dict:
+    """Set multiple device parameters in one call. parameters is a list of objects: [{"name_or_index": "Dry/Wet", "value": 0.5}, ...].
+    track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master."""
+    _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.
+    track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master."""
+    _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.
+    track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master."""
+    _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.
+    track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master."""
+    _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.
+    track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master."""
+    _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: Optional[int] = None,
+    sensitivity: Optional[float] = 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: Optional[float] = None,
+    pan: Optional[float] = 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/memory.py

@@ -0,0 +1,198 @@
+"""Memory MCP tools — technique library for saving, recalling, and replaying patterns.
+
+8 tools for the agent's long-term memory system.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastmcp import Context
+
+from ..server import mcp
+from ..memory.technique_store import TechniqueStore
+
+_store = TechniqueStore()
+
+
+def _get_store() -> TechniqueStore:
+    return _store
+
+
+@mcp.tool()
+def memory_learn(
+    ctx: Context,
+    name: str,
+    type: str,
+    qualities: dict,
+    payload: dict,
+    tags: Optional[list] = None,
+) -> dict:
+    """Save a new technique to the memory library with stylistic qualities. type must be one of: beat_pattern, device_chain, mix_template, browser_pin, preference. qualities must include at minimum a 'summary' field."""
+    return _get_store().save(name=name, type=type, qualities=qualities, payload=payload, tags=tags)
+
+
+@mcp.tool()
+def memory_recall(
+    ctx: Context,
+    query: Optional[str] = None,
+    type: Optional[str] = None,
+    tags: Optional[list] = None,
+    limit: int = 10,
+) -> dict:
+    """Search the technique library by text query and/or filters. Returns summaries (no payload)."""
+    results = _get_store().search(query=query, type_filter=type, tags=tags, limit=limit)
+    return {"count": len(results), "techniques": results}
+
+
+@mcp.tool()
+def memory_get(ctx: Context, technique_id: str) -> dict:
+    """Fetch a full technique by ID, including payload for replay."""
+    return _get_store().get(technique_id)
+
+
+@mcp.tool()
+def memory_replay(ctx: Context, technique_id: str, adapt: bool = False) -> dict:
+    """Retrieve a technique with a replay plan for the agent to execute. adapt=false: returns step-by-step replay plan for exact reconstruction. adapt=true: returns technique for creative adaptation."""
+    store = _get_store()
+    technique = store.get(technique_id)
+    store.increment_replay(technique_id)
+
+    mode = "adapt" if adapt else "exact"
+
+    if adapt:
+        steps = [
+            "Read qualities and payload as inspiration",
+            "Create something new that matches the stylistic palette",
+        ]
+    else:
+        steps = _generate_replay_steps(technique)
+
+    return {
+        "technique": technique,
+        "replay_plan": {
+            "mode": mode,
+            "type": technique["type"],
+            "steps": steps,
+        },
+    }
+
+
+def _generate_replay_steps(technique: dict) -> list[str]:
+    """Generate human-readable replay steps based on technique type."""
+    t_type = technique["type"]
+    payload = technique.get("payload", {})
+
+    if t_type == "beat_pattern":
+        steps = []
+        kit = payload.get("kit_name")
+        if kit:
+            steps.append(f"Load kit '{kit}' using search_browser + load_browser_item")
+        steps.append(
+            f"Create a MIDI clip using create_clip "
+            f"(length={payload.get('clip_length', 4)} beats)"
+        )
+        notes = payload.get("notes", [])
+        if notes:
+            steps.append(f"Add {len(notes)} notes using add_notes with the stored note data")
+        tempo = payload.get("tempo")
+        if tempo:
+            steps.append(f"Set tempo to {tempo} BPM using set_tempo")
+        return steps or ["Replay the beat pattern from the stored payload"]
+
+    elif t_type == "device_chain":
+        steps = []
+        devices = payload.get("devices", [])
+        for i, dev in enumerate(devices):
+            dev_name = dev.get("name", f"device {i + 1}")
+            steps.append(f"Load '{dev_name}' using find_and_load_device")
+            params = dev.get("params", {})
+            if params:
+                steps.append(
+                    f"Set {len(params)} parameters on '{dev_name}' using batch_set_parameters"
+                )
+        return steps or ["Load the device chain from the stored payload"]
+
+    elif t_type == "mix_template":
+        steps = []
+        returns = payload.get("returns", [])
+        if returns:
+            steps.append(
+                f"Create {len(returns)} return tracks using create_return_track"
+            )
+            for ret in returns:
+                devices = ret.get("devices", [])
+                for dev in devices:
+                    dev_name = dev if isinstance(dev, str) else dev.get("name", "device")
+                    steps.append(
+                        f"Load '{dev_name}' on return track using find_and_load_device"
+                    )
+        sends = payload.get("sends_pattern", {})
+        if sends:
+            steps.append(
+                "Apply send levels from sends_pattern "
+                "(note: role names must be resolved to track indices by the agent)"
+            )
+        return steps or ["Apply the mix template from the stored payload"]
+
+    elif t_type == "browser_pin":
+        uri = payload.get("uri", "")
+        name = payload.get("name", "item")
+        steps = [f"Load browser item '{name}' by URI '{uri}' using load_browser_item"]
+        return steps
+
+    elif t_type == "preference":
+        key = payload.get("key", "preference")
+        value = payload.get("value", "")
+        steps = [f"Apply preference '{key}' = '{value}'"]
+        return steps
+
+    return ["Replay the technique from the stored payload"]
+
+
+@mcp.tool()
+def memory_list(
+    ctx: Context,
+    type: Optional[str] = None,
+    tags: Optional[list] = None,
+    sort_by: str = "updated_at",
+    limit: int = 20,
+) -> dict:
+    """Browse the technique library with optional filtering."""
+    results = _get_store().list_techniques(
+        type_filter=type, tags=tags, sort_by=sort_by, limit=limit
+    )
+    return {"count": len(results), "techniques": results}
+
+
+@mcp.tool()
+def memory_favorite(
+    ctx: Context,
+    technique_id: str,
+    favorite: Optional[bool] = None,
+    rating: Optional[int] = None,
+) -> dict:
+    """Star and/or rate a technique (rating 0-5)."""
+    return _get_store().favorite(
+        technique_id=technique_id, favorite=favorite, rating=rating
+    )
+
+
+@mcp.tool()
+def memory_update(
+    ctx: Context,
+    technique_id: str,
+    name: Optional[str] = None,
+    tags: Optional[list] = None,
+    qualities: Optional[dict] = None,
+) -> dict:
+    """Update name, tags, or qualities on an existing technique. Qualities are merged (lists replace)."""
+    return _get_store().update(
+        technique_id=technique_id, name=name, tags=tags, qualities=qualities
+    )
+
+
+@mcp.tool()
+def memory_delete(ctx: Context, technique_id: str) -> dict:
+    """Delete a technique from the library (creates backup first)."""
+    return _get_store().delete(technique_id)