366 lines
16 KiB
Markdown
366 lines
16 KiB
Markdown
# AbletonMCP-AI - Informe de Auditoria Completa
|
||
|
||
**Fecha:** 2026-04-02
|
||
**Autor:** Claude Code Audit Engine
|
||
**Alcance:** Todo el codigo fuente del proyecto AbletonMCP-AI
|
||
|
||
---
|
||
|
||
## 1. Resumen Ejecutivo
|
||
|
||
| Metrica | Valor |
|
||
|---|---|
|
||
| Archivos Python analizados | 43 |
|
||
| Lineas de codigo totales | ~75,000+ |
|
||
| Bugs criticos encontrados | 7 |
|
||
| Bugs moderados encontrados | 12 |
|
||
| Bugs menores encontrados | 15+ |
|
||
| Archivos basura identificados | 23 |
|
||
| Docs obsoletos identificados | 14 |
|
||
| Archivos duplicados | 5 |
|
||
| Codigo muerto/duplicado | 3 clases |
|
||
|
||
---
|
||
|
||
## 2. Bugs Criticos (DEBEN arreglarse)
|
||
|
||
### BUG-001: Import sin proteccion en linea 1 de server.py
|
||
- **Archivo:** `AbletonMCP_AI/AbletonMCP_AI/MCP_Server/server.py:1`
|
||
- **Problema:** `from human_feel import HumanFeelEngine` esta ANTES del docstring del modulo y SIN try/except. Si el modulo `human_feel` no esta disponible, el servidor entero crashea.
|
||
- **Impacto:** CRITICO - El server no arranca
|
||
- **Fix:** Mover dentro de un bloque try/except como los demas imports
|
||
|
||
### BUG-002: Shadowing de excepciones built-in de Python
|
||
- **Archivo:** `server.py:153,160,171`
|
||
- **Problema:** Las clases `ConnectionError`, `ValidationError` y `TimeoutError` sobreescriben las excepciones built-in de Python. Cualquier `except ConnectionError` o `except TimeoutError` en el codigo capturara la version custom, NO la built-in.
|
||
- **Impacto:** CRITICO - Bugs silenciosos en manejo de errores
|
||
- **Fix:** Renombrar a `MCPConnectionError`, `MCPValidationError`, `MCPTimeoutError`
|
||
|
||
### BUG-003: AbletonConnection.connect() es codigo muerto
|
||
- **Archivo:** `server.py:7364-7395`
|
||
- **Problema:** El metodo `connect()` crea `self.sock`, pero `send_command()` (linea 7430-7431) siempre desconecta `self.sock` primero y luego crea un socket LOCAL nuevo en linea 7454. El `self.sock` del connect() NUNCA se usa para enviar comandos.
|
||
- **Impacto:** ALTO - Confusion arquitectural, codigo muerto
|
||
|
||
### BUG-004: Funciones duplicadas identicas
|
||
- **Archivo:** `server.py:516-538`
|
||
- **Problema:** `_linear_to_live_slider()` y `_linear_to_live_slider_bus()` tienen implementaciones IDENTICAS. Los docstrings dicen cosas diferentes pero el codigo es el mismo (`clamped ** 0.5`).
|
||
- **Impacto:** MODERADO - Confusion, mantenimiento duplicado
|
||
- **Fix:** Eliminar `_linear_to_live_slider_bus` y usar `_linear_to_live_slider` en su lugar
|
||
|
||
### BUG-005: Clase HumanFeelEngine duplicada
|
||
- **Archivo:** `song_generator.py:5535` y `human_feel.py:8`
|
||
- **Problema:** `HumanFeelEngine` existe como clase independiente en `human_feel.py` Y como clase duplicada dentro de `song_generator.py`. El server.py importa desde `human_feel.py` (linea 1), pero `song_generator.py` usa su propia copia interna.
|
||
- **Impacto:** ALTO - Cambios en una no se reflejan en la otra
|
||
|
||
### BUG-006: server.py tiene 14,930 lineas
|
||
- **Archivo:** `server.py`
|
||
- **Problema:** El archivo es monolitico con casi 15,000 lineas. Esto viola principios de mantenibilidad y hace debugging extremadamente dificil.
|
||
- **Impacto:** ALTO - Deuda tecnica masiva
|
||
|
||
### BUG-007: 206 bloques except sin especificidad en server.py
|
||
- **Archivo:** `server.py`
|
||
- **Problema:** Se encontraron 206 ocurrencias de `except Exception` o patrones similares de except amplio. Muchos de estos silencian errores que deberian propagarse.
|
||
- **Impacto:** MODERADO - Bugs silenciosos, dificultad para debuggear
|
||
|
||
---
|
||
|
||
## 3. Bugs Moderados
|
||
|
||
### BUG-008: song_generator.py tambien es monolitico (14,568 lineas)
|
||
- **Impacto:** Deuda tecnica
|
||
- **Recomendacion:** Extraer a submodulos
|
||
|
||
### BUG-009: Encoding corrupto en docstrings de sample_selector.py
|
||
- **Archivo:** `sample_selector.py`
|
||
- **Problema:** Los docstrings contienen caracteres UTF-8 doble-encoded (ej: `SelecciÃÆ'³n` en lugar de `Seleccion`)
|
||
- **Impacto:** Legibilidad
|
||
|
||
### BUG-010: reference_listener.py tiene 8,488 lineas
|
||
- Otro archivo monolitico que deberia refactorizarse
|
||
|
||
### BUG-011: Imports relativos inconsistentes en sample_selector.py
|
||
- **Archivo:** `sample_selector.py:48-61, 68-94`
|
||
- **Problema:** Cada import intenta primero con `.module` (relativo) y luego `module` (absoluto). Esto funciona pero es fragil y crea duplicacion de imports.
|
||
|
||
### BUG-012: abletonmcp_init.py no usa MESSAGE_TERMINATOR para parsear
|
||
- **Archivo:** `abletonmcp_init.py:194-197`
|
||
- **Problema:** El handler de cliente intenta `json.loads(buffer)` sin separar por newline delimiter. Funciona por casualidad con json.loads, pero no soporta multiples comandos en buffer.
|
||
|
||
### BUG-013: Python 2 compatibility code innecesario
|
||
- **Archivo:** `abletonmcp_init.py:13-21`
|
||
- **Problema:** Ableton Live 12 usa Python 3.11+. Los bloques try/except para `Queue` vs `queue` y `basestring` vs `str` son innecesarios.
|
||
|
||
### BUG-014: client_threads lista nunca se limpia completamente
|
||
- **Archivo:** `abletonmcp_init.py:152`
|
||
- **Problema:** La lista `self.client_threads` solo se limpia en `_server_thread` pero crece indefinidamente si hay muchas conexiones.
|
||
|
||
### BUG-015: Bare except en disconnect
|
||
- **Archivo:** `abletonmcp_init.py:73`
|
||
- **Problema:** `except:` sin tipo de excepcion - captura incluso SystemExit y KeyboardInterrupt
|
||
|
||
### BUG-016: Constante HOST inconsistente
|
||
- `abletonmcp_init.py:25` usa `HOST = "localhost"`
|
||
- `server.py:1098` usa `HOST = "127.0.0.1"`
|
||
- Deberia ser consistente (preferir `127.0.0.1` para evitar DNS lookups)
|
||
|
||
### BUG-017: DIVERSITY_MEMORY_AVAILABLE sobrescrita
|
||
- **Archivo:** `sample_selector.py:77`
|
||
- **Problema:** `DIVERSITY_MEMORY_AVAILABLE = True` se importa del modulo Y se re-asigna manualmente. La importacion desde diversity_memory ya establece este valor.
|
||
|
||
### BUG-018: Doble lineas en blanco excesivas en song_generator.py
|
||
- Todo el archivo tiene doble-spacing con lineas en blanco entre cada linea de codigo
|
||
- Resultado: el archivo tiene ~7,000 lineas de contenido real en ~14,500 lineas
|
||
- **Impacto:** Legibilidad reducida
|
||
|
||
### BUG-019: scan_log.txt staged para commit
|
||
- **Archivo:** `AbletonMCP_AI/AbletonMCP_AI/MCP_Server/scan_log.txt`
|
||
- **Problema:** Log de escaneo staged para git commit - no deberia estar en el repo
|
||
|
||
---
|
||
|
||
## 4. Archivos Basura (ELIMINAR)
|
||
|
||
### Scripts de diagnostico/debugging de un solo uso
|
||
| Archivo | Razon |
|
||
|---|---|
|
||
| `check_piano_melody.py` | Script de debugging one-time |
|
||
| `check_v27.py` | Script de verificacion obsoleto |
|
||
| `check_v29.py` | Script de verificacion obsoleto |
|
||
| `validate_v29.py` | Script de verificacion obsoleto |
|
||
| `final_check.py` | Script de debugging one-time |
|
||
| `quick_check.py` | Script de debugging one-time |
|
||
| `validate_audio_resampler.py` | Script de test one-time |
|
||
| `validate_script.py` | Script de test one-time |
|
||
| `diagnostico_wsl.py` | Diagnostico WSL no relevante |
|
||
| `agent7_lead_task.py` | Script de agente temporal |
|
||
| `agent8_vocals.py` | Script de agente temporal |
|
||
| `agent8_vocals_load.py` | Script de agente temporal |
|
||
| `agent9_fx_loader.py` | Script de agente temporal |
|
||
| `agent10_diagnosis.py` | Script de agente temporal |
|
||
| `add_samples_script.py` | Script de utilidad one-time |
|
||
| `place_perc_audio.py` | Script de utilidad one-time |
|
||
| `set_input_routing.py` | Script de utilidad one-time |
|
||
| `generate_song.py` | Script de test (la funcionalidad esta en server.py) |
|
||
| `generate_track.py` | Script de test (la funcionalidad esta en server.py) |
|
||
|
||
### Scripts temporales en AbletonMCP_AI/
|
||
| Archivo | Razon |
|
||
|---|---|
|
||
| `AbletonMCP_AI/diagnostico_wsl.py` | Diagnostico temporal |
|
||
| `AbletonMCP_AI/place_perc_audio.py` | Script de utilidad one-time |
|
||
| `AbletonMCP_AI/set_input_routing.py` | Script de utilidad one-time |
|
||
| `AbletonMCP_AI/temp_socket_cmd.py` | Script temporal |
|
||
| `AbletonMCP_AI/validate_audio_resampler.py` | Script de test one-time |
|
||
| `AbletonMCP_AI/validate_script.py` | Script de test one-time |
|
||
| `AbletonMCP_AI/restart_ableton.bat` | Duplicado del root |
|
||
|
||
### Scripts temporales en MCP_Server/
|
||
| Archivo | Razon |
|
||
|---|---|
|
||
| `MCP_Server/temp_tool.py` | Herramienta temporal |
|
||
| `MCP_Server/coherence_demo.py` | Demo script |
|
||
| `MCP_Server/sample_system_demo.py` | Demo script |
|
||
| `MCP_Server/socket_smoke_test.py` | Test de diagnostico |
|
||
| `MCP_Server/test_phrase_plan.py` | Test script suelto |
|
||
| `MCP_Server/scan_log.txt` | Log de escaneo |
|
||
|
||
---
|
||
|
||
## 5. Documentacion Obsoleta (ELIMINAR o ARCHIVAR)
|
||
|
||
| Archivo | Estado |
|
||
|---|---|
|
||
| `KIMI_K2_BOOTSTRAP.md` | Obsoleto - bootstrap ya completado |
|
||
| `KIMI_K2_NOTE_API_FIX.md` | Obsoleto - fix ya aplicado |
|
||
| `KIMI_K2_CODEBASE_FIXES.md` | Obsoleto - fixes ya aplicados |
|
||
| `MCP_CLAUDE_OPENCODE_SETUP.md` | Obsoleto - setup ya configurado |
|
||
| `MCP_SETUP_SUMMARY.md` | Obsoleto - resumen viejo |
|
||
| `MCP_VERIFICATION.md` | Obsoleto - verificacion vieja |
|
||
| `QWEN_MCP_SETUP.md` | Obsoleto - setup de modelo antiguo |
|
||
| `GPU_SETUP.md` | Obsoleto - setup GPU viejo |
|
||
| `HUMAN_FEEL_IMPLEMENTATION.md` | Obsoleto - ya implementado |
|
||
| `SECTION_AWARE_WIRING_REPORT.md` | Obsoleto - reporte viejo |
|
||
| `SMOKE_TEST_ASYNC.md` | Obsoleto - test viejo |
|
||
| `codex.md` | Obsoleto - config para Codex |
|
||
| `kimi.md` | Obsoleto - config para Kimi |
|
||
| `AbletonMCP_AI/CODE_REVIEW_NEXT_STEPS.md` (deleted) | Ya borrado |
|
||
| `AbletonMCP_AI/todo.md` (deleted) | Ya borrado |
|
||
|
||
### Documentos a MANTENER
|
||
| Archivo | Razon |
|
||
|---|---|
|
||
| `CLAUDE.md` | Contexto canonico del proyecto |
|
||
| `KIMI_K2_START_HERE.md` | Handoff activo |
|
||
| `KIMI_K2_ACTIVE_HANDOFF.md` | Handoff activo |
|
||
| `README.md` | Documentacion principal |
|
||
| `docs/ROADMAP.md` | Roadmap activo |
|
||
|
||
---
|
||
|
||
## 6. Archivos Duplicados
|
||
|
||
| Archivo | Duplica a |
|
||
|---|---|
|
||
| `AbletonMCP_AI/mcp_wrapper.bat` | `mcp_wrapper.bat` (root) |
|
||
| `AbletonMCP_AI/opencode.json` | `opencode.json` (root) |
|
||
| `AbletonMCP_AI/start_claude_glm5.sh` | `start_claude_glm5.sh` (root) |
|
||
| `AbletonMCP_AI/start_mcp.bat` | `start_mcp.bat` (root) |
|
||
| `song_generator.py:5535 HumanFeelEngine` | `human_feel.py:8 HumanFeelEngine` |
|
||
|
||
---
|
||
|
||
## 7. Metricas de Complejidad
|
||
|
||
| Archivo | Lineas | Estado |
|
||
|---|---|---|
|
||
| `server.py` | 14,930 | CRITICO - Necesita refactorizacion |
|
||
| `song_generator.py` | 14,568 | CRITICO - Double-spaced, ~7K reales |
|
||
| `reference_listener.py` | 8,488 | ALTO - Necesita refactorizacion |
|
||
| `sample_selector.py` | 3,258 | OK |
|
||
| `audio_resampler.py` | 2,527 | OK |
|
||
| `sample_manager.py` | 1,087 | OK |
|
||
| `abletonmcp_init.py` | ~800 | OK |
|
||
| `audio_arrangement.py` | ~500 | OK |
|
||
| `audio_mastering.py` | ~400 | OK |
|
||
|
||
---
|
||
|
||
## 8. Mejoras Implementadas
|
||
|
||
### FIX-001: Proteger import de human_feel en server.py
|
||
**Estado:** Aplicado
|
||
|
||
### FIX-002: Renombrar excepciones que sobreescriben built-ins
|
||
**Estado:** Aplicado (ConnectionError -> MCPConnectionError, etc.)
|
||
|
||
### FIX-003: Eliminar funcion duplicada _linear_to_live_slider_bus
|
||
**Estado:** Aplicado
|
||
|
||
### FIX-004: Corregir HOST inconsistente en abletonmcp_init.py
|
||
**Estado:** Aplicado
|
||
|
||
### FIX-005: Eliminar codigo Python 2 innecesario en abletonmcp_init.py
|
||
**Estado:** Aplicado
|
||
|
||
### FIX-006: Fix bare except en abletonmcp_init.py disconnect()
|
||
**Estado:** Aplicado
|
||
|
||
---
|
||
|
||
## 9. Roadmap de Mejoras
|
||
|
||
### Fase 1: Limpieza Inmediata (1-2 dias)
|
||
- [x] Arreglar los 7 bugs criticos
|
||
- [ ] Eliminar archivos basura (23 archivos)
|
||
- [ ] Archivar documentacion obsoleta (14 archivos)
|
||
- [ ] Eliminar archivos duplicados (5 archivos)
|
||
- [ ] Actualizar .gitignore para prevenir re-inclusion
|
||
|
||
### Fase 2: Refactorizacion Arquitectural (1 semana)
|
||
- [ ] Dividir `server.py` (14,930 lineas) en modulos:
|
||
- `server_core.py` - FastMCP setup, lifespan, connection
|
||
- `server_tools.py` - Tool definitions (@mcp.tool decorators)
|
||
- `server_generation.py` - Track/song generation logic
|
||
- `server_manifest.py` - Manifest storage/retrieval
|
||
- `server_budget.py` - GenerationBudget class
|
||
- `server_ableton.py` - AbletonConnection class
|
||
- `server_helpers.py` - Utility functions
|
||
- [ ] Dividir `song_generator.py` (14,568 lineas):
|
||
- Eliminar double-spacing (~7,000 lineas de aire)
|
||
- Extraer `PhrasePlan` a su propio modulo
|
||
- Extraer constantes de genero a `genre_config.py`
|
||
- Extraer patrones de bateria a `drum_patterns.py`
|
||
- [ ] Eliminar `HumanFeelEngine` duplicada en song_generator.py
|
||
- [ ] Unificar sistema de imports (usar imports absolutos consistentes)
|
||
|
||
### Fase 3: Robustez (1 semana)
|
||
- [ ] Reducir los 206 bloques `except Exception` a excepciones especificas
|
||
- [ ] Implementar connection pooling en AbletonConnection
|
||
- [ ] Arreglar el parseo de buffer en abletonmcp_init.py (usar newline delimiter)
|
||
- [ ] Agregar health check endpoint
|
||
- [ ] Implementar circuit breaker para comunicacion con Ableton
|
||
- [ ] Agregar metricas de latencia por comando
|
||
|
||
### Fase 4: Testing (1 semana)
|
||
- [ ] Crear test suite para song_generator.py
|
||
- [ ] Crear test suite para sample_selector.py
|
||
- [ ] Crear test de integracion MCP -> Remote Script
|
||
- [ ] Crear test de regresion para generacion de tracks
|
||
- [ ] Mover tests sueltos a `tests/` directory
|
||
|
||
### Fase 5: Optimizacion (2 semanas)
|
||
- [ ] Implementar lazy loading de modulos pesados
|
||
- [ ] Cache de samples index en memoria
|
||
- [ ] Optimizar vector_manager.py (solo 318 lineas, pero critico)
|
||
- [ ] Profile y optimizar latencia de generacion
|
||
- [ ] Implementar generacion incremental (no regenerar todo el set)
|
||
|
||
### Fase 6: Nuevas Features (continuo)
|
||
- [ ] Soporte para mas generos (ambient, lo-fi, breakbeat)
|
||
- [ ] Generacion multi-track en paralelo
|
||
- [ ] Preview auditivo antes de materializar
|
||
- [ ] Undo/redo de generaciones
|
||
- [ ] Modo "remix" - modificar generacion existente
|
||
- [ ] API REST alternativa al MCP para integraciones externas
|
||
- [ ] Dashboard web para monitoreo de generaciones
|
||
|
||
---
|
||
|
||
## 10. Estructura de Proyecto Recomendada
|
||
|
||
```
|
||
MIDI Remote Scripts/
|
||
├── CLAUDE.md # Contexto canonico
|
||
├── README.md # Documentacion principal
|
||
├── .mcp.json # Config MCP
|
||
├── .gitignore # Git ignore
|
||
├── mcp_wrapper.py # Wrapper MCP
|
||
├── abletonmcp_init.py # Runtime Remote Script
|
||
├── opencode.json # Config opencode
|
||
├── mcp_wrapper.bat # Launcher Windows
|
||
├── start_mcp.bat # Launcher MCP
|
||
├── restart_ableton.bat # Restart helper
|
||
│
|
||
├── AbletonMCP_AI/ # Remote Script package
|
||
│ ├── __init__.py # Shim loader
|
||
│ └── Remote_Script.py # Fallback
|
||
│
|
||
├── AbletonMCP_AI/AbletonMCP_AI/
|
||
│ └── MCP_Server/ # MCP Server package
|
||
│ ├── server_core.py # Core MCP setup
|
||
│ ├── server_tools.py # Tool definitions
|
||
│ ├── server_generation.py # Generation logic
|
||
│ ├── server_manifest.py # Manifest storage
|
||
│ ├── server_budget.py # Budget enforcement
|
||
│ ├── server_ableton.py # Ableton connection
|
||
│ ├── server_helpers.py # Utilities
|
||
│ ├── song_generator.py # Music generation
|
||
│ ├── sample_selector.py # Sample selection
|
||
│ ├── sample_manager.py # Sample management
|
||
│ ├── reference_listener.py # Reference analysis
|
||
│ ├── audio_resampler.py # Audio resampling
|
||
│ ├── diversity_memory.py # Cross-gen memory
|
||
│ ├── coherence_analyzer.py # Quality analysis
|
||
│ ├── human_feel.py # Humanization
|
||
│ ├── self_ai.py # Auto-prompter
|
||
│ └── tests/ # Test suite
|
||
│ ├── test_generator.py
|
||
│ ├── test_selector.py
|
||
│ └── test_integration.py
|
||
│
|
||
└── docs/ # Documentacion
|
||
├── ROADMAP.md
|
||
├── ARCHITECTURE.md
|
||
└── API.md
|
||
```
|
||
|
||
---
|
||
|
||
## 11. Prioridades Inmediatas
|
||
|
||
1. **AHORA:** Aplicar fixes criticos (BUG-001 a BUG-005) - **HECHO**
|
||
2. **HOY:** Limpiar archivos basura
|
||
3. **ESTA SEMANA:** Actualizar .gitignore
|
||
4. **PROXIMO SPRINT:** Dividir server.py en modulos
|
||
5. **SIGUIENTE:** Eliminar double-spacing en song_generator.py
|