# 🎵 MCP Spotify Server

Um servidor MCP (Model Context Protocol) que permite interagir com o Spotify através de LLMs. Este servidor fornece ferramentas para buscar música, controlar reprodução, gerenciar playlists e muito mais.

## 🚀 Funcionalidades

- **Autenticação OAuth2** com Spotify
- **Busca** por músicas, artistas, álbuns e playlists
- **Controle de reprodução** (tocar, pausar, próximo, anterior)
- **Informações da música atual**
- **Gerenciamento de dispositivos**
- **Listagem e reprodução de playlists**

## 📋 Pré-requisitos

1. **Node.js** (versão 18 ou superior)
2. **Conta Spotify** (Premium recomendado para funcionalidade completa)
3. **Aplicação Spotify** registrada no [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
4. **ngrok** (para expor o servidor local)

## 🛠️ Instalação

1. **Clone o repositório:**
   ```bash
   git clone https://github.com/fborello/MCPSpotify.git
   cd MCPSpotify
   ```

2. **Instale as dependências:**
   ```bash
   npm install
   ```

3. **Instale o ngrok:**
   
   **macOS (com Homebrew):**
   ```bash
   brew install ngrok/ngrok/ngrok
   ```
   
   **Windows (com Chocolatey):**
   ```bash
   choco install ngrok
   ```
   
   **Linux:**
   ```bash
   # Baixe o binário do site oficial
   curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
   echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | sudo tee /etc/apt/sources.list.d/ngrok.list
   sudo apt update && sudo apt install ngrok
   ```
   
   **Ou baixe diretamente do [site oficial](https://ngrok.com/download)**

4. **Configure as variáveis de ambiente:**
   ```bash
   cp env.example .env
   ```

5. **Edite o arquivo `.env` com suas credenciais:**
   ```env
   SPOTIFY_CLIENT_ID=seu_client_id_aqui
   SPOTIFY_CLIENT_SECRET=seu_client_secret_aqui
   SPOTIFY_REDIRECT_URI=http://localhost:3000/callback
   ```

6. **Configure o MCP (opcional):**
   
   **Para Claude Desktop:**
   ```bash
   cp configs/claude-desktop.example.json ~/.claude-desktop/config.json
   # Edite o arquivo com seu caminho e credenciais
   ```
   
   **Para Cursor:**
   ```bash
   cp configs/cursor.example.json ~/.cursor/mcp.json
   # Edite o arquivo com seu caminho e credenciais
   ```
   
   **Para outros clientes MCP:**
   ```bash
   cp mcp-config.example.json mcp-config.json
   # Edite o arquivo com seu caminho e credenciais
   ```

## 🔧 Configuração do Spotify

1. Acesse o [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
2. Clique em "Create App"
3. Preencha os dados:
   - **App name**: MCP Spotify Server
   - **App description**: Servidor MCP para integração com Spotify
4. Após criar, copie o **Client ID** e **Client Secret**
5. Clique em "Edit Settings" e adicione `http://localhost:3000/callback` nas **Redirect URIs**

## 🌐 Configuração do ngrok

Para que o OAuth do Spotify funcione corretamente, você precisa expor seu servidor local para a internet. O ngrok é a ferramenta recomendada para isso.

### 1. Crie uma conta no ngrok (opcional mas recomendado)
- Acesse [ngrok.com](https://ngrok.com) e crie uma conta gratuita
- Isso permite URLs estáveis e remove limitações de tempo

### 2. Configure o ngrok
```bash
# Autentique sua conta (opcional)
ngrok config add-authtoken SEU_TOKEN_AQUI

# Exponha a porta 8080
ngrok http 8080
```

### 3. Atualize a Redirect URI
1. Copie a URL HTTPS fornecida pelo ngrok (ex: `https://abc123.ngrok.io`)
2. No Spotify Dashboard, adicione `https://abc123.ngrok.io/callback` nas **Redirect URIs**
3. Atualize seu arquivo `.env`:
   ```env
   SPOTIFY_REDIRECT_URI=https://abc123.ngrok.io/callback
   ```

### 4. Inicie o servidor
```bash
# Em um terminal, mantenha o ngrok rodando
ngrok http 8080

# Em outro terminal, inicie o servidor
npm run dev
```

## 🚀 Uso

### Desenvolvimento
```bash
# Terminal 1: Inicie o ngrok
ngrok http 8080

# Terminal 2: Inicie o servidor
npm run dev
```

### Produção
```bash
npm run build
npm start
```

## 🎯 Ferramentas Disponíveis

### Autenticação
- `spotify_auth` - Inicia o processo de autenticação
- `spotify_set_tokens` - Finaliza a autenticação com o `code` de retorno

### Busca
- `spotify_search` - Busca por músicas, artistas, álbuns ou playlists

### Controle de Reprodução
- `spotify_play` - Toca uma música específica
- `spotify_pause` - Pausa a reprodução
- `spotify_resume` - Retoma a reprodução
- `spotify_next` - Pula para a próxima música
- `spotify_previous` - Volta para a música anterior

### Informações
- `spotify_current_playing` - Obtém informações sobre a música atual
- `spotify_devices` - Lista dispositivos disponíveis
- `spotify_playlists` - Lista playlists do usuário

### Playlists
- `spotify_play_playlist` - Toca uma playlist específica

## 📝 Exemplos de Uso

### Fluxo de Autenticação
1) Iniciar o login (vai abrir o navegador)
```json
{
  "name": "spotify_auth",
  "arguments": {}
}
```
2) Depois de autorizar no Spotify, copie o `code` retornado e finalize:
```json
{
  "name": "spotify_set_tokens",
  "arguments": { "code": "SEU_CODE_AQUI" }
}
```

### Buscar uma música
```json
{
  "name": "spotify_search",
  "arguments": {
    "query": "Bohemian Rhapsody",
    "type": "track",
    "limit": 5
  }
}
```

### Tocar uma música
```json
{
  "name": "spotify_play",
  "arguments": {
    "track_id": "4uLU6hMCjMI75M1A2tKUQC"
  }
}
```

### Buscar playlists
```json
{
  "name": "spotify_playlists",
  "arguments": {
    "limit": 10
  }
}
```

## ✅ Validar o Servidor MCP

Para verificar se o servidor está configurado corretamente:

```bash
npm run validate
```

Este comando irá:
- ✅ Verificar se o build existe
- ✅ Validar o arquivo `.env`
- ✅ Checar variáveis de ambiente
- ✅ Mostrar a configuração correta para o cliente MCP

### Configuração do Cliente MCP

Após validar, você pode usar a configuração sugerida pelo script no seu arquivo de configuração do cliente:

**Para Cursor** (`~/.cursor/mcp.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": "sua_redirect_uri"
      }
    }
  }
}
```

**Para Claude Desktop** (`~/.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": "sua_redirect_uri"
      }
    }
  }
}
```

**Importante:** 
- Use `node dist/index.js` (não `tsx src/index.ts`) para produção
- Certifique-se de que o caminho `cwd` está correto
- Inclua as variáveis de ambiente no arquivo de configuração
- Após alterar a configuração, reinicie o cliente MCP

## 🔒 Segurança

- As credenciais do Spotify são armazenadas apenas localmente
- Os tokens de acesso são renovados automaticamente
- Nenhuma informação é enviada para servidores externos (exceto Spotify)

## 🐛 Solução de Problemas

### Erro de Autenticação
- Verifique se as credenciais no `.env` estão corretas
- Confirme se a Redirect URI está configurada no Spotify Dashboard
- Certifique-se de que o ngrok está rodando e a URL está atualizada no `.env`
- Verifique se a URL do ngrok no Spotify Dashboard corresponde à URL no arquivo `.env`

### Erro "Cannot find module" ou caminho incorreto
- **Erro**: `Cannot find module '/Users/.../src/index.ts'`
- **Solução**: Use `node dist/index.js` ao invés de `tsx src/index.ts` no arquivo de configuração do MCP
- Execute `npm run build` antes de usar o servidor
- Certifique-se de que o `cwd` no arquivo de configuração aponta para o diretório correto do projeto
- Execute `npm run validate` para gerar a configuração correta

### Dispositivo Não Encontrado
- Certifique-se de que o Spotify está aberto em algum dispositivo
- Verifique se o dispositivo está ativo na sua conta Spotify

### Erro de Permissões
- Algumas funcionalidades requerem Spotify Premium
- Verifique se todas as permissões foram concedidas durante a autenticação

### Problemas com ngrok
- **URL muda a cada reinicialização**: Use uma conta ngrok gratuita para URLs estáveis
- **Erro de conexão**: Verifique se o ngrok está rodando na porta correta (3000)
- **Timeout**: Certifique-se de que o servidor está rodando antes de iniciar o ngrok
- **URL não acessível**: Verifique se o firewall não está bloqueando a conexão

## 📄 Licença

MIT License - veja o arquivo [LICENSE](LICENSE) para detalhes.

## 🤝 Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues e pull requests.

## 📞 Suporte

Se você encontrar problemas ou tiver dúvidas, abra uma issue no repositório.