livepilot 1.1.0

package/mcp_server/connection.py

@@ -0,0 +1,207 @@
+"""TCP client for communicating with Ableton Live's Remote Script."""
+
+import json
+import os
+import socket
+import time
+import uuid
+from collections import deque
+
+CONNECT_TIMEOUT = 5
+RECV_TIMEOUT = 20
+
+
+class AbletonConnectionError(Exception):
+    """Raised when communication with Ableton Live fails."""
+    pass
+
+
+# Error messages with user-friendly context
+_ERROR_HINTS = {
+    "INDEX_ERROR": "Check that the track, clip, device, or scene index exists. "
+                   "Use get_session_info to see current indices.",
+    "NOT_FOUND": "The requested item could not be found in the Live session. "
+                 "Verify names and indices with get_session_info or get_track_info.",
+    "INVALID_PARAM": "A parameter value was out of range or the wrong type. "
+                     "Use get_device_parameters to check valid ranges.",
+    "STATE_ERROR": "The operation isn't valid in the current state. "
+                   "For example, you can't add notes to a clip that doesn't exist yet.",
+    "TIMEOUT": "Ableton took too long to respond. This can happen with heavy sessions. "
+               "Try again, or check if Ableton is unresponsive.",
+}
+
+
+def _friendly_error(code: str, message: str, command_type: str) -> str:
+    """Format an error from the Remote Script into a user-friendly message."""
+    hint = _ERROR_HINTS.get(code, "")
+    parts = [f"[{code}] {message}"]
+    if hint:
+        parts.append(hint)
+    return " ".join(parts)
+
+
+class AbletonConnection:
+    """TCP client that sends JSON commands to the LivePilot Remote Script."""
+
+    MAX_LOG_ENTRIES = 50
+
+    def __init__(self, host: str | None = None, port: int | None = None):
+        self.host = host or os.environ.get("LIVE_MCP_HOST", "127.0.0.1")
+        self.port = port or int(os.environ.get("LIVE_MCP_PORT", "9878"))
+        self._socket: socket.socket | None = None
+        self._recv_buf: bytes = b""
+        self._command_log: deque[dict] = deque(maxlen=self.MAX_LOG_ENTRIES)
+
+    # ------------------------------------------------------------------
+    # Connection lifecycle
+    # ------------------------------------------------------------------
+
+    def connect(self) -> None:
+        """Open a TCP connection to the Remote Script."""
+        try:
+            sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            sock.settimeout(CONNECT_TIMEOUT)
+            sock.connect((self.host, self.port))
+            sock.settimeout(RECV_TIMEOUT)
+            self._socket = sock
+        except ConnectionRefusedError:
+            self._socket = None
+            raise AbletonConnectionError(
+                f"Cannot reach Ableton Live on {self.host}:{self.port}. "
+                "Make sure Ableton Live is running and the LivePilot Remote Script "
+                "is enabled in Preferences > Link, Tempo & MIDI > Control Surface. "
+                "Run 'npx livepilot --doctor' for a full diagnostic."
+            )
+        except OSError as exc:
+            self._socket = None
+            raise AbletonConnectionError(
+                f"Could not connect to Ableton Live at {self.host}:{self.port} — {exc}"
+            ) from exc
+
+    def disconnect(self) -> None:
+        """Close the TCP connection."""
+        if self._socket is not None:
+            try:
+                self._socket.close()
+            except OSError:
+                pass
+            self._socket = None
+
+    def is_connected(self) -> bool:
+        """Return True if a socket is currently held."""
+        return self._socket is not None
+
+    # ------------------------------------------------------------------
+    # High-level API
+    # ------------------------------------------------------------------
+
+    def ping(self) -> bool:
+        """Send a ping and return True if a pong is received."""
+        try:
+            resp = self._send_raw({"type": "ping"})
+            return resp.get("result", {}).get("pong") is True
+        except Exception:
+            return False
+
+    def send_command(self, command_type: str, params: dict | None = None) -> dict:
+        """Send a command to Ableton and return the result dict.
+
+        Retries once on socket errors with a fresh connection.
+        """
+        # Ensure we have a connection
+        if not self.is_connected():
+            self.connect()
+
+        command: dict = {"type": command_type}
+        if params:
+            command["params"] = params
+
+        try:
+            response = self._send_raw(command)
+        except (OSError, AbletonConnectionError):
+            # Retry once with a fresh connection
+            self.disconnect()
+            self.connect()
+            response = self._send_raw(command)
+
+        # Log the command and response
+        log_entry = {
+            "command": command_type,
+            "params": params,
+            "timestamp": time.time(),
+            "ok": response.get("ok", True),
+        }
+
+        # Handle error responses — Remote Script uses {"ok": false, "error": {"code": ..., "message": ...}}
+        if response.get("ok") is False:
+            err = response.get("error", {})
+            code = err.get("code", "INTERNAL") if isinstance(err, dict) else "INTERNAL"
+            message = err.get("message", str(err)) if isinstance(err, dict) else str(err)
+            log_entry["error"] = code
+            self._command_log.append(log_entry)
+            friendly = _friendly_error(code, message, command_type)
+            raise AbletonConnectionError(friendly)
+
+        self._command_log.append(log_entry)
+        return response.get("result", {})
+
+    # ------------------------------------------------------------------
+    # Command log
+    # ------------------------------------------------------------------
+
+    def get_recent_commands(self, limit: int = 20) -> list[dict]:
+        """Return the most recent commands sent to Ableton (newest first)."""
+        entries = list(self._command_log)
+        entries.reverse()
+        return entries[:limit]
+
+    # ------------------------------------------------------------------
+    # Low-level transport
+    # ------------------------------------------------------------------
+
+    def _send_raw(self, command: dict) -> dict:
+        """Send a JSON command (with request_id) and read the response."""
+        if self._socket is None:
+            raise AbletonConnectionError("Not connected to Ableton Live")
+
+        # Don't mutate the caller's dict
+        envelope = {**command, "id": str(uuid.uuid4())[:8]}
+        payload = json.dumps(envelope) + "\n"
+
+        try:
+            self._socket.sendall(payload.encode("utf-8"))
+        except OSError as exc:
+            self.disconnect()
+            raise AbletonConnectionError(f"Failed to send command: {exc}") from exc
+
+        # Read until newline, preserving any trailing bytes in _recv_buf
+        buf = getattr(self, "_recv_buf", b"")
+        try:
+            while b"\n" not in buf:
+                chunk = self._socket.recv(4096)
+                if not chunk:
+                    self._recv_buf = b""
+                    self.disconnect()
+                    raise AbletonConnectionError("Connection closed by Ableton")
+                buf += chunk
+        except socket.timeout as exc:
+            self._recv_buf = buf
+            self.disconnect()
+            raise AbletonConnectionError(
+                f"Timeout waiting for response from Ableton ({RECV_TIMEOUT}s)"
+            ) from exc
+        except OSError as exc:
+            self._recv_buf = b""
+            self.disconnect()
+            raise AbletonConnectionError(
+                f"Socket error reading response: {exc}"
+            ) from exc
+
+        line, remainder = buf.split(b"\n", 1)
+        self._recv_buf = remainder
+        try:
+            return json.loads(line)
+        except json.JSONDecodeError as exc:
+            raise AbletonConnectionError(
+                f"Invalid JSON from Ableton: {line[:200]}"
+            ) from exc

package/mcp_server/server.py

@@ -0,0 +1,40 @@
+"""FastMCP entry point for LivePilot."""
+
+from contextlib import asynccontextmanager
+
+from fastmcp import FastMCP, Context  # noqa: F401
+
+from .connection import AbletonConnection
+
+
+@asynccontextmanager
+async def lifespan(server):
+    """Create and yield the shared AbletonConnection for all tools."""
+    ableton = AbletonConnection()
+    try:
+        yield {"ableton": ableton}
+    finally:
+        ableton.disconnect()
+
+
+mcp = FastMCP("LivePilot", lifespan=lifespan)
+
+# Import tool modules so they register with `mcp`
+from .tools import transport    # noqa: F401, E402
+from .tools import tracks       # noqa: F401, E402
+from .tools import clips        # noqa: F401, E402
+from .tools import notes        # noqa: F401, E402
+from .tools import devices      # noqa: F401, E402
+from .tools import scenes       # noqa: F401, E402
+from .tools import mixing       # noqa: F401, E402
+from .tools import browser      # noqa: F401, E402
+from .tools import arrangement  # noqa: F401, E402
+
+
+def main():
+    """Run the MCP server over stdio."""
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

package/mcp_server/tools/__init__.py

@@ -0,0 +1 @@
+"""MCP tool modules for LivePilot."""

package/mcp_server/tools/arrangement.py

@@ -0,0 +1,399 @@
+"""Arrangement MCP tools — clips, recording, cue points, navigation.
+
+19 tools matching the Remote Script arrangement domain.
+"""
+
+import json as _json
+
+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")
+
+
+@mcp.tool()
+def get_arrangement_clips(ctx: Context, track_index: int) -> dict:
+    """Get all arrangement clips on a track."""
+    _validate_track_index(track_index)
+    return _get_ableton(ctx).send_command("get_arrangement_clips", {
+        "track_index": track_index,
+    })
+
+
+@mcp.tool()
+def jump_to_time(ctx: Context, beat_time: float) -> dict:
+    """Jump to a specific beat time in the arrangement."""
+    if beat_time < 0:
+        raise ValueError("beat_time must be >= 0")
+    return _get_ableton(ctx).send_command("jump_to_time", {"beat_time": beat_time})
+
+
+@mcp.tool()
+def capture_midi(ctx: Context) -> dict:
+    """Capture recently played MIDI notes into a new clip."""
+    return _get_ableton(ctx).send_command("capture_midi")
+
+
+@mcp.tool()
+def start_recording(ctx: Context, arrangement: bool = False) -> dict:
+    """Start recording. arrangement=True for arrangement, False for session."""
+    return _get_ableton(ctx).send_command("start_recording", {
+        "arrangement": arrangement,
+    })
+
+
+@mcp.tool()
+def stop_recording(ctx: Context) -> dict:
+    """Stop all recording (both session and arrangement)."""
+    return _get_ableton(ctx).send_command("stop_recording")
+
+
+@mcp.tool()
+def get_cue_points(ctx: Context) -> dict:
+    """Get all cue points in the arrangement."""
+    return _get_ableton(ctx).send_command("get_cue_points")
+
+
+@mcp.tool()
+def jump_to_cue(ctx: Context, cue_index: int) -> dict:
+    """Jump to a cue point by index."""
+    if cue_index < 0:
+        raise ValueError("cue_index must be >= 0")
+    return _get_ableton(ctx).send_command("jump_to_cue", {"cue_index": cue_index})
+
+
+@mcp.tool()
+def toggle_cue_point(ctx: Context) -> dict:
+    """Set or delete a cue point at the current playback position."""
+    return _get_ableton(ctx).send_command("toggle_cue_point")
+
+
+@mcp.tool()
+def create_arrangement_clip(
+    ctx: Context,
+    track_index: int,
+    clip_slot_index: int,
+    start_time: float,
+    length: float,
+    loop_length: float | None = None,
+    name: str = "",
+    color_index: int | None = None,
+) -> dict:
+    """Duplicate a session clip into Arrangement View at a specific beat position.
+
+    clip_slot_index: which session clip slot to use as the source pattern
+    start_time:      beat position in arrangement (0.0 = song start, 4.0 = bar 2)
+    length:          total clip length in beats on the timeline
+    loop_length:     pattern length to loop within the clip (e.g. 8.0 for an
+                     8-beat pattern inside a 128-beat section). Defaults to
+                     the source clip's length.
+    name:            optional clip display name
+    color_index:     optional 0-69 Ableton color
+
+    Returns clip_index in the track's arrangement_clips list.
+    """
+    _validate_track_index(track_index)
+    if clip_slot_index < 0:
+        raise ValueError("clip_slot_index must be >= 0")
+    if start_time < 0:
+        raise ValueError("start_time must be >= 0")
+    if length <= 0:
+        raise ValueError("length must be > 0")
+    params: dict = {
+        "track_index": track_index,
+        "clip_slot_index": clip_slot_index,
+        "start_time": start_time,
+        "length": length,
+    }
+    if loop_length is not None:
+        params["loop_length"] = loop_length
+    if name:
+        params["name"] = name
+    if color_index is not None:
+        if not 0 <= color_index <= 69:
+            raise ValueError("color_index must be 0-69")
+        params["color_index"] = color_index
+    return _get_ableton(ctx).send_command("create_arrangement_clip", params)
+
+
+@mcp.tool()
+def add_arrangement_notes(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    notes: list | str,
+) -> dict:
+    """Add MIDI notes to an arrangement clip.
+
+    clip_index:  index in track.arrangement_clips (returned by create_arrangement_clip
+                 or get_arrangement_clips)
+    notes:       list of dicts with: pitch (0-127), start_time (beats, relative to
+                 clip start), duration (beats), velocity (1-127), mute (bool)
+
+    start_time in notes is relative to the clip start, not the song timeline.
+    """
+    _validate_track_index(track_index)
+    if isinstance(notes, str):
+        notes = _json.loads(notes)
+    return _get_ableton(ctx).send_command("add_arrangement_notes", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "notes": notes,
+    })
+
+
+@mcp.tool()
+def set_arrangement_automation(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    parameter_type: str,
+    points: list | str,
+    device_index: int | None = None,
+    parameter_index: int | None = None,
+    send_index: int | None = None,
+) -> dict:
+    """Write automation envelope points into an arrangement clip.
+
+    parameter_type: "device", "volume", "panning", or "send"
+    points:         list of {time, value, duration?} dicts — time is relative
+                    to clip start (0.0 = first beat of clip), value is the
+                    parameter's native range (0.0-1.0 for most, check
+                    get_device_parameters for exact min/max).
+                    duration defaults to 0.125 beats (step automation).
+                    For smooth ramps, use many closely-spaced points.
+
+    For parameter_type="device": device_index + parameter_index required.
+    For parameter_type="send": send_index required (0=A, 1=B, ...).
+    """
+    _validate_track_index(track_index)
+    if parameter_type not in ("device", "volume", "panning", "send"):
+        raise ValueError("parameter_type must be 'device', 'volume', 'panning', or 'send'")
+    if parameter_type == "device":
+        if device_index is None or parameter_index is None:
+            raise ValueError("device_index and parameter_index required for parameter_type='device'")
+    if parameter_type == "send" and send_index is None:
+        raise ValueError("send_index required for parameter_type='send'")
+    if isinstance(points, str):
+        points = _json.loads(points)
+    if not points:
+        raise ValueError("points list cannot be empty")
+    params: dict = {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "parameter_type": parameter_type,
+        "points": points,
+    }
+    if device_index is not None:
+        params["device_index"] = device_index
+    if parameter_index is not None:
+        params["parameter_index"] = parameter_index
+    if send_index is not None:
+        params["send_index"] = send_index
+    return _get_ableton(ctx).send_command("set_arrangement_automation", params)
+
+
+@mcp.tool()
+def transpose_arrangement_notes(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    semitones: int,
+    from_time: float = 0.0,
+    time_span: float | None = None,
+) -> dict:
+    """Transpose notes in an arrangement clip by semitones (positive=up, negative=down).
+
+    clip_index:  index in track.arrangement_clips (from get_arrangement_clips)
+    semitones:   number of semitones to shift (-127 to 127)
+    from_time:   start of note range (beats, relative to clip start)
+    time_span:   length of note range in beats (defaults to full clip)
+    """
+    _validate_track_index(track_index)
+    if not -127 <= semitones <= 127:
+        raise ValueError("semitones must be between -127 and 127")
+    params: dict = {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "semitones": semitones,
+        "from_time": from_time,
+    }
+    if time_span is not None:
+        if time_span <= 0:
+            raise ValueError("time_span must be > 0")
+        params["time_span"] = time_span
+    return _get_ableton(ctx).send_command("transpose_arrangement_notes", params)
+
+
+@mcp.tool()
+def set_arrangement_clip_name(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    name: str,
+) -> dict:
+    """Rename an arrangement clip by its index in the track's arrangement_clips list."""
+    _validate_track_index(track_index)
+    if not name.strip():
+        raise ValueError("name cannot be empty")
+    return _get_ableton(ctx).send_command("set_arrangement_clip_name", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "name": name,
+    })
+
+
+@mcp.tool()
+def back_to_arranger(ctx: Context) -> dict:
+    """Switch playback from session clips back to the arrangement timeline."""
+    return _get_ableton(ctx).send_command("back_to_arranger")
+
+
+@mcp.tool()
+def get_arrangement_notes(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    from_pitch: int = 0,
+    pitch_span: int = 128,
+    from_time: float = 0.0,
+    time_span: float | None = None,
+) -> dict:
+    """Get MIDI notes from an arrangement clip. Returns note_id, pitch, start_time,
+    duration, velocity, mute, probability. Times are relative to clip start."""
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
+    if not 0 <= from_pitch <= 127:
+        raise ValueError("from_pitch must be between 0 and 127")
+    if pitch_span < 1 or pitch_span > 128:
+        raise ValueError("pitch_span must be between 1 and 128")
+    params: dict = {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "from_pitch": from_pitch,
+        "pitch_span": pitch_span,
+        "from_time": from_time,
+    }
+    if time_span is not None:
+        if time_span <= 0:
+            raise ValueError("time_span must be > 0")
+        params["time_span"] = time_span
+    return _get_ableton(ctx).send_command("get_arrangement_notes", params)
+
+
+@mcp.tool()
+def remove_arrangement_notes(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    from_pitch: int = 0,
+    pitch_span: int = 128,
+    from_time: float = 0.0,
+    time_span: float | None = None,
+) -> dict:
+    """Remove all MIDI notes in a pitch/time region of an arrangement clip. Defaults remove ALL notes."""
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
+    params: dict = {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "from_pitch": from_pitch,
+        "pitch_span": pitch_span,
+        "from_time": from_time,
+    }
+    if time_span is not None:
+        if time_span <= 0:
+            raise ValueError("time_span must be > 0")
+        params["time_span"] = time_span
+    return _get_ableton(ctx).send_command("remove_arrangement_notes", params)
+
+
+@mcp.tool()
+def remove_arrangement_notes_by_id(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    note_ids: list | str,
+) -> dict:
+    """Remove specific MIDI notes from an arrangement clip by their IDs."""
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
+    if isinstance(note_ids, str):
+        note_ids = _json.loads(note_ids)
+    if not note_ids:
+        raise ValueError("note_ids list cannot be empty")
+    return _get_ableton(ctx).send_command("remove_arrangement_notes_by_id", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "note_ids": note_ids,
+    })
+
+
+@mcp.tool()
+def modify_arrangement_notes(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    modifications: list | str,
+) -> dict:
+    """Modify existing MIDI notes in an arrangement clip by ID. modifications is a JSON array:
+    [{note_id, pitch?, start_time?, duration?, velocity?, probability?}]."""
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
+    if isinstance(modifications, str):
+        modifications = _json.loads(modifications)
+    if not modifications:
+        raise ValueError("modifications list cannot be empty")
+    for mod in modifications:
+        if "note_id" not in mod:
+            raise ValueError("Each modification must have a 'note_id' field")
+        if "pitch" in mod and not 0 <= int(mod["pitch"]) <= 127:
+            raise ValueError("pitch must be between 0 and 127")
+        if "duration" in mod and float(mod["duration"]) <= 0:
+            raise ValueError("duration must be > 0")
+        if "velocity" in mod and not 0.0 <= float(mod["velocity"]) <= 127.0:
+            raise ValueError("velocity must be between 0.0 and 127.0")
+        if "probability" in mod and not 0.0 <= float(mod["probability"]) <= 1.0:
+            raise ValueError("probability must be between 0.0 and 1.0")
+    return _get_ableton(ctx).send_command("modify_arrangement_notes", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "modifications": modifications,
+    })
+
+
+@mcp.tool()
+def duplicate_arrangement_notes(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    note_ids: list | str,
+    time_offset: float = 0.0,
+) -> dict:
+    """Duplicate specific notes in an arrangement clip by ID, with optional time offset (beats)."""
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
+    if isinstance(note_ids, str):
+        note_ids = _json.loads(note_ids)
+    if not note_ids:
+        raise ValueError("note_ids list cannot be empty")
+    return _get_ableton(ctx).send_command("duplicate_arrangement_notes", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "note_ids": note_ids,
+        "time_offset": time_offset,
+    })