ableton-mcp-ai/KIMI_K2_CODEBASE_FIXES.md

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:

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:

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.