livepilot 1.0.0

package/mcp_server/connection.py

@@ -0,0 +1,210 @@
+"""TCP client for communicating with Ableton Live's Remote Script."""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import time
+import uuid
+from collections import deque
+from typing import Optional
+
+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: Optional[str] = None, port: Optional[int] = 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: Optional[socket.socket] = 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: Optional[dict] = 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/memory/__init__.py

@@ -0,0 +1,5 @@
+"""LivePilot technique memory — persistent storage for learned patterns."""
+
+from .technique_store import TechniqueStore
+
+__all__ = ["TechniqueStore"]

package/mcp_server/memory/technique_store.py

@@ -0,0 +1,296 @@
+"""Persistent JSON store for LivePilot techniques (beat patterns, device chains, etc.)."""
+
+import json
+import os
+import threading
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+
+VALID_TYPES = frozenset(
+    ["beat_pattern", "device_chain", "mix_template", "browser_pin", "preference"]
+)
+
+VALID_SORT_FIELDS = frozenset(
+    ["updated_at", "created_at", "rating", "replay_count", "name"]
+)
+
+
+class TechniqueStore:
+    """Thread-safe JSON-backed store for techniques."""
+
+    def __init__(self, base_dir: Optional[str] = None):
+        if base_dir is None:
+            base_dir = os.path.join(os.path.expanduser("~"), ".livepilot", "memory")
+        self._base_dir = Path(base_dir)
+        self._base_dir.mkdir(parents=True, exist_ok=True)
+        self._file = self._base_dir / "techniques.json"
+        self._lock = threading.Lock()
+
+        if self._file.exists():
+            try:
+                with open(self._file, "r") as f:
+                    self._data = json.load(f)
+            except (json.JSONDecodeError, ValueError):
+                corrupt = self._file.with_suffix(".json.corrupt")
+                self._file.rename(corrupt)
+                self._data = {"version": 1, "techniques": []}
+        else:
+            self._data = {"version": 1, "techniques": []}
+            self._flush()
+
+    # ── persistence ──────────────────────────────────────────────
+
+    def _flush(self) -> None:
+        """Atomic write: tmp file then rename."""
+        tmp = self._file.with_suffix(".tmp")
+        with open(tmp, "w") as f:
+            json.dump(self._data, f, indent=2)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(str(tmp), str(self._file))
+
+    # ── public API ───────────────────────────────────────────────
+
+    def save(
+        self,
+        name: str,
+        type: str,
+        qualities: dict,
+        payload: dict,
+        tags: Optional[list[str]] = None,
+    ) -> dict:
+        """Create a new technique. Returns {id, name, type, summary}."""
+        if type not in VALID_TYPES:
+            raise ValueError(
+                f"INVALID_PARAM: type must be one of {sorted(VALID_TYPES)}, got '{type}'"
+            )
+        if not qualities.get("summary"):
+            raise ValueError("INVALID_PARAM: qualities must contain non-empty 'summary'")
+
+        now = datetime.now(timezone.utc).isoformat()
+        technique = {
+            "id": str(uuid.uuid4()),
+            "name": name,
+            "type": type,
+            "qualities": qualities,
+            "payload": payload,
+            "tags": tags or [],
+            "created_at": now,
+            "updated_at": now,
+            "favorite": False,
+            "rating": 0,
+            "replay_count": 0,
+        }
+
+        with self._lock:
+            self._data["techniques"].append(technique)
+            self._flush()
+
+        return {
+            "id": technique["id"],
+            "name": technique["name"],
+            "type": technique["type"],
+            "summary": qualities["summary"],
+        }
+
+    def get(self, technique_id: str) -> dict:
+        """Return full technique by id."""
+        with self._lock:
+            for t in self._data["techniques"]:
+                if t["id"] == technique_id:
+                    return dict(t)
+        raise ValueError(f"NOT_FOUND: technique '{technique_id}' does not exist")
+
+    def search(
+        self,
+        query: Optional[str] = None,
+        type_filter: Optional[str] = None,
+        tags: Optional[list[str]] = None,
+        limit: int = 10,
+    ) -> list[dict]:
+        """Search techniques. Returns summaries (no payload)."""
+        with self._lock:
+            results = list(self._data["techniques"])
+
+        # filter by type
+        if type_filter:
+            results = [t for t in results if t["type"] == type_filter]
+
+        # filter by tags (match any)
+        if tags:
+            tag_set = set(tags)
+            results = [t for t in results if tag_set & set(t.get("tags", []))]
+
+        # text search — all query words must appear somewhere in the technique
+        if query:
+            words = query.lower().split()
+            filtered = []
+            for t in results:
+                searchable = self._searchable_text(t)
+                if all(w in searchable for w in words):
+                    filtered.append(t)
+            results = filtered
+
+        results = self._multi_sort(results)
+
+        results = results[:limit]
+
+        # strip payload
+        return [self._summary(t) for t in results]
+
+    def list_techniques(
+        self,
+        type_filter: Optional[str] = None,
+        tags: Optional[list[str]] = None,
+        sort_by: str = "updated_at",
+        limit: int = 20,
+    ) -> list[dict]:
+        """List techniques as compact summaries."""
+        if sort_by not in VALID_SORT_FIELDS:
+            raise ValueError(
+                f"INVALID_PARAM: sort_by must be one of {sorted(VALID_SORT_FIELDS)}, got '{sort_by}'"
+            )
+
+        with self._lock:
+            results = list(self._data["techniques"])
+
+        if type_filter:
+            results = [t for t in results if t["type"] == type_filter]
+
+        if tags:
+            tag_set = set(tags)
+            results = [t for t in results if tag_set & set(t.get("tags", []))]
+
+        reverse = sort_by != "name"
+        results.sort(key=lambda t: t.get(sort_by, ""), reverse=reverse)
+
+        results = results[:limit]
+
+        return [self._compact_summary(t) for t in results]
+
+    def favorite(
+        self,
+        technique_id: str,
+        favorite: Optional[bool] = None,
+        rating: Optional[int] = None,
+    ) -> dict:
+        """Set favorite flag and/or rating."""
+        if rating is not None and (rating < 0 or rating > 5):
+            raise ValueError("INVALID_PARAM: rating must be between 0 and 5")
+
+        with self._lock:
+            t = self._find(technique_id)
+            if favorite is not None:
+                t["favorite"] = favorite
+            if rating is not None:
+                t["rating"] = rating
+            t["updated_at"] = datetime.now(timezone.utc).isoformat()
+            self._flush()
+            return self._compact_summary(t)
+
+    def update(
+        self,
+        technique_id: str,
+        name: Optional[str] = None,
+        tags: Optional[list[str]] = None,
+        qualities: Optional[dict] = None,
+    ) -> dict:
+        """Update technique fields. Qualities are merged (lists replaced)."""
+        with self._lock:
+            t = self._find(technique_id)
+            if name is not None:
+                t["name"] = name
+            if tags is not None:
+                t["tags"] = tags
+            if qualities is not None:
+                existing = t.get("qualities", {})
+                existing.update(qualities)
+                t["qualities"] = existing
+            t["updated_at"] = datetime.now(timezone.utc).isoformat()
+            self._flush()
+            return self._compact_summary(t)
+
+    def delete(self, technique_id: str) -> dict:
+        """Delete technique after creating a timestamped backup."""
+        with self._lock:
+            t = self._find(technique_id)
+            # backup
+            backup_dir = self._base_dir / "backups"
+            backup_dir.mkdir(exist_ok=True)
+            ts = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S")
+            backup_file = backup_dir / f"{technique_id}_{ts}.json"
+            with open(backup_file, "w") as f:
+                json.dump(t, f, indent=2)
+            # remove
+            self._data["techniques"] = [
+                x for x in self._data["techniques"] if x["id"] != technique_id
+            ]
+            self._flush()
+            return {"id": technique_id, "deleted": True}
+
+    def increment_replay(self, technique_id: str) -> None:
+        """Increment replay_count and set last_replayed_at."""
+        with self._lock:
+            t = self._find(technique_id)
+            t["replay_count"] = t.get("replay_count", 0) + 1
+            t["last_replayed_at"] = datetime.now(timezone.utc).isoformat()
+            self._flush()
+
+    # ── private helpers ──────────────────────────────────────────
+
+    def _find(self, technique_id: str) -> dict:
+        """Find technique by id (must hold lock). Returns mutable ref."""
+        for t in self._data["techniques"]:
+            if t["id"] == technique_id:
+                return t
+        raise ValueError(f"NOT_FOUND: technique '{technique_id}' does not exist")
+
+    @staticmethod
+    def _searchable_text(t: dict) -> str:
+        """Build a single lowercase string from all searchable fields."""
+        parts = [t.get("name", "")]
+        parts.extend(t.get("tags", []))
+        for v in t.get("qualities", {}).values():
+            if isinstance(v, str):
+                parts.append(v)
+            elif isinstance(v, list):
+                parts.extend(str(item) for item in v)
+        return " ".join(parts).lower()
+
+    @staticmethod
+    def _multi_sort(results: list[dict]) -> list[dict]:
+        """Sort: favorites first, rating desc, replay_count desc, updated_at desc."""
+        return sorted(
+            results,
+            key=lambda t: (
+                t.get("favorite", False),
+                t.get("rating", 0),
+                t.get("replay_count", 0),
+                t.get("updated_at", ""),
+            ),
+            reverse=True,
+        )
+
+    @staticmethod
+    def _summary(t: dict) -> dict:
+        """Everything except payload."""
+        return {k: v for k, v in t.items() if k != "payload"}
+
+    @staticmethod
+    def _compact_summary(t: dict) -> dict:
+        """Compact: id, name, type, tags, summary, favorite, rating, replay_count, timestamps."""
+        return {
+            "id": t["id"],
+            "name": t["name"],
+            "type": t["type"],
+            "tags": t.get("tags", []),
+            "summary": t.get("qualities", {}).get("summary", ""),
+            "favorite": t.get("favorite", False),
+            "rating": t.get("rating", 0),
+            "replay_count": t.get("replay_count", 0),
+            "created_at": t.get("created_at", ""),
+            "updated_at": t.get("updated_at", ""),
+        }

package/mcp_server/server.py

@@ -0,0 +1,87 @@
+"""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
+from .tools import memory       # noqa: F401, E402
+
+
+# ---------------------------------------------------------------------------
+# Schema coercion patch — accept strings for numeric parameters
+# ---------------------------------------------------------------------------
+# Some MCP clients (with deferred tools) send all parameter
+# values as strings.  Their client-side Zod validators reject "0" against
+# {"type": "integer"} before the request even reaches our server.
+#
+# Fix: widen every integer/number property in the advertised JSON Schema to
+# also accept strings.  Server-side Pydantic validation (lax mode) coerces
+# "5" → 5 and "0.75" → 0.75 automatically, so no tool code changes needed.
+# ---------------------------------------------------------------------------
+
+def _coerce_schema_property(prop: dict) -> None:
+    """Widen a single JSON Schema property to also accept strings."""
+    if prop.get("type") in ("integer", "number"):
+        original_type = prop.pop("type")
+        prop["anyOf"] = [{"type": original_type}, {"type": "string"}]
+    elif "anyOf" in prop:
+        for variant in prop["anyOf"]:
+            _coerce_schema_property(variant)
+
+
+def _get_all_tools():
+    """Get all registered tools, compatible with FastMCP 0.x and 3.x."""
+    # FastMCP 0.x: mcp._tool_manager._tools (dict of name -> Tool)
+    if hasattr(mcp, "_tool_manager"):
+        return list(mcp._tool_manager._tools.values())
+    # FastMCP 3.x: mcp._local_provider._components (dict of key -> Tool)
+    if hasattr(mcp, "_local_provider") and hasattr(mcp._local_provider, "_components"):
+        return list(mcp._local_provider._components.values())
+    return []
+
+
+def _patch_tool_schemas() -> None:
+    """Post-process all registered tool schemas for string coercion."""
+    for tool in _get_all_tools():
+        props = tool.parameters.get("properties", {})
+        for name, prop in props.items():
+            if name == "ctx":
+                continue  # skip the Context parameter
+            _coerce_schema_property(prop)
+
+
+_patch_tool_schemas()
+
+
+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."""