Music Collection MCP Server

Acesse e gerencie coleções de música locais com metadados avançados, classificação e análises.

Documentação

Music Collection MCP Server

Um poderoso servidor Model Context Protocol (MCP) que fornece acesso inteligente à sua coleção de música local por meio de gerenciamento avançado de metadados, classificação de tipos de álbum e análises abrangentes.

✨ Principais Recursos

🎵 Descoberta Inteligente de Música: Escaneamento inteligente com classificação de 8 tipos de álbum (Álbum, EP, Ao Vivo, Demo, Compilação, Single, Instrumental, Split)
📊 Análises Avançadas: Avaliação de maturidade da coleção, pontuação de saúde e recomendações personalizadas
🏗️ Organização Flexível: Suporte a múltiplas estruturas de pastas com migração automatizada e pontuação de conformidade
⚡ Alto Desempenho: Escaneamento otimizado (20-30% mais rápido), operações em lote e cache inteligente
🤖 Integração com IA: Funciona perfeitamente com Claude Desktop e outros clientes MCP
🔄 Configuração Automatizada: Instalação com um comando e geração de configuração

🚀 Início Rápido

Opção 1: Configuração Automatizada (Recomendada)

python scripts/setup.py

Esta configuração guiada irá:

Verificar os requisitos do sistema
Instalar dependências
Configurar o caminho da sua coleção de música
Gerar a configuração do Claude Desktop
Validar sua configuração

Opção 2: Instalação 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

🤖 Configuração do Cliente MCP

Locais dos Arquivos de Configuração 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

Instalação via 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"
      }
    }
  }
}

Instalação via 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"
      ]
    }
  }
}

📁 Organização de Música

O servidor suporta múltiplos padrões de organização:

Estrutura Aprimorada (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)

Estrutura Simples (Também Suportada)

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

🛠️ Recursos do MCP

Ferramentas (10 no total)

Descoberta de Música: scan_music_folders - Escaneamento inteligente com detecção de tipo
Gerenciamento de Coleção: get_band_list - Filtragem e busca avançadas
Armazenamento de Metadados: save_band_metadata, save_band_analyze, save_collection_insight
Validação: validate_band_metadata - Validação de simulação (dry-run)
Busca Avançada: advanced_search_albums - Sistema de filtragem com 13 parâmetros
Análises: analyze_collection_insights - Análise abrangente da coleção
Migração de Estrutura: migrate_band_structure - Migração segura de organização de pastas

Recursos (3 no total)

Informações da Banda: band://info/{band_name} - Informações detalhadas da banda
Resumo da Coleção: collection://summary - Visão geral e estatísticas
Análises Avançadas: collection://analytics - Análise profunda da coleção

Prompts (4 no total)

Coleta de Informações: fetch_band_info, analyze_band
Análise: compare_bands, collection_insights

⚙️ Configuração

Configure por meio de variáveis de ambiente ou da configuração 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)

📚 Documentação

Comece Rapidamente

Guia de Início Rápido - Comece a usar em minutos
Guia de Instalação - Instruções detalhadas de configuração
Guia de Configuração - Opções avançadas de configuração

Saiba Mais

Exemplos de Uso - Exemplos do mundo real
Organização da Coleção - Melhores práticas
Gerenciamento de Álbuns - Entendendo os tipos de álbum

Obtenha Ajuda

FAQ - Perguntas frequentes
Solução de Problemas - Resolução de problemas
Sistema de Avaliação - Entendendo avaliações e análises

🔧 Manutenção e Scripts

O diretório scripts/ fornece ferramentas poderosas de manutenção:

Configuração: setup.py - Instalação e configuração automatizadas
Docker: start-docker.sh - Gerenciamento de contêineres com opções
Validação: validate-music-structure.py - Verificação de saúde da coleção
Backup: backup-recovery.py - Sistema completo de backup e recuperação
Monitoramento: health-check.py - Monitoramento abrangente de saúde

🧪 Testes

# 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

📊 Novidades

Melhorias Recentes

Ferramentas de Migração: Migração segura de estrutura de pastas com backup e reversão
Análises Avançadas: Avaliação de maturidade da coleção e pontuação de saúde
Desempenho: Escaneamento 20-30% mais rápido com operações de arquivo otimizadas
Esquema Separado: Álbuns locais vs. ausentes para melhor gerenciamento
Configuração Automatizada: Instalação e configuração com um comando
Tipos de Álbum: Sistema inteligente de classificação em 8 tipos
Estrutura Flexível: Suporte a múltiplos padrões de organização

🆘 Precisa de Ajuda?

Consulte o FAQ para perguntas frequentes
Execute a verificação de saúde: python scripts/health-check.py /path/to/music
Valide a estrutura: python scripts/validate-music-structure.py /path/to/music
Revise o guia de Solução de Problemas

🔗 Links

Scripts de Configuração: Automação completa no diretório scripts/
Configurações do Claude Desktop: Exemplos prontos para uso em scripts/claude-desktop-configs/
Documentação para Desenvolvedores: Referência de arquitetura e API em docs/developer/

Transforme sua coleção de música em uma biblioteca inteligente e pesquisável com insights alimentados por IA! 🎶

Requisitos

Python 3.8+
Docker (para implantação em contêineres)

Licença

Licença MIT

A permissão é concedida, gratuitamente, a qualquer pessoa que obtenha uma cópia deste software e dos arquivos de documentação associados (o "Software"), para lidar com o Software sem restrições, incluindo, sem limitação, os direitos de usar, copiar, modificar, mesclar, publicar, distribuir, sublicenciar e/ou vender cópias do Software, e permitir que as pessoas a quem o Software é fornecido façam o mesmo, sujeito às seguintes condições:

O aviso de copyright acima e este aviso de permissão deverão ser incluídos em todas as cópias ou partes substanciais do Software.

O SOFTWARE É FORNECIDO "NO ESTADO EM QUE SE ENCONTRA", SEM GARANTIA DE QUALQUER TIPO, EXPRESSA OU IMPLÍCITA, INCLUINDO, MAS NÃO SE LIMITANDO ÀS GARANTIAS DE COMERCIABILIDADE, ADEQUAÇÃO A UM FIM ESPECÍFICO E NÃO VIOLAÇÃO. EM NENHUM CASO OS AUTORES OU DETENTORES DE DIREITOS AUTORAIS SERÃO RESPONSÁVEIS POR QUALQUER RECLAMAÇÃO, DANOS OU OUTRA RESPONSABILIDADE, SEJA EM AÇÃO DE CONTRATO, ATO ILÍCITO OU OUTRA FORMA, DECORRENTE DE, FORA OU EM CONEXÃO COM O SOFTWARE OU O USO OU OUTRAS NEGOCIAÇÕES NO SOFTWARE.