# QWEN.md - AbletonMCP_AI v2.0

> **Context**: MCP-based system for controlling Ableton Live 12 from AI agents.
> **Rewritten**: 2026-04-11 - Clean rewrite from scratch.
> **Team**: Qwen (verify/debug/architecture) + Kimi (fast coding)

## CRITICAL RULES (READ FIRST)

1. **NEVER touch `libreria/` or `librerias/`** - User's sample library. NEVER delete, move, or modify.
2. **NEVER delete project files** - Overwrite, don't delete then create.
3. **NEVER create debug .md files in project root** - All docs go in `AbletonMCP_AI/docs/`.
4. **NEVER use `rmdir /s /q` except for `__pycache__`** - Can accidentally delete the whole project.
5. **NEVER modify Ableton's built-in scripts** - `_Framework`, `_APC`, etc. are not yours.
6. **ALWAYS compile after changes**: `python -m py_compile "<file_path>"`
7. **ALWAYS restart Ableton Live** after changes to `__init__.py`

## Architecture

```
AbletonMCP_AI/
├── __init__.py          # Remote Script (ALL code in one file)
├── README.md            # Documentation
├── docs/                # Sprints and project docs
└── mcp_server/
    ├── server.py        # MCP FastMCP server (stdio)
    └── engines/
        ├── sample_selector.py  # Sample indexing
        └── song_generator.py   # Track generation
```

## Key Files

| File | Purpose | Lines |
|------|---------|-------|
| `__init__.py` | Ableton Remote Script | ~300 |
| `mcp_server/server.py` | MCP Server | ~300 |
| `mcp_server/engines/sample_selector.py` | Sample selection | ~150 |
| `mcp_server/engines/song_generator.py` | Song generation | ~120 |
| `mcp_wrapper.py` | Launcher | ~15 |

## Setup Commands

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

### Test Connection
```powershell
netstat -an | findstr 9877
```

## Available MCP Tools (30)

### Info
`get_session_info`, `get_tracks`, `get_scenes`, `get_master_info`

### Transport
`start_playback`, `stop_playback`, `toggle_playback`, `stop_all_clips`

### Settings
`set_tempo`, `set_time_signature`, `set_metronome`

### 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`, `add_notes_to_clip`, `fire_clip`, `fire_scene`,
`set_scene_name`, `create_scene`

### Arrangement & Samples
`create_arrangement_audio_pattern`, `load_sample_to_drum_rack`

### Generation
`generate_track`, `generate_song`, `select_samples_for_genre`

## Sample Library
- **Location**: `libreria/reggaeton/`
- **509 indexed samples** in kick/, snare/, bass/, fx/, drumloops/, oneshots/, etc.