MCP Spotify Server

# 🎵 Exemplos de Uso do MCP Spotify Server Este documento mostra como usar o servidor MCP Spotify com diferentes LLMs. ## 🚀 Início Rápido 1. **Configure o ambiente:** ```bash ./setup.sh ``` 2. **Configure suas credenciais no `.env`:** ```env SPOTIFY_CLIENT_ID=seu_client_id_aqui SPOTIFY_CLIENT_SECRET=seu_client_secret_aqui SPOTIFY_REDIRECT_URI=http://localhost:3000/callback ``` 3. **Inicie o servidor:** ```bash npm run dev ``` ## 🎯 Exemplos de Interação ### 1. Autenticação ``` Usuário: "Preciso me autenticar com o Spotify" LLM: Chama spotify_auth → Abre navegador → Usuário autoriza → Código retornado ``` ### 2. Buscar Música ``` Usuário: "Busque por 'Bohemian Rhapsody' do Queen" LLM: Chama spotify_search com query="Bohemian Rhapsody", type="track" Resultado: Lista de músicas com IDs para reprodução ``` ### 3. Tocar Música ``` Usuário: "Toque a primeira música que encontrou" LLM: Chama spotify_play com o track_id da primeira música Resultado: Música começa a tocar no dispositivo ativo ``` ### 4. Controle de Reprodução ``` Usuário: "Pause a música" LLM: Chama spotify_pause Resultado: Reprodução pausada Usuário: "Continue tocando" LLM: Chama spotify_resume Resultado: Reprodução retomada ``` ### 5. Buscar Playlists ``` Usuário: "Mostre minhas playlists" LLM: Chama spotify_playlists Resultado: Lista de playlists do usuário ``` ### 6. Tocar Playlist ``` Usuário: "Toque minha playlist 'Favoritas'" LLM: Chama spotify_play_playlist com o ID da playlist Resultado: Playlist começa a tocar ``` ## 🔧 Integração com LLMs ### Claude Desktop Adicione ao seu `claude_desktop_config.json`: ```json { "mcpServers": { "spotify": { "command": "node", "args": ["dist/index.js"], "cwd": "/caminho/para/MCPSpotify", "env": { "SPOTIFY_CLIENT_ID": "seu_client_id", "SPOTIFY_CLIENT_SECRET": "seu_client_secret", "SPOTIFY_REDIRECT_URI": "http://localhost:3000/callback" } } } } ``` ### Outros LLMs O servidor MCP é compatível com qualquer cliente MCP. Configure o servidor como um processo externo que o LLM pode chamar. ## 🎵 Casos de Uso Avançados ### 1. Criação de Playlist Inteligente ``` Usuário: "Crie uma playlist com músicas relaxantes dos anos 90" LLM: 1. Busca por "relaxing 90s music" 2. Filtra resultados 3. Cria playlist (requer implementação adicional) 4. Adiciona músicas selecionadas ``` ### 2. Recomendações Baseadas em Humor ``` Usuário: "Estou triste, me recomende músicas alegres" LLM: 1. Busca por "happy upbeat songs" 2. Filtra por gêneros alegres 3. Sugere músicas específicas 4. Pode tocar automaticamente ``` ### 3. Análise de Música Atual ``` Usuário: "Que música está tocando agora?" LLM: Chama spotify_current_playing Resultado: Informações detalhadas sobre a música atual ``` ## 🛠️ Desenvolvimento ### Adicionando Novas Ferramentas 1. Adicione a ferramenta em `src/tools/spotify-tools.ts` 2. Registre no `src/index.ts` no `ListToolsRequestSchema` 3. Implemente o handler no `CallToolRequestSchema` ### Exemplo de Nova Ferramenta ```typescript // Em spotify-tools.ts async setVolume(volume: number, deviceId?: string) { // Implementação } // Em index.ts - ListToolsRequestSchema { name: 'spotify_volume', description: 'Ajusta o volume do dispositivo', inputSchema: { type: 'object', properties: { volume: { type: 'number', minimum: 0, maximum: 100 }, device_id: { type: 'string' } }, required: ['volume'] } } // Em index.ts - CallToolRequestSchema case 'spotify_volume': return await spotifyTools.setVolume(args.volume, args.device_id); ``` ## 🔒 Segurança - **Tokens**: Armazenados apenas localmente - **Credenciais**: Nunca expostas em logs - **Renovação**: Automática quando necessário - **Permissões**: Mínimas necessárias para funcionamento ## 📊 Monitoramento O servidor registra: - Tentativas de autenticação - Chamadas de ferramentas - Erros e exceções - Status de conexão ## 🐛 Debugging ### Logs Detalhados ```bash DEBUG=* npm run dev ``` ### Verificar Conexão ```bash # Testar se o servidor responde curl -X POST http://localhost:3000/health ``` ### Verificar Autenticação ```bash # Verificar tokens armazenados node -e "console.log(process.env.SPOTIFY_CLIENT_ID)" ``` ## 📈 Performance - **Latência**: < 100ms para operações simples - **Throughput**: Suporta múltiplas chamadas simultâneas - **Memória**: ~50MB em uso normal - **CPU**: Baixo uso, apenas durante operações ## 🔄 Atualizações Para atualizar o servidor: ```bash git pull npm install npm run build ``` ## 📞 Suporte - **Issues**: Abra uma issue no repositório - **Documentação**: Consulte o README.md - **Exemplos**: Veja a pasta `examples/`