livepilot 1.27.1 → 1.27.3

package/mcp_server/tools/arrangement.py

@@ -107,10 +107,13 @@ def create_arrangement_clip(
                      8-beat pattern inside a 128-beat section). Defaults to
                      the source clip's length. Must be > 0.
 
-    When loop_length < source clip length, overlapping copies are placed
-    every loop_length beats. Ableton's "later clip takes priority" rule
-    ensures correct playback. Each copy's internal loop region is set to
-    loop_length beats. For best results, use loop_length >= source length.
+    Copies are tiled every min(loop_length, source length) beats so the
+    region is always filled seamlessly — a loop_length larger than the
+    source no longer leaves a silent gap between copies. When
+    loop_length < source length, overlapping copies are placed every
+    loop_length beats and each copy's internal loop region is set to
+    loop_length beats (Ableton's "later clip takes priority" rule ensures
+    correct playback).
 
     name:            optional clip display name
     color_index:     optional 0-69 Ableton color

package/mcp_server/tools/automation.py

@@ -7,6 +7,7 @@ engine (curves.py) for musically intelligent automation.
 
 from __future__ import annotations
 
+import asyncio
 from typing import Any, Optional
 
 from fastmcp import Context
@@ -110,11 +111,25 @@ def set_clip_automation(
             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'")
+    points_list = _ensure_list(points)
+    # Clamp values for fixed-range mixer envelopes so an out-of-range curve
+    # value (e.g. volume=1.5 from an inverted/scaled curve) can't reach the
+    # Remote Script. Mirrors set_track_volume/send (0.0-1.0) and
+    # set_track_pan (-1.0..1.0). Device params keep their native range — the
+    # caller is responsible for scaling those to the parameter's min/max.
+    if parameter_type in ("volume", "send"):
+        for pt in points_list:
+            if isinstance(pt, dict) and "value" in pt:
+                pt["value"] = max(0.0, min(1.0, pt["value"]))
+    elif parameter_type == "panning":
+        for pt in points_list:
+            if isinstance(pt, dict) and "value" in pt:
+                pt["value"] = max(-1.0, min(1.0, pt["value"]))
     params: dict = {
         "track_index": track_index,
         "clip_index": clip_index,
         "parameter_type": parameter_type,
-        "points": _ensure_list(points),
+        "points": points_list,
     }
     if device_index is not None:
         params["device_index"] = device_index
@@ -257,6 +272,8 @@ def apply_automation_shape(
             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 curve_type == "euclidean" and steps < 1:
+        raise ValueError("euclidean 'steps' must be >= 1")
 
     # Generate the curve
     points = generate_curve(
@@ -465,6 +482,8 @@ def generate_automation_curve(
     Pass the returned points to set_clip_automation or
     set_arrangement_automation to write them.
     """
+    if curve_type == "euclidean" and steps < 1:
+        raise ValueError("euclidean 'steps' must be >= 1")
     points = generate_curve(
         curve_type=curve_type,
         duration=duration,
@@ -717,7 +736,8 @@ async def set_arrangement_automation_via_session_record(
     if send_index is not None:
         start_params["send_index"] = send_index
 
-    start_result = ableton.send_command(
+    start_result = await asyncio.to_thread(
+        ableton.send_command,
         "arrangement_automation_via_session_record_start",
         start_params,
     )
@@ -732,7 +752,6 @@ async def set_arrangement_automation_via_session_record(
     # Compute sleep: duration_beats * 60/tempo seconds + 0.5s buffer for
     # Live's record-arm latency. Tempo comes back from the start handler
     # (fresh Song.tempo read) so we don't hardcode 120.
-    import asyncio
     tempo = float(start_result.get("tempo") or 120.0)
     if tempo <= 0:
         tempo = 120.0
@@ -755,7 +774,8 @@ async def set_arrangement_automation_via_session_record(
         "duration_beats": duration_beats,
         "cleanup_session_clip": cleanup_session_clip,
     }
-    complete_result = ableton.send_command(
+    complete_result = await asyncio.to_thread(
+        ableton.send_command,
         "arrangement_automation_via_session_record_complete",
         complete_params,
     )

package/mcp_server/tools/browser.py

@@ -327,12 +327,12 @@ def load_browser_item(
 
     # Post-load: probe the loaded device once, then apply two layers of hygiene.
     #
-    # 2026-05-02 — fixed device-detection bug. The TCP load_browser_item command
-    # returns {loaded, name, device_count} with NO device_index and NO class_name,
-    # so the previous detection (`result.get("device_index")` / `result.get("class_name")`)
-    # always failed and the role-defaults branch was never entered. Resolution:
-    # treat newly-loaded sample-on-empty-track as device_index=0 (Live places the
-    # instrument at chain head) and verify class + name via get_device_info.
+    # 2026-06-24 — fixed wrong-device bug. Live APPENDS a newly-loaded device at
+    # the END of the chain, so on a NON-EMPTY track the loaded device is NOT at
+    # index 0. The remote handler now returns device_index (= device_count - 1);
+    # we use that (falling back to device_count - 1, then 0) and probe THAT index
+    # to verify class + name before applying any role-default / hygiene writes —
+    # otherwise the writes would hit the pre-existing device 0.
     #
     # Layer 1 (gated on `role`): Simpler role-aware defaults — Snap/Volume/
     # Trigger Mode/Transpose for drum/melodic/texture roles.
@@ -342,18 +342,32 @@ def load_browser_item(
     device_class = ""
     device_name_loaded = ""
     if isinstance(result, dict) and result.get("loaded") and not result.get("error"):
+        # Resolve the index of the JUST-LOADED device. Live appends new devices
+        # at the END of the chain, so the loaded device is device_count - 1 —
+        # NOT index 0. Probing/writing index 0 on a NON-EMPTY track would
+        # read/mutate the WRONG (pre-existing) device while leaving the freshly
+        # loaded one at raw defaults (the documented drum-Simpler Transpose=+24
+        # silent-failure path). Prefer the remote-reported device_index, fall
+        # back to device_count - 1, then to 0 (empty track / unknown count).
         device_index_resolved = result.get("device_index")
+        if device_index_resolved is None:
+            dc = result.get("device_count")
+            device_index_resolved = (dc - 1) if isinstance(dc, int) and dc > 0 else 0
         try:
             probe = ableton.send_command("get_device_info", {
                 "track_index": track_index,
-                "device_index": 0,
+                "device_index": int(device_index_resolved),
             })
             device_class = str(probe.get("class_name", "") or "")
             device_name_loaded = str(probe.get("name", "") or result.get("name", "") or "")
-            if device_index_resolved is None:
-                device_index_resolved = 0
-        except Exception:
-            pass
+        except Exception as exc:
+            # Surface the probe failure instead of silently swallowing it: the
+            # role-defaults / M4L-hygiene blocks below are gated on
+            # device_class / device_name_loaded and will quietly skip, so
+            # without this the load reports success while post-load hygiene
+            # (drum Transpose=+24, Snap, Volume) never ran.
+            result["role_defaults_skipped"] = "device probe failed: %s" % exc
+            device_name_loaded = str(result.get("name", "") or "")
 
     # Layer 0 — atlas-aware preflight. Surface a follow-up hint when the
     # loaded device declares self_contained=false in its atlas enrichment

package/mcp_server/tools/clips.py

@@ -516,6 +516,8 @@ def get_clip_scale(ctx: Context, track_index: int, clip_index: int) -> dict:
     Returns {root_note (0-11), scale_mode (bool), scale_name (str)}.
     Raises if the clip slot is empty.
     """
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
     return _get_ableton(ctx).send_command("get_clip_scale", {
         "track_index": track_index,
         "clip_index": clip_index,
@@ -540,6 +542,8 @@ def set_clip_scale(
     scale_name:  must match one of Live's built-in scales
                  (call list_available_scales() if unsure)
     """
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
     if not 0 <= root_note <= 11:
         raise ValueError("root_note must be 0-11")
     if not scale_name.strip():
@@ -564,6 +568,8 @@ def set_clip_scale_mode(
     When enabled on a clip, its notes are constrained/highlighted
     by the clip's own root_note + scale_name (set via set_clip_scale).
     """
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
     return _get_ableton(ctx).send_command("set_clip_scale_mode", {
         "track_index": track_index,
         "clip_index": clip_index,

package/mcp_server/tools/composition.py

@@ -57,6 +57,27 @@ def _build_clip_matrix(ableton, scene_count: int, track_count: int) -> list[list
         return [[] for _ in range(scene_count)]
 
 
+def _slot_has_clip(clip_matrix: list[list], scene_idx: int, track_idx: int) -> bool:
+    """Whether the (scene, track) session slot actually holds a clip.
+
+    Reads the clip_matrix produced by get_scene_matrix
+    (matrix[scene_index][track_index] = {"state": ...}). A slot holds a
+    clip when its state is anything other than "empty"/"missing". Used to
+    gate per-slot get_notes round-trips so empty slots — the bulk of a
+    sparse session grid — don't each cost a blocking TCP call on
+    Ableton's main thread.
+    """
+    if scene_idx >= len(clip_matrix):
+        return False
+    row = clip_matrix[scene_idx]
+    if track_idx >= len(row):
+        return False
+    cell = row[track_idx]
+    if not cell:
+        return False
+    return cell.get("state") not in ("empty", "missing")
+
+
 # ── analyze_composition ───────────────────────────────────────────────
 
 
@@ -126,9 +147,15 @@ def analyze_composition(ctx: Context) -> dict:
 
     for track in tracks:
         t_idx = track["index"]
-        # Collect notes from all clips
+        # Collect notes only from slots that actually hold a clip. Empty
+        # slots are skipped — the clip_matrix already tells us they have no
+        # notes, so issuing a blocking get_notes round-trip per empty slot
+        # would burn O(tracks x scenes) synchronous TCP calls on Ableton's
+        # main thread for no data.
         track_notes = []
         for s_idx in range(len(scenes)):
+            if not _slot_has_clip(clip_matrix, s_idx, t_idx):
+                continue
             try:
                 result = ableton.send_command("get_notes", {
                     "track_index": t_idx, "clip_index": s_idx
@@ -241,7 +268,11 @@ def get_phrase_grid(
     # (which maps to the actual clip slot), not the section_index
     # (which is a position in the section graph)
     notes_by_track: dict[int, list] = {}
-    scene_idx = section.scene_index if hasattr(section, "scene_index") else section_index
+    # scene_index now ALWAYS exists (dataclass default -1), so a hasattr() guard
+    # is always True and would forward -1 for arrangement-backed sections — and
+    # clip_index=-1 silently wraps to the LAST clip slot. Guard on the value
+    # being a real slot (>= 0), matching get_harmony_field's guard.
+    scene_idx = section.scene_index if getattr(section, "scene_index", -1) >= 0 else section_index
     for t_idx in section.tracks_active:
         try:
             result = ableton.send_command("get_notes", {

package/mcp_server/tools/devices.py

@@ -5,6 +5,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import json
 from typing import Any, Optional
 
@@ -252,40 +253,32 @@ def set_device_parameter(
 
     track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master.
 
-    ⚠️ PARAMETER RANGES ARE NOT ALWAYS 0-1 (BUG-B4 / B9 / 2026-04-26#2):
-      Ableton devices use MIXED units depending on the parameter. Always
-      read the `value_string` in the response (and the `min`/`max` from
-      get_device_parameters) before assuming 0-1 semantics:
-
-        - Auto Filter `Frequency`:        20-135 index (NOT normalized)
-        - Auto Filter Legacy `LFO Amount`: 0-30 absolute (displays as %)
-        - Auto Filter `Resonance`:        0-1.25 on legacy, 0-1 on AutoFilter2
-        - Auto Filter `Env. Modulation`:  -127..+127 on legacy
-        - Compressor I (legacy):          pre-2010 units (Threshold dB direct)
-        - **Compressor 2 (modern, default)**: 0-1 NORMALIZED.
+    ⚠️ PARAMETER RANGES ARE NOT ALWAYS 0-1. Ableton devices use MIXED
+    units depending on the parameter. Always read `value_string` in the
+    response (or min/max from get_device_parameters) before assuming
+    0-1 semantics — it's the SOURCE OF TRUTH for what the user sees.
+    Full per-device table: livepilot-devices references/
+    device-parameter-units.md. Quick hits:
+
+        - **Compressor 2** (modern, default): 0-1 NORMALIZED.
           `Threshold 0.85 ≈ 0 dB`, `Ratio 0.75 = 4:1`, `Release 0.16 = 30 ms`.
-          Setting Threshold to a dB value like -22 will fail. Compute
-          normalized: `(dB + 50) / 50` for typical dB→0-1 mapping, OR
-          read the param's value_string after a probe write.
+          A dB value like -22 will fail here. Compressor I (legacy):
+          pre-2010 units, dB direct.
         - **Saturator** `Drive`, `Output`, `Threshold`, `Color *`: 0-1
           NORMALIZED (Drive 0.5 ≈ 0 dB, Drive 0.6 ≈ +7 dB).
-        - Dynamic Tube, Vocoder:          pre-2010 units
-        - EQ Three `Frequency Hi/Lo`:     50Hz-15kHz absolute
-        - Wavetable `Osc 1 Pos`:          0-1 normalized ✓
-        - Drift / Analog / Operator macros: 0-1 normalized ✓
-        - Pedal `Output`:                 -20..+20 dB direct
-        - Pedal `Bass / Mid / Treble`:    -1..+1 direct
-
-      The `value_string` field in the response is the SOURCE OF TRUTH
-      for what the user sees. Automation recipes that assume 0-1 will
-      clamp on legacy devices. When in doubt, call
-      get_device_parameters first to inspect min/max/is_quantized.
-
-    Error enrichment (BUG-2026-04-26#2): if the Remote Script rejects
-    the value as out-of-range, this wrapper fetches the parameter's
-    actual min/max/value_string and re-raises with that context inline.
-    Saves a follow-up get_device_parameters round-trip in the agent
-    loop after every miss.
+        - Auto Filter `Frequency`: 20-135 index (NOT normalized).
+        - EQ Three `Frequency Hi/Lo`: 50Hz-15kHz absolute.
+        - Wavetable / Drift / Analog / Operator macros: 0-1 normalized ✓.
+        - Pedal `Output`: -20..+20 dB direct; `Bass/Mid/Treble`: -1..+1.
+
+      When in doubt, call get_device_parameters first to inspect
+      min/max/is_quantized.
+
+    On out-of-range rejection, the error is enriched with the actual
+    min/max/value_string for that parameter — no follow-up
+    get_device_parameters round-trip needed. Response includes
+    `snapped: bool` when Ableton silently quantized the value to the
+    nearest step (quantized-enum params).
     """
     _validate_track_index(track_index)
     _validate_device_index(device_index)
@@ -303,7 +296,20 @@ def set_device_parameter(
     if parameter_index is not None:
         params["parameter_index"] = parameter_index
     try:
-        return _get_ableton(ctx).send_command("set_device_parameter", params)
+        response = _get_ableton(ctx).send_command("set_device_parameter", params)
+        # P2-51: apply the same silent-snap detection as batch_set_parameters so
+        # both sibling tools give a machine-readable ``snapped`` signal.
+        if isinstance(response, dict):
+            actual_val = response.get("value")
+            if actual_val is not None:
+                try:
+                    req_f = float(value)
+                    act_f = float(actual_val)
+                    did_snap = abs(req_f - act_f) > _SNAP_EPSILON
+                except (TypeError, ValueError):
+                    did_snap = value != actual_val
+                response["snapped"] = did_snap
+        return response
     except Exception as exc:
         # BUG-2026-04-26#2: enrich out-of-range errors with the actual
         # min/max/value_string from get_device_parameters so the caller
@@ -503,13 +509,11 @@ def batch_set_parameters(
 
     track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master.
 
-    Response (v1.20.2+): the dict now includes a ``snapped_params`` list
-    when quantized-enum parameters were silently snapped by Ableton
-    (requested 0.3, received 0). Empty list means every requested value
-    round-tripped within 1e-5 tolerance. Callers using this tool to
-    drive deterministic state should inspect ``snapped_params`` before
-    assuming success — see BUG #4 in the v1.20 live-test campaign for
-    the motivating case (Beat Repeat Gate).
+    Response includes a ``snapped_params`` list when quantized-enum
+    parameters were silently snapped by Ableton (requested 0.3, received
+    0; e.g. Beat Repeat's Gate). Empty list means every requested value
+    round-tripped within 1e-5 tolerance. Callers driving deterministic
+    state should inspect ``snapped_params`` before assuming success.
     """
     _validate_track_index(track_index)
     _validate_device_index(device_index)
@@ -650,12 +654,11 @@ def insert_device(
     device_index: required when inserting into a rack chain (identifies the rack)
     chain_index:  insert into this chain of a rack device (for building drum kits)
 
-    Drum Rack construction workflow (12.3+):
-    1. insert_device(track_index, 'Drum Rack')       — create empty rack
-    2. insert_rack_chain(track_index, device_index)   — add chains
-    3. set_drum_chain_note(chain_index, note=36)      — assign C1 (kick)
-    4. insert_device(track_index, 'Simpler',          — add instrument
-       device_index=rack_idx, chain_index=0)            into chain
+    Drum Rack construction workflow (12.3+, full detail: livepilot-devices
+    references/device-parameter-units.md#drum-rack-construction-workflow-123):
+    insert_device(track, 'Drum Rack') to create the rack, then
+    insert_rack_chain + set_drum_chain_note + insert_device(..., chain_index=0)
+    to add each pad's instrument.
 
     On Live < 12.3: returns an error suggesting find_and_load_device instead.
     """
@@ -690,11 +693,8 @@ def insert_rack_chain(
 ) -> dict:
     """Insert a new chain into a Rack device — Instrument Rack, Audio Effect Rack, or Drum Rack (Live 12.3+).
 
-    Use with insert_device + set_drum_chain_note to build Drum Racks from scratch:
-    1. insert_device(track, 'Drum Rack') to create the rack
-    2. insert_rack_chain(track, rack_device_index) to add chains
-    3. set_drum_chain_note(chain_index=0, note=36) to assign C1 (kick)
-    4. insert_device(track, 'Simpler', device_index=rack, chain_index=0) into chain
+    Use with insert_device + set_drum_chain_note to build Drum Racks from
+    scratch — see insert_device's docstring for the full 4-step workflow.
 
     track_index:  track containing the rack
     device_index: rack device index on the track
@@ -932,7 +932,7 @@ async def get_plugin_parameters(
     _validate_track_index(track_index)
     _validate_device_index(device_index)
     cache = _get_spectral(ctx)
-    _require_analyzer(cache)
+    await asyncio.to_thread(_require_analyzer, cache)
     bridge = _get_m4l(ctx)
     return await bridge.send_command("get_plugin_params", track_index, device_index, timeout=20.0)
 
@@ -956,7 +956,7 @@ async def map_plugin_parameter(
     if parameter_index < 0:
         raise ValueError("parameter_index must be >= 0")
     cache = _get_spectral(ctx)
-    _require_analyzer(cache)
+    await asyncio.to_thread(_require_analyzer, cache)
     bridge = _get_m4l(ctx)
     return await bridge.send_command("map_plugin_param", track_index, device_index, parameter_index, timeout=10.0)
 
@@ -976,7 +976,7 @@ async def get_plugin_presets(
     _validate_track_index(track_index)
     _validate_device_index(device_index)
     cache = _get_spectral(ctx)
-    _require_analyzer(cache)
+    await asyncio.to_thread(_require_analyzer, cache)
     bridge = _get_m4l(ctx)
     return await bridge.send_command("get_plugin_presets", track_index, device_index, timeout=15.0)
 

package/mcp_server/tools/generative.py

@@ -43,11 +43,11 @@ def generate_euclidean_rhythm(
     Returns note array — use add_notes to place in a clip.
     """
     if not 0 <= pulses <= 64:
-        return {"error": "pulses must be 0-64"}
+        return {"error": "pulses must be 0-64", "code": "INVALID_PARAM"}
     if not 1 <= steps <= 64:
-        return {"error": "steps must be 1-64"}
+        return {"error": "steps must be 1-64", "code": "INVALID_PARAM"}
     if pulses > steps:
-        return {"error": "pulses must be <= steps"}
+        return {"error": "pulses must be <= steps", "code": "INVALID_PARAM"}
 
     pattern = gen.bjorklund(pulses, steps)
     if rotation:
@@ -85,7 +85,7 @@ def layer_euclidean_rhythms(
     """
     layers = _ensure_list(layers)
     if not layers:
-        return {"error": "At least one layer required"}
+        return {"error": "At least one layer required", "code": "INVALID_PARAM"}
 
     all_notes: list[dict] = []
     layer_info: list[dict] = []
@@ -152,16 +152,16 @@ def generate_tintinnabuli(
     """
     melody_notes = _ensure_list(melody_notes)
     if not melody_notes:
-        return {"error": "melody_notes cannot be empty"}
+        return {"error": "melody_notes cannot be empty", "code": "INVALID_PARAM"}
     if position not in ("above", "below", "nearest"):
-        return {"error": "position must be 'above', 'below', or 'nearest'"}
+        return {"error": "position must be 'above', 'below', or 'nearest'", "code": "INVALID_PARAM"}
 
     try:
         parsed = theory.parse_key(triad)
     except ValueError:
-        return {"error": f"Cannot parse triad: {triad}"}
+        return {"error": f"Cannot parse triad: {triad}", "code": "INVALID_PARAM"}
     if parsed["mode"] not in ("major", "minor"):
-        return {"error": "Only major and minor triads are supported"}
+        return {"error": "Only major and minor triads are supported", "code": "INVALID_PARAM"}
 
     root = parsed["tonic"]
     if parsed["mode"] == "major":
@@ -208,11 +208,11 @@ def generate_phase_shift(
     """
     pattern_notes = _ensure_list(pattern_notes)
     if not pattern_notes:
-        return {"error": "pattern_notes cannot be empty"}
+        return {"error": "pattern_notes cannot be empty", "code": "INVALID_PARAM"}
     if not 1 <= voices <= 8:
-        return {"error": "voices must be 1-8"}
+        return {"error": "voices must be 1-8", "code": "INVALID_PARAM"}
     if shift_amount <= 0:
-        return {"error": "shift_amount must be > 0"}
+        return {"error": "shift_amount must be > 0", "code": "INVALID_PARAM"}
 
     result_notes = gen.phase_shift(pattern_notes, voices, shift_amount, total_length)
 
@@ -251,11 +251,11 @@ def generate_additive_process(
     """
     melody_notes = _ensure_list(melody_notes)
     if not melody_notes:
-        return {"error": "melody_notes cannot be empty"}
+        return {"error": "melody_notes cannot be empty", "code": "INVALID_PARAM"}
     if direction not in ("forward", "backward", "both"):
-        return {"error": "direction must be 'forward', 'backward', or 'both'"}
+        return {"error": "direction must be 'forward', 'backward', or 'both'", "code": "INVALID_PARAM"}
     if repetitions_per_stage < 1:
-        return {"error": "repetitions_per_stage must be >= 1"}
+        return {"error": "repetitions_per_stage must be >= 1", "code": "INVALID_PARAM"}
 
     result_notes = gen.additive_process(melody_notes, direction,
                                          repetitions_per_stage)

package/mcp_server/tools/harmony.py

@@ -43,11 +43,11 @@ def navigate_tonnetz(
     Use depth 2-3 to see compound transforms (PL, PR, PRL, etc.).
     """
     if not 1 <= depth <= 3:
-        return {"error": "depth must be 1-3"}
+        return {"error": "depth must be 1-3", "code": "INVALID_PARAM"}
     try:
         root_pc, quality = harmony.parse_chord(chord)
     except ValueError as e:
-        return {"error": str(e)}
+        return {"error": str(e), "code": "INVALID_PARAM"}
 
     all_neighbors = harmony.get_neighbors(root_pc, quality, depth)
 
@@ -108,12 +108,12 @@ def find_voice_leading_path(
     hexatonic poles, and other cinematic chord moves.
     """
     if not 1 <= max_steps <= 6:
-        return {"error": "max_steps must be 1-6"}
+        return {"error": "max_steps must be 1-6", "code": "INVALID_PARAM"}
     try:
         from_parsed = harmony.parse_chord(from_chord)
         to_parsed = harmony.parse_chord(to_chord)
     except ValueError as e:
-        return {"error": str(e)}
+        return {"error": str(e), "code": "INVALID_PARAM"}
 
     result = harmony.find_shortest_path(from_parsed, to_parsed, max_steps)
 
@@ -221,7 +221,7 @@ def classify_progression(
     """
     chords = _ensure_list(chords)
     if len(chords) < 2:
-        return {"error": "Need at least 2 chords to classify"}
+        return {"error": "Need at least 2 chords to classify", "code": "INVALID_PARAM"}
 
     # Normalize dict inputs like {"root": "F#", "quality": "minor"} to strings
     normalized = []
@@ -236,7 +236,7 @@ def classify_progression(
     try:
         parsed = [harmony.parse_chord(c) for c in normalized]
     except ValueError as e:
-        return {"error": str(e)}
+        return {"error": str(e), "code": "INVALID_PARAM"}
 
     transforms = harmony.classify_transform_sequence(parsed)
     pattern = "".join(transforms)
@@ -336,7 +336,7 @@ def suggest_chromatic_mediants(
     try:
         root_pc, quality = harmony.parse_chord(chord)
     except ValueError as e:
-        return {"error": str(e)}
+        return {"error": str(e), "code": "INVALID_PARAM"}
 
     mediants = harmony.get_chromatic_mediants(root_pc, quality)
 

package/mcp_server/tools/mixing.py

@@ -130,13 +130,13 @@ async def get_track_meters(
         interval = max(0, sample_interval_ms) / 1000.0
         snapshots: list[dict] = []
         for i in range(samples):
-            snap = ableton.send_command("get_track_meters", params)
+            snap = await asyncio.to_thread(ableton.send_command, "get_track_meters", params)
             if isinstance(snap, dict):
                 snapshots.append(snap)
             if i < samples - 1 and interval > 0:
                 await asyncio.sleep(interval)
         if not snapshots:
-            return {"error": "No meter snapshots collected"}
+            return {"error": "No meter snapshots collected", "code": "STATE_ERROR"}
         # Take the first snapshot's structure and peak-combine across all.
         result = dict(snapshots[0])
         # Merge tracks field with peak-maxing
@@ -165,13 +165,13 @@ async def get_track_meters(
         result["samples_collected"] = len(snapshots)
         result["sample_interval_ms"] = sample_interval_ms
     else:
-        result = ableton.send_command("get_track_meters", params)
+        result = await asyncio.to_thread(ableton.send_command, "get_track_meters", params)
         if not isinstance(result, dict):
             return result
 
     # Probe playback state once so we can annotate the response
     try:
-        session = ableton.send_command("get_session_info", {})
+        session = await asyncio.to_thread(ableton.send_command, "get_session_info", {})
         is_playing = bool(session.get("is_playing", False))
     except Exception:
         is_playing = None  # unknown — leave left/right as reported