# Ableton MCP AI

Sistema MCP + Remote Script para controlar Ableton Live 12 desde clientes tipo Claude Code, Codex y opencode, con foco en generacion musical y flujo de produccion en Arrangement View.

## Estado actual

- Wrapper estable por `stdio` para Claude Code, Codex y opencode.
- Remote Script `AbletonMCP_AI` cargable desde `Preferences > Link/Tempo/MIDI > Control Surface`.
- Runtime canonico en `abletonmcp_init.py` con fallback desde `AbletonMCP_AI/__init__.py`.
- MCP server en `AbletonMCP_AI/AbletonMCP_AI/MCP_Server/server.py`.
- Generacion de canciones y tracks con fallback de audio en Arrangement.
- Seleccion de samples endurecida para reggaeton usando la libreria local del usuario.
- Pack brain y jueces externos preparados para trabajar con Z.ai via API Anthropic-compatible.

## Que contiene este repo

- `AbletonMCP_AI/`
  Remote Script entrypoint, runtime espejo y paquete principal.
- `AbletonMCP_AI/AbletonMCP_AI/MCP_Server/`
  Servidor MCP, generador musical, seleccion de samples, jobs async y utilidades.
- `_Framework/`
  Shim minimo necesario para que el runtime no dependa de imports rotos de `ableton.v2`.
- `abletonmcp_init.py`
  Runtime canonico que corre dentro de Ableton Live.
- `mcp_wrapper.py`
  Launcher estable para clientes MCP por `stdio`.
- `CLAUDE.md`
  Documentacion operativa para agentes.
- `KIMI_K2_START_HERE.md`
  Entrada minima y obligatoria para Kimi K2.
- `KIMI_K2_ACTIVE_HANDOFF.md`
  Handoff activo, simple y actualizado.
- `MCP_CLAUDE_OPENCODE_SETUP.md`
  Setup puntual para Claude Code y opencode.
- `docs/KNOWN_ISSUES.md`
  Problemas abiertos y limites reales.
- `docs/ROADMAP.md`
  Roadmap canonico del proyecto.
- `docs/TODO.md`
  Trabajo pendiente priorizado.

## Lo que no contiene

- La libreria privada del usuario en `libreria/reggaeton`.
- Audio generado, caches, embeddings pesados y logs.
- Recovery files, estados temporales y artefactos de ejecucion local.

## Requisitos

- Windows nativo.
- Ableton Live 12 instalado en:
  `C:\ProgramData\Ableton\Live 12 Suite\Program\Ableton Live 12 Suite.exe`
- Python accesible como `python`.
- Este repo ubicado dentro de:
  `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts`

## Arranque rapido

1. Copia el repo a `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts`.
2. Abre Ableton Live.
3. En `Preferences > Link/Tempo/MIDI`, selecciona `AbletonMCP_AI` como `Control Surface`.
4. Arranca el MCP con:

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

5. Para lanzamiento manual simple:

```bat
start_mcp.bat
```

## Configuracion de clientes

### Claude Code

Usa `.mcp.json` o config equivalente apuntando a:

```json
{
  "mcpServers": {
    "ableton-mcp-ai": {
      "type": "stdio",
      "command": "python",
      "args": [
        "C:/ProgramData/Ableton/Live 12 Suite/Resources/MIDI Remote Scripts/mcp_wrapper.py"
      ]
    }
  }
}
```

### Codex / opencode

Usa el mismo wrapper `mcp_wrapper.py` por `stdio`. Hay ejemplos ya preparados en `opencode.json`.

En esta maquina, las rutas activas son:

- Codex: `C:\Users\ren\.codex\config.toml`
- OpenCode global: `C:\Users\ren\.opencode.json`
- OpenCode local: `C:\Users\ren\.config\opencode\opencode.json`
- OpenCode proyecto: `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\opencode.json`

Todas deben apuntar al mismo entrypoint:

`C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\mcp_wrapper.py`

## Libreria de samples

La libreria principal usada durante las pruebas esta fuera del repo:

`C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\libreria\reggaeton`

El codigo esta preparado para trabajar con esa ruta local, pero no se publica por tamano y por contenido privado.

## Z.ai / jueces externos

Si quieres usar jueces externos y no solo heuristicas locales:

```powershell
$env:ANTHROPIC_BASE_URL = "https://api.z.ai/api/anthropic"
$env:ANTHROPIC_AUTH_TOKEN = "<token>"
$env:ANTHROPIC_MODEL = "glm-5.1"
```

El sistema usa fallback heuristico si la API no responde o devuelve rate limit.

## Flujo recomendado

1. Verifica socket y estado con `get_session_info`.
2. Usa `generate_song_async` o `generate_track_async` desde clientes MCP para evitar timeouts largos.
3. Si trabajas localmente desde Python, puedes invocar `server.generate_song(...)` directo.
4. Despues de generar, fuerza `show_arrangement_view`, `jump_to 0` y `start_playback`.

## Documentacion adicional

- `CLAUDE.md`
- `KIMI_K2_START_HERE.md`
- `KIMI_K2_ACTIVE_HANDOFF.md`
- `MCP_CLAUDE_OPENCODE_SETUP.md`
- `KIMI_K2_CODEBASE_FIXES.md`
- `KIMI_K2_NOTE_API_FIX.md`
- `docs/KNOWN_ISSUES.md`
- `docs/ROADMAP.md`
- `docs/TODO.md`

## Nota honesta

El sistema ya genera sets utilizables y estabilizo la conexion Live <-> MCP, pero todavia no esta en un punto de "produccion profesional sin supervision". El estado real y lo pendiente estan documentados en `docs/KNOWN_ISSUES.md` y `docs/TODO.md`.