# Kimi K2 Handoff: Codigo Fuente y Qué Hay Que Arreglar

IMPORTANT:

Read these files first:

1. `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\KIMI_K2_START_HERE.md`
2. `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\KIMI_K2_ACTIVE_HANDOFF.md`

This document is now historical context.

Some statements below are outdated because the project moved forward.
Examples of things that changed after this document was written:

- the active runtime now prefers `abletonmcp_init.py`
- `server.py` no longer has duplicate MCP tool registrations

Use this file for background only, not as the first source of truth.

## Objetivo

Este documento es un handoff tecnico para que Kimi K2 pueda entrar al proyecto sin perder tiempo en arboles duplicados ni archivos muertos. El foco es el codigo fuente que afecta al MCP, al Remote Script de Ableton y a la generacion musical.

## Alcance leido

Leido/inventariado en este workspace:

- `300` archivos de codigo/config/docs detectados por extension.
- `122` archivos bajo `AbletonMCP_AI`.
- `56` archivos dentro del arbol backup `AbletonMCP_AI_BAK_20260328_200801`.
- `40` modulos Python en el arbol activo `AbletonMCP_AI/AbletonMCP_AI/MCP_Server`.

El arbol activo del MCP Server contiene estos modulos:

- Core: `server.py`, `server_v2.py`, `start_server.py`, `__init__.py`
- Generacion: `song_generator.py`, `human_feel.py`, `enhanced_device_automation.py`, `full_integration.py`, `self_ai.py`, `validation_system_fix.py`
- Samples/audio: `sample_index.py`, `sample_manager.py`, `sample_selector.py`, `audio_analyzer.py`, `audio_arrangement.py`, `audio_fingerprint.py`, `audio_key_compatibility.py`, `audio_mastering.py`, `audio_organizer.py`, `audio_resampler.py`, `audio_soundscape.py`, `reference_listener.py`, `reference_stem_builder.py`, `role_matcher.py`, `vector_manager.py`, `segment_rag_builder.py`
- Diagnostico/QA: `socket_smoke_test.py`, `health_check.py`, `benchmark.py`, `retrieval_benchmark.py`, `sample_system_demo.py`, `scan_audio.py`, `template_analyzer.py`, `validate_key_detection.py`
- Tests: `tests/test_human_feel.py`, `tests/test_integration.py`, `tests/test_sample_selector.py`

## Source Of Truth Real

Hoy el sistema no tiene una sola fuente de verdad.

### Claude Code y opencode

- `/.mcp.json` y `/opencode.json` apuntan a `/mcp_wrapper.py`
- `/mcp_wrapper.py` resuelve el codigo y termina levantando:
  - `/AbletonMCP_AI/AbletonMCP_AI/MCP_Server/server.py`

### Ableton Live

- Ableton carga:
  - `/AbletonMCP_AI/__init__.py`
  - `/AbletonMCP_AI/Remote_Script.py`
- Ambos son shims.
- Esos shims priorizan:
  - `/AbletonMCP_AI/AbletonMCP_AI_BAK_20260328_200801/Remote_Script.py`
- Solo si eso no existe, hacen fallback a:
  - `/abletonmcp_init.py`

### Consecuencia

El MCP de Claude/opencode usa una implementacion y Ableton Live ejecuta otra. Ese desacople es hoy el problema principal del proyecto.

## Hallazgos Verificados

### P0. El runtime activo de Ableton sigue siendo un backup

Archivos:

- `/AbletonMCP_AI/__init__.py`
- `/AbletonMCP_AI/Remote_Script.py`

Ambos cargan primero `AbletonMCP_AI_BAK_20260328_200801/Remote_Script.py`. Mientras eso siga asi:

- los arreglos hechos en `abletonmcp_init.py` no son necesariamente los que corre Live
- el MCP Server y el Remote Script evolucionan por caminos distintos
- Kimi K2 puede editar el archivo "correcto" y no mover el runtime real

### P0. `generate_track` hace que Ableton entre en `Audio queue timeout`

Evidencia observada en `C:\Users\ren\AppData\Roaming\Ableton\Live 12.0.15\Preferences\Log.txt`:

- `Comando recibido: generate_track`
- ~3 segundos despues: `Internal Error: From 5 to Audio queue timeout.`

Esto ya no es un problema de deteccion del puerto ni de MCP handshake. Es un problema de ejecucion del Remote Script dentro de Live.

Hipotesis mas fuerte y consistente con el codigo:

- el Remote Script activo ejecuta operaciones largas de Live API durante `generate_track`
- parte de ese trabajo se hace en el hilo principal de Live en bloques demasiado grandes
- Live se queda sin respuesta y termina cerrando la conexion o entrando en recovery

Archivos involucrados:

- `/AbletonMCP_AI/AbletonMCP_AI_BAK_20260328_200801/Remote_Script.py`
- `/abletonmcp_init.py`

### P0. Hay dos topologias del repo compitiendo al mismo tiempo

`git status --short` muestra sintomas de reubicacion parcial:

- muchos archivos aparecen como `D AbletonMCP_AI/MCP_Server/...`
- al mismo tiempo hay archivos nuevos bajo `?? AbletonMCP_AI/AbletonMCP_AI/...`

Eso significa que el repo quedo en una migracion a medias:

- arbol viejo borrado
- arbol nuevo agregado
- wrappers y scripts mezclados entre ambos

Hasta normalizar esto, cualquier agente se puede equivocar de path.

### P1. `server_v2.py` no compila

Comando usado:

```powershell
python -m compileall AbletonMCP_AI\AbletonMCP_AI\MCP_Server
```

Error objetivo:

- `/AbletonMCP_AI/AbletonMCP_AI/MCP_Server/server_v2.py`
- `SyntaxError: name '_ableton_connection' is used prior to global declaration`

El mismo error existe en la copia backup:

- `/AbletonMCP_AI/AbletonMCP_AI_BAK_20260328_200801/MCP_Server/server_v2.py`

`server_v2.py` hoy es codigo muerto o roto. No debe usarse como base hasta corregirlo o retirarlo.

### P1. `server.py` registra tools duplicadas

Chequeo AST sobre el archivo activo:

- `93` tools registradas
- `85` nombres unicos

Duplicados confirmados:

- `apply_clip_fades`
- `apply_sidechain_pump`
- `generate_with_human_feel`
- `humanize_set`
- `inject_pattern_fills`
- `reset_diversity_memory`
- `suggest_key_change`
- `write_volume_automation`

Archivo:

- `/AbletonMCP_AI/AbletonMCP_AI/MCP_Server/server.py`

Esto explica los warnings de duplicados y hace mas dificil mantener el contrato MCP.

### P1. `song_generator.py` tiene helpers duplicados

Duplicados detectados en el mismo archivo:

- `_get_pattern_variant_penalty`
- `_record_pattern_variant_usage`
- `_decay_pattern_variant_memory`
- `reset_pattern_variant_memory`

Archivo:

- `/AbletonMCP_AI/AbletonMCP_AI/MCP_Server/song_generator.py`

No necesariamente rompe en runtime, pero hace el comportamiento ambiguo y facilita regresiones.

### P1. Hay mojibake/encoding roto en varios modulos

Ejemplos visibles:

- `género`
- `raíz`
- `química`
- `Integración`

Archivos con señales claras:

- `/AbletonMCP_AI/AbletonMCP_AI/MCP_Server/song_generator.py`
- `/AbletonMCP_AI/AbletonMCP_AI/MCP_Server/server_v2.py`
- `/AbletonMCP_AI/AbletonMCP_AI_BAK_20260328_200801/Remote_Script.py`
- algunos scripts utilitarios legacy

Esto afecta:

- logs
- descripciones de tools
- prompts internos
- mantenibilidad general

### P1. `start_server.py` apunta a paths viejos

Archivo:

- `/AbletonMCP_AI/AbletonMCP_AI/MCP_Server/start_server.py`

Problema:

- hace `chdir` e `insert` de `PYTHONPATH` a `AbletonMCP_AI\MCP_Server`
- ese ya no es el arbol real usado por `mcp_wrapper.py`

Conclusion:

- es un entrypoint obsoleto
- puede levantar el codigo equivocado

### P1. Hay mas de un servidor MCP en el repo

Servidores detectados:

- `/AbletonMCP_AI/AbletonMCP_AI/MCP_Server/server.py` -> FastMCP real
- `/AbletonMCP_AI/AbletonMCP_AI/MCP_Server/server_v2.py` -> roto
- `/mcp_1429/server.py` -> servidor de prueba con tool `hola`
- `/AbletonMCP_AI/mcp_1429/server.py` -> misma idea, duplicado
- `/abletonmcp_server.py` -> servidor FastMCP legacy en root

Esto no es necesariamente un bug funcional inmediato, pero si es deuda tecnica fuerte. Un nuevo agente puede arrancar el servidor incorrecto muy facil.

### P1. El Remote Script backup tiene warning por string mal escapado

Durante `compileall` aparecio:

- `SyntaxWarning: "\P" is an invalid escape sequence`

Archivo:

- `/AbletonMCP_AI/AbletonMCP_AI_BAK_20260328_200801/Remote_Script.py`

No es el crash principal, pero confirma que ese runtime backup no esta limpio.

### P2. Tests existen pero no hay runner disponible en el entorno actual

Intento realizado:

```powershell
python -m pytest -q
```

Resultado:

- `No module named pytest`

Hay tests, pero hoy no existe una via reproducible de correrlos desde este entorno Windows tal como esta.

### P2. Hay muchas rutas absolutas hardcodeadas

Ejemplos:

- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\...`
- `127.0.0.1:9877`
- scripts root que asumen layout fijo

Archivos afectados:

- `start_server.py`
- `place_perc_audio.py`
- `scan_audio.py`
- scripts socket de root
- shims y wrappers

Esto vuelve fragil cualquier cambio de layout.

### P2. Hay scripts auxiliares legacy que usan protocolos viejos o parciales

Ejemplos:

- `/generate_song.py`
- `/generate_track.py`
- `/fix_connection.py`
- `/check_status.py`
- `/temp_socket_cmd.py`
- `/validate_script.py`

No parecen ser la ruta principal del producto, pero si se usan para diagnostico pueden inducir falsos positivos porque mezclan comandos legacy y supuestos viejos.

## Recomendacion De Arquitectura Para Kimi K2

### 1. Elegir una sola implementacion canonica del Remote Script

Recomendacion:

- convertir `/abletonmcp_init.py` en runtime canonico
- mover a ese runtime los aliases y la logica minima que hoy existen solo en el backup
- cambiar `/AbletonMCP_AI/__init__.py` y `/AbletonMCP_AI/Remote_Script.py` para que carguen primero `abletonmcp_init.py`
- dejar `AbletonMCP_AI_BAK_20260328_200801` fuera del path activo

Razon:

- `abletonmcp_init.py` ya tiene un modelo mas ordenado de `schedule_message` + cola de respuesta para comandos Live API
- el backup hoy concentra la logica que esta rompiendo Live

### 2. Hacer que MCP Server y Remote Script compartan el mismo contrato

Contrato minimo que debe quedar estable:

- `get_session_info`
- `get_tracks`
- `get_all_tracks`
- `create_track`
- `create_midi_track`
- `create_audio_track`
- `create_clip`
- `add_notes_to_clip`
- `add_notes`
- `play`
- `stop`
- `start_playback`
- `stop_playback`
- `generate_track`

No depender de traducciones ambiguas si el runtime no las soporta de verdad.

### 3. Rehacer `generate_track` para no bloquear el hilo de Live

Objetivo:

- nunca correr toda la generacion en un solo bloque de hilo principal
- hacer operaciones pequenas sobre Live API
- si hay trabajo pesado de CPU o de planificacion, dejarlo fuera del hilo principal

Patron recomendado:

- planificacion/configuracion fuera del hilo principal
- mutaciones de Live via `schedule_message` o cola, una operacion corta por vez
- evitar bloques largos de `delete/create/load browser/add notes` en una sola llamada monolitica

### 4. Limpiar duplicados de `server.py`

Hay que dejar un solo registro por tool y una sola definicion por helper. Mientras haya 93 registros para 85 tools:

- los warnings van a seguir
- el contrato MCP va a seguir siendo ambiguo

### 5. Retirar o aislar codigo muerto

Mover fuera del camino activo o documentar como obsoleto:

- `server_v2.py`
- `mcp_1429/`
- `abletonmcp_server.py`
- scripts utilitarios legacy del root
- arbol backup una vez migrado lo necesario

## Orden Recomendado De Trabajo

1. Congelar la topologia del repo y definir `source of truth`
2. Cambiar los shims de Ableton para dejar de cargar el backup primero
3. Portar/ajustar los comandos faltantes al runtime canonico
4. Arreglar `generate_track` con mutaciones cortas y seguras para Live
5. Limpiar tools duplicadas en `server.py`
6. Borrar o archivar `server_v2.py` si no se va a rescatar
7. Normalizar encoding UTF-8 sin mojibake
8. Reemplazar rutas absolutas innecesarias por resolucion relativa
9. Crear una verificacion reproducible

## Validacion Minima Que Kimi K2 Tiene Que Poder Dejar

### MCP

- `claude mcp list` muestra `ableton-mcp-ai` conectado
- `opencode mcp list` muestra `ableton-mcp-ai` conectado
- `initialize` y `tools/list` devuelven la lista esperada sin warnings de duplicados

### Socket Ableton

- `get_session_info` responde en menos de 2s
- `get_tracks` responde estable
- `create_midi_track` y `create_clip` no cierran Live

### Generacion

- `generate_track(genre=\"reggaeton\", bpm=92, key=\"Dm\", style=\"perreo\", structure=\"standard\")`
- no produce `Audio queue timeout`
- no cierra Ableton
- devuelve respuesta MCP valida

## Que No Hacer

- No editar primero `server_v2.py` como si fuera el entrypoint principal
- No confiar en el backup como fuente de verdad de largo plazo
- No tocar solo `server.py` del MCP esperando que eso arregle Live
- No dejar wrappers apuntando a un arbol y Live cargando otro

## Resumen Ejecutivo

El problema real ya no es "Claude no ve el MCP" ni "Ableton no escucha en 9877". El problema real es de arquitectura:

- MCP y Live corren implementaciones distintas
- Live sigue cargando un runtime backup
- `generate_track` bloquea o satura el hilo de Live
- el repo tiene duplicados, tools duplicadas y codigo legacy compitiendo

Si Kimi K2 arregla eso en ese orden, el resto pasa de caos operativo a mantenimiento normal.