# AbletonMCP_AI v2.0 - Clean Rewrite

> MCP-based system for controlling Ableton Live 12 Suite from AI agents.
> **Rewritten from scratch** - Clean, simple, functional.

## Architecture

```
┌─────────────────────────────────────────┐
│  OpenCode / MCP Clients                 │
├─────────────────────────────────────────┤
│  Layer 1: MCP Server (server.py ~300ln) │  ← FastMCP, stdio transport
│  Layer 2: Engines (engines/*.py)        │  ← Music logic, sample selection
│  Layer 3: Remote Script (runtime.py)   │  ← Ableton Live API, TCP socket
│  Layer 4: Ableton Live 12 Suite        │
└─────────────────────────────────────────┘
```

## Key Design Decisions

1. **Simple TCP socket** - One connection per command, no persistent state
2. **No main thread queue** - Uses Live's `update_display()` callback directly
3. **Clean error handling** - Every command returns `{status, result/error}`
4. **Minimal code** - ~300 lines for runtime, ~300 for server (vs 5400+13800 before)
5. **Reusable engines** - Music logic isolated from communication layer

## Available Tools (28)

### Info
- `get_session_info` - Project state (tempo, tracks, scenes)
- `get_tracks` - All tracks info
- `get_scenes` - All scenes
- `get_master_info` - Master track

### Transport
- `start_playback` / `stop_playback` / `toggle_playback`
- `stop_all_clips`

### Settings
- `set_tempo` - BPM (20-300)
- `set_time_signature` - Numerator/denominator
- `set_metronome` - On/off

### Tracks
- `create_midi_track` / `create_audio_track`
- `set_track_name` / `set_track_volume` / `set_track_pan`
- `set_track_mute` / `set_track_solo`
- `set_master_volume`

### Clips & Sessions
- `create_clip` - MIDI clip in Session View
- `add_notes_to_clip` - Add MIDI notes
- `fire_clip` / `fire_scene`
- `set_scene_name` / `create_scene`

### Arrangement View
- `create_arrangement_audio_pattern` - Load .wav clips
- `load_sample_to_drum_rack` - Load sample into Drum Rack

### Generation
- `generate_track` / `generate_song` - AI generation
- `select_samples_for_genre` - Auto sample selection

## Setup

### 1. Ableton Live Configuration
1. Open Ableton Live 12 Suite
2. Go to **Preferences → Link/Tempo/MIDI**
3. Under **Control Surfaces**, add **AbletonMCP_AI**
4. The Remote Script will start listening on port 9877

### 2. OpenCode Configuration
Already configured in `~/.config/opencode/opencode.json`:
```json
{
  "mcp": {
    "ableton-live-mcp": {
      "type": "local",
      "command": ["python", "C:\\ProgramData\\Ableton\\Live 12 Suite\\Resources\\MIDI Remote Scripts\\mcp_wrapper.py"],
      "enabled": true,
      "timeout": 300000
    }
  }
}
```

### 3. Sample Library
Your reggaeton library at `libreria/reggaeton/` is automatically indexed (509 samples).

## File Structure
```
AbletonMCP_AI/
├── __init__.py          # Live Control Surface entry point
├── runtime.py           # Remote Script (~300 lines)
└── mcp/
    ├── __init__.py
    ├── server.py        # MCP FastMCP server (~300 lines)
    ├── engines/
    │   ├── __init__.py
    │   ├── sample_selector.py  # Sample indexing & selection
    │   └── song_generator.py   # Track generation
    ├── tests/           # Unit tests
    └── docs/            # Documentation
```

## Commands

### Compile Check
```powershell
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\runtime.py"
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\mcp\server.py"
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\mcp_wrapper.py"
```

### Test MCP Server
```powershell
python "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\mcp_wrapper.py" --transport stdio
```

## Troubleshooting

### Connection Refused
- Ensure AbletonMCP_AI is loaded as a Control Surface in Live
- Check port 9877: `netstat -an | findstr 9877`
- Restart Ableton Live after code changes

### Timeout on Commands
- Commands that mutate Live state use 30s timeout by default
- Generation commands use 300s timeout
- Check Ableton log for errors

### Sample Selection Returns Empty
- Verify `libreria/reggaeton/` exists with .wav files
- Check sample index: should show "Indexed X samples" in logs