livemcp 1.1.0__tar.gz

livemcp-1.1.0/.claude/skills/README.md

@@ -0,0 +1,9 @@
+# LiveMCP Claude Skills
+
+Project-specific skills for Ableton Live MCP development.
+
+| Skill | When to use |
+|-------|-------------|
+| `/verify` | Before every commit — tests, tool count check |
+| `/restart-ableton` | After modifying remote script files |
+| `/publish` | Publish new version to PyPI |

livemcp-1.1.0/.claude/skills/publish.md

@@ -0,0 +1,45 @@
+# /publish — Publish to PyPI
+
+Release a new version of livemcp.
+
+## Pre-flight
+
+1. Run `/verify` first
+2. Test with Ableton Live (run `/restart-ableton` + verify all 171 tools work)
+3. Update version in `pyproject.toml`
+4. Update CHANGELOG or README with new features/fixes
+5. Commit: `git commit -m "Bump version to X.Y.Z"`
+6. Tag: `git tag vX.Y.Z`
+7. Push: `git push && git push --tags`
+
+## Build and Publish
+
+```bash
+# Clean previous builds
+rm -rf dist/
+
+# Build package
+uv build
+
+# Check package contents
+tar tzf dist/livemcp-*.tar.gz
+
+# Publish to PyPI (requires API token)
+uv publish
+```
+
+## Verify Publication
+
+```bash
+# Install from PyPI
+uvx livemcp@X.Y.Z
+
+# Should connect to Ableton on port 9877
+# Test with Claude Desktop or Claude Code
+```
+
+## Rollback
+
+PyPI doesn't allow deleting versions. If bad release:
+1. Publish a new patch version (X.Y.Z+1)
+2. Update docs/README to skip the broken version

livemcp-1.1.0/.claude/skills/restart-ableton.md

@@ -0,0 +1,58 @@
+# /restart-ableton — Restart Ableton Live
+
+Critical procedure after modifying remote script files. Clears Python bytecode cache so Ableton loads fresh code.
+
+## Quick Version
+
+```bash
+bash scripts/restart_ableton.sh
+```
+
+## Manual Steps (if script fails)
+
+```bash
+# 1. Clear bytecode cache
+find /home/alaarab/Sites/livemcp/remote_script -name "__pycache__" -type d -exec rm -rf {} + 2>/dev/null
+
+# 2. Quit Ableton
+osascript -e 'tell application "Ableton Live 12 Suite" to quit'
+sleep 2
+
+# 3. Dismiss save dialog
+osascript -e 'tell application "System Events" to tell process "Ableton Live 12 Suite" to if exists window 1 then click button "Don'\''t Save" of window 1' 2>/dev/null
+
+# 4. Wait for exit (max 15s)
+for i in $(seq 1 15); do
+  pgrep -x "Ableton Live" > /dev/null 2>&1 || break
+  sleep 1
+done
+
+# 5. Force kill if hanging
+pgrep -x "Ableton Live" > /dev/null 2>&1 && pkill -9 -x "Ableton Live" && sleep 2
+
+# 6. Relaunch
+open -a "Ableton Live 12 Suite"
+
+# 7. Dismiss "unexpectedly quit" dialog (poll for 10s)
+for i in $(seq 1 10); do
+  osascript -e 'tell application "System Events" to tell process "Ableton Live 12 Suite" to if exists window 1 then click button "Reopen" of window 1' 2>/dev/null && break
+  sleep 1
+done
+
+# 8. Wait for LiveMCP socket (port 9877)
+for i in $(seq 1 30); do
+  python3 -c "import socket; s=socket.socket(); s.settimeout(2); s.connect(('127.0.0.1', 9877)); s.close()" 2>/dev/null && break
+  sleep 3
+done
+```
+
+## Verify
+
+1. Check Ableton status bar: "LiveMCP: Server started on port 9877"
+2. Test MCP server: `uvx livemcp` (should connect)
+
+## Common Issues
+
+- **Cache not cleared**: Ableton loads old .pyc files → always clear `__pycache__` first
+- **Save dialog blocks**: Script clicks "Don't Save" automatically
+- **Socket timeout**: Takes 15-30s for port 9877 to be ready after launch

livemcp-1.1.0/.claude/skills/verify.md

@@ -0,0 +1,49 @@
+# /verify — Pre-Commit Gate
+
+Run before `git commit`. Tests and tool registration check.
+
+## Steps
+
+### 1. Tool Count
+```bash
+uv run python -c "from livemcp.server import mcp; print(f'{len(mcp._tool_manager._tools)} tools registered')"
+```
+✅ 171 tools | ❌ If count is wrong, check server.py registrations
+
+### 2. Syntax Check (all Python files)
+```bash
+find . -name "*.py" -not -path "./.venv/*" | xargs -I{} python3 -c "import py_compile; py_compile.compile('{}', doraise=True)"
+```
+✅ All files valid | ❌ Report syntax errors
+
+### 3. Lint (Ruff)
+```bash
+uv run ruff check src/livemcp/
+```
+✅ Clean | ❌ Fix with `uv run ruff check --fix src/livemcp/`
+
+### 4. Git Status
+```bash
+git status
+```
+✅ No `.env` or credentials in staging
+
+### 4. Remote Script Check
+```bash
+ls -l ~/Music/"Ableton/User Library/Remote Scripts/LiveMCP/" | grep __init__
+```
+✅ Symlink intact | ⚠️ If broken, run `./scripts/install.sh`
+
+## Output
+
+```
+/verify Report
+
+1. Tools        ✅ 171 tools registered
+2. Syntax       ✅ All Python files valid
+3. Lint         ✅ Ruff clean
+4. Git status   ✅ Clean
+5. Remote script ✅ Symlink intact
+
+RESULT: ✅ SAFE TO COMMIT
+```

livemcp-1.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+.env
+.DS_Store
+*.so
+.ruff_cache/
+.pytest_cache/

livemcp-1.1.0/CLAUDE.md

@@ -0,0 +1,210 @@
+# LiveMCP — Claude Code Instructions
+
+## Project Overview
+
+LiveMCP is a Model Context Protocol (MCP) bridge that exposes Ableton Live's internal Python API to AI assistants. Version 1.0.0, published on PyPI as `livemcp`, invoked via `uvx livemcp`.
+
+It provides 171 tools across 7 categories: session, clips, tracks, devices, mixer, arrangement, grooves.
+
+macOS only. The remote script relies on Ableton's macOS application bundle structure and the osascript-based install/restart scripts target macOS paths exclusively.
+
+## Architecture
+
+LiveMCP has two components that must stay in sync:
+
+**MCP Server (`src/livemcp/`)** — Python 3.10+, FastMCP, communicates with Ableton over a TCP socket.
+
+- `src/livemcp/server.py` — FastMCP instance, registers all tools
+- `src/livemcp/connection.py` — singleton TCP connection to Ableton
+- `src/livemcp/tools/` — one module per category, each exports a `TOOLS` list of functions
+
+**Remote Script (`remote_script/LiveMCP/`)** — Runs inside Ableton Live's embedded Python 3.11 interpreter as a MIDI Remote Script (extends `ControlSurface`).
+
+- `remote_script/LiveMCP/server.py` — TCP server, command dispatcher
+- `remote_script/LiveMCP/handlers/` — one module per category, each exports `READ_HANDLERS` and `WRITE_HANDLERS` dicts
+
+## Connection Details
+
+- Host: `127.0.0.1`, Port: `9877`
+- Singleton: one `AbletonConnection` instance shared across all tool calls (thread-safe via `threading.Lock`)
+- Timeout: 15 seconds per command
+- Retries: 3 attempts with 1-second delay between attempts
+- Validation: on first connect, `get_session_info` is sent as a ping to confirm the remote script is ready
+
+## READ vs WRITE Handler Threading Model
+
+This is the most important rule when adding handlers in `remote_script/LiveMCP/handlers/`:
+
+- **READ_HANDLERS** run directly on the socket thread. Safe for reading Live object properties.
+- **WRITE_HANDLERS** are dispatched to Ableton's main thread via `schedule_message`. Required for any mutation of Live's object model (setting properties, calling methods that modify state).
+
+**Putting a write operation in READ_HANDLERS will crash or corrupt Ableton's state.** When in doubt, use WRITE_HANDLERS.
+
+## Adding a New Tool
+
+Adding a tool requires changes in four places:
+
+**Step 1 — Add the tool function** in `src/livemcp/tools/<category>.py`:
+
+```python
+def my_new_tool(track_index: int, value: float) -> str:
+    """One-line summary for the AI assistant.
+
+    Args:
+        track_index: Zero-based track index.
+        value: The value to set.
+    """
+    result = get_connection().send_command("my_new_tool", {
+        "track_index": track_index,
+        "value": value,
+    })
+    return json.dumps(result)
+```
+
+**Step 2 — Append to TOOLS list** at the bottom of the same file:
+
+```python
+TOOLS = [
+    # ... existing tools ...
+    my_new_tool,
+]
+```
+
+**Step 3 — Add the handler** in `remote_script/LiveMCP/handlers/<category>.py`:
+
+```python
+def my_new_tool(control_surface, params):
+    track_index = params.get("track_index")
+    value = params.get("value")
+    if track_index is None or value is None:
+        raise ValueError("Missing required parameters")
+    song = control_surface.song()
+    track = song.tracks[track_index]
+    # mutate state here
+    return {"ok": True}
+```
+
+**Step 4 — Register in READ_HANDLERS or WRITE_HANDLERS** in the same handler file:
+
+```python
+READ_HANDLERS = {
+    # read-only: runs on socket thread
+    "get_something": get_something,
+}
+
+WRITE_HANDLERS = {
+    # state mutation: queued to Ableton's main thread
+    "my_new_tool": my_new_tool,
+}
+```
+
+The command string (e.g. `"my_new_tool"`) must be identical in `send_command(...)` and the handler dict key.
+
+## Project Structure
+
+```
+src/livemcp/
+    server.py           # FastMCP instance, registers all tools from TOOLS lists
+    connection.py       # AbletonConnection singleton, send_command()
+    tools/
+        session.py      # tempo, transport, time signature, cue points
+        tracks.py       # create/delete/rename tracks, arm, solo, mute
+        clips.py        # create clips, add notes, quantize, warp
+        devices.py      # load instruments/effects, device parameters
+        mixer.py        # volume, pan, send levels, routing
+        arrangement.py  # arrangement view clips
+        grooves.py      # groove pool
+
+remote_script/LiveMCP/
+    __init__.py         # ControlSurface entry point
+    server.py           # TCP server + dispatcher (READ vs WRITE routing)
+    handlers/
+        __init__.py     # aggregates all READ/WRITE handler dicts
+        session.py
+        tracks.py
+        clips.py
+        devices.py
+        mixer.py
+        arrangement.py
+        grooves.py
+
+scripts/
+    install.sh          # symlinks remote_script/LiveMCP into Ableton's MIDI Remote Scripts dir
+    uninstall.sh        # removes the symlink from all detected Ableton versions
+    restart_ableton.sh  # full restart procedure (cache clear, quit, relaunch, wait for socket)
+```
+
+## Restarting Ableton Live
+
+When you need to restart Ableton (e.g. after modifying remote script files), **always** use this procedure:
+
+```bash
+# 1. Clear bytecode cache so Ableton loads fresh Python
+find /home/alaarab/Sites/livemcp/remote_script -name "__pycache__" -type d -exec rm -rf {} + 2>/dev/null
+
+# 2. Gracefully quit (sends save dialog — dismiss it)
+osascript -e 'tell application "Ableton Live 12 Suite" to quit'
+
+# 3. Dismiss any "Save" dialog that appears
+sleep 2
+osascript -e 'tell application "System Events" to tell process "Ableton Live 12 Suite" to if exists window 1 then click button "Don'\''t Save" of window 1' 2>/dev/null
+
+# 4. Wait for process to fully exit
+for i in $(seq 1 15); do
+  pgrep -x "Ableton Live" > /dev/null 2>&1 || break
+  sleep 1
+done
+
+# 5. Force kill if it's still hanging
+pgrep -x "Ableton Live" > /dev/null 2>&1 && pkill -9 -x "Ableton Live" && sleep 2
+
+# 6. Relaunch
+open -a "Ableton Live 12 Suite"
+
+# 7. Dismiss "unexpectedly quit" dialog if it appears (poll for a few seconds)
+for i in $(seq 1 10); do
+  osascript -e 'tell application "System Events" to tell process "Ableton Live 12 Suite" to if exists window 1 then click button "Reopen" of window 1' 2>/dev/null && break
+  sleep 1
+done
+
+# 8. Wait for LiveMCP socket to be ready
+for i in $(seq 1 30); do
+  python3 -c "import socket; s=socket.socket(); s.settimeout(2); s.connect(('127.0.0.1', 9877)); s.close()" 2>/dev/null && break
+  sleep 3
+done
+```
+
+Or use the helper script: `bash scripts/restart_ableton.sh`
+
+### Important Notes
+
+- **Always clear `__pycache__`** before restarting — Ableton caches .pyc files and won't see your changes otherwise
+- The "unexpectedly quit" dialog appears if the previous quit wasn't clean. The script handles this automatically.
+- The "Save?" dialog appears on graceful quit. The script clicks "Don't Save" — if you need to save, do it manually first.
+- Socket on port 9877 typically takes 15-30 seconds after launch to become available.
+
+## Verification After Changes
+
+```bash
+# Syntax check all Python files
+find . -name "*.py" -not -path "./.venv/*" | xargs -I{} python3 -c "import py_compile; py_compile.compile('{}', doraise=True)"
+
+# Verify registered tool count (target: 171)
+uv run python -c "from livemcp.server import mcp; print(len(mcp._tool_manager._tools), 'tools')"
+
+# Lint with ruff (line-length 100, configured in pyproject.toml)
+uv run ruff check src/livemcp/
+```
+
+## Code Style
+
+Ruff is the linter. Line length is 100, configured in `pyproject.toml` under `[tool.ruff]`. Run `uv run ruff check src/livemcp/` before committing. Run `uv run ruff format src/livemcp/` to auto-format.
+
+## Known API Gotchas
+
+- `MidiNoteSpecification`: must use constructor kwargs, NOT attribute setting
+- `apply_note_modifications`: pass the original tuple from `get_notes_extended`, don't convert to list
+- `quantize_clip` grid: must be int, not float
+- Mixer zero-value: never use `params.get("x") or params.get("y")` — use explicit None checks (0.0 is falsy)
+- `scene.tempo`: can't set to -1.0 to clear; use `scene.tempo_enabled = False` instead
+- `clip.groove = None` doesn't work; groove removal is an API limitation

livemcp-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ala Arab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.