Music Collection MCP Server

Accede y gestiona colecciones de música locales con metadatos avanzados, clasificación y análisis.

Documentación

Music Collection MCP Server

Un potente servidor de Model Context Protocol (MCP) que proporciona acceso inteligente a tu colección de música local mediante gestión avanzada de metadatos, clasificación de tipos de álbum y análisis exhaustivos.

✨ Características Principales

🎵 Descubrimiento Inteligente de Música: Escaneo inteligente con clasificación de álbumes en 8 tipos (Álbum, EP, En Vivo, Demo, Recopilación, Sencillo, Instrumental, Split)
📊 Análisis Avanzados: Evaluación de madurez de la colección, puntuación de salud y recomendaciones personalizadas
🏗️ Organización Flexible: Soporte para múltiples estructuras de carpetas con migración automatizada y puntuación de cumplimiento
⚡ Alto Rendimiento: Escaneo optimizado (20-30% más rápido), operaciones por lotes y caché inteligente
🤖 Integración con IA: Funciona perfectamente con Claude Desktop y otros clientes MCP
🔄 Configuración Automatizada: Instalación con un solo comando y generación de configuración

🚀 Inicio Rápido

Opción 1: Configuración Automatizada (Recomendada)

python scripts/setup.py

Esta configuración guiada:

Comprobará los requisitos del sistema
Instalará las dependencias
Configurará la ruta de tu colección de música
Generará la configuración de Claude Desktop
Validará tu configuración

Opción 2: Instalación Manual

Usando Python

# Install dependencies
pip install -r requirements.txt

# Set your music path
export MUSIC_ROOT_PATH="/path/to/your/music"

# Run the server
python main.py

Usando Docker

# Build and run
docker build -t music-mcp .
docker run -v "/path/to/your/music:/music" -e MUSIC_ROOT_PATH=/music music-mcp

🤖 Configuración del Cliente MCP

Ubicaciones de Archivos de Configuración para Claude Desktop

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Instalación con Python

{
  "mcpServers": {
    "music-collection": {
      "command": "python",
      "args": ["/path/to/music-mcp-server/main.py"],
      "env": {
        "MUSIC_ROOT_PATH": "/path/to/your/music",
        "CACHE_DURATION_DAYS": "30",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Instalación con Docker

{
  "mcpServers": {
    "music-collection": {
      "command": "docker",
      "args": [
        "run", "--rm", "--interactive",
        "-v", "/path/to/your/music:/music",
        "-e", "MUSIC_ROOT_PATH=/music",
        "-e", "CACHE_DURATION_DAYS=30",
        "music-mcp"
      ]
    }
  }
}

📁 Organización de Música

El servidor admite múltiples patrones de organización:

Estructura Mejorada (Recomendada)

Band Name/
├── Album/
│   ├── 1973 - Dark Side of the Moon/
│   └── 1979 - The Wall (Deluxe)/
├── Live/
│   └── 1988 - Delicate Sound of Thunder/
├── Compilation/
│   └── 2001 - Echoes - Best Of/
└── .band_metadata.json (auto-generated)

Estructura Simple (También Compatible)

Band Name/
├── 1973 - Dark Side of the Moon/
├── 1988 - Delicate Sound of Thunder (Live)/
└── 2001 - Echoes - Best Of (Compilation)/

🛠️ Capacidades de MCP

Herramientas (10 en total)

Descubrimiento de Música: scan_music_folders - Escaneo inteligente con detección de tipos
Gestión de Colección: get_band_list - Filtrado y búsqueda avanzados
Almacenamiento de Metadatos: save_band_metadata, save_band_analyze, save_collection_insight
Validación: validate_band_metadata - Validación simulada (dry-run)
Búsqueda Avanzada: advanced_search_albums - Sistema de filtrado con 13 parámetros
Análisis: analyze_collection_insights - Análisis exhaustivo de la colección
Migración de Estructura: migrate_band_structure - Migración segura de la organización de carpetas

Recursos (3 en total)

Información de Banda: band://info/{band_name} - Información detallada de la banda
Resumen de Colección: collection://summary - Visión general y estadísticas
Análisis Avanzados: collection://analytics - Análisis profundo de la colección

Prompts (4 en total)

Recopilación de Información: fetch_band_info, analyze_band
Análisis: compare_bands, collection_insights

⚙️ Configuración

Configura mediante variables de entorno o la configuración automatizada:

MUSIC_ROOT_PATH="/path/to/your/music"     # Required: Your music directory
CACHE_DURATION_DAYS=30                    # Optional: Cache expiration (default: 30)
LOG_LEVEL=INFO                           # Optional: Logging level (default: INFO)

📚 Documentación

Comienza Rápidamente

Guía de Inicio Rápido - Ponte en marcha en minutos
Guía de Instalación - Instrucciones detalladas de configuración
Guía de Configuración - Opciones de configuración avanzadas

Aprende Más

Ejemplos de Uso - Ejemplos del mundo real
Organización de Colección - Mejores prácticas
Gestión de Álbumes - Comprender los tipos de álbumes

Obtén Ayuda

Preguntas Frecuentes - Preguntas comunes
Solución de Problemas - Resolución de problemas
Sistema de Clasificación - Comprender las clasificaciones y el análisis

🔧 Mantenimiento y Scripts

El directorio scripts/ proporciona potentes herramientas de mantenimiento:

Configuración: setup.py - Instalación y configuración automatizadas
Docker: start-docker.sh - Gestión de contenedores con opciones
Validación: validate-music-structure.py - Comprobación de salud de la colección
Copia de Seguridad: backup-recovery.py - Sistema completo de copia de seguridad y recuperación
Monitoreo: health-check.py - Monitoreo integral de salud

🧪 Pruebas

# Using Docker (recommended)
docker build -f Dockerfile.test -t music-mcp-tests .
docker run --rm music-mcp-tests python -m pytest . -v

# Using Python
python -m pytest tests/ -v

📊 Novedades

Mejoras Recientes

Herramientas de Migración: Migración segura de estructura de carpetas con copia de seguridad y reversión
Análisis Avanzados: Evaluación de madurez de la colección y puntuación de salud
Rendimiento: Escaneo 20-30% más rápido con operaciones de archivo optimizadas
Esquema Separado: Álbumes locales vs. faltantes para una mejor gestión
Configuración Automatizada: Instalación y configuración con un solo comando
Tipos de Álbumes: Sistema inteligente de clasificación en 8 tipos
Estructura Flexible: Soporte para múltiples patrones de organización

🆘 ¿Necesitas Ayuda?

Consulta las Preguntas Frecuentes para preguntas comunes
Ejecuta la comprobación de salud: python scripts/health-check.py /path/to/music
Valida la estructura: python scripts/validate-music-structure.py /path/to/music
Revisa la guía de Solución de Problemas

🔗 Enlaces

Scripts de Configuración: Automatización completa en el directorio scripts/
Configuraciones de Claude Desktop: Ejemplos listos para usar en scripts/claude-desktop-configs/
Documentación para Desarrolladores: Referencia de arquitectura y API en docs/developer/

¡Transforma tu colección de música en una biblioteca inteligente y buscable con información impulsada por IA! 🎶

Requisitos

Python 3.8+
Docker (para implementación en contenedores)

Licencia

Licencia MIT

Por la presente se concede permiso, de forma gratuita, a cualquier persona que obtenga una copia de este software y de los archivos de documentación asociados (el "Software"), para tratar el Software sin restricción, incluidos, sin limitación, los derechos de usar, copiar, modificar, fusionar, publicar, distribuir, sublicenciar y/o vender copias del Software, y para permitir que las personas a las que se les proporcione el Software hagan lo mismo, sujeto a las siguientes condiciones:

El aviso de copyright anterior y este aviso de permiso deberán incluirse en todas las copias o partes sustanciales del Software.

EL SOFTWARE SE PROPORCIONA "TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO, EXPRESA O IMPLÍCITA, INCLUIDAS, ENTRE OTRAS, LAS GARANTÍAS DE COMERCIABILIDAD, IDONEIDAD PARA UN FIN PARTICULAR Y NO INFRACCIÓN. EN NINGÚN CASO LOS AUTORES O TITULARES DE LOS DERECHOS DE AUTOR SERÁN RESPONSABLES DE CUALQUIER RECLAMO, DAÑO U OTRA RESPONSABILIDAD, YA SEA EN UNA ACCIÓN DE CONTRATO, AGRAVIO O DE OTRO MODO, QUE SURJA DE, O EN RELACIÓN CON, EL SOFTWARE O EL USO U OTROS TRATOS EN EL SOFTWARE.