# spotify-mcp

Spotify Web API'yı MCP olarak Hermes'e bağlayan sunucu. **Computer use / UI otomasyonu yok** — her şey resmi Spotify Web API ile. Windows, macOS ve Linux'ta çalışır; hesaptaki hangi cihaz aktifse (desktop, telefon, web) onu kontrol eder.

## Özellikler

- ▶️ Şarkı/albüm/sanatçı/playlist ara & çal
- ⏸️ Duraklat / devam et / ileri / geri
- 🔊 Ses seviyesi (0-100)
- ⏭️ Sıraya ekle (queue)
- 📱 Aktif cihazları listele, çalan şarkıyı göster

## Kurulum

### 1. Spotify Developer App oluştur

1. https://developer.spotify.com/dashboard adresine gir → **Create app**
2. App name/description doldur, **Redirect URI** olarak şunu ekle:
   ```
   http://127.0.0.1:8890/callback
   ```
3. Client ID'yi (ve varsa Client Secret'ı) kopyala.

### 2. Config yaz

```bash
mkdir -p ~/.spotify-mcp
```

`~/.spotify-mcp/config.json`:

```json
{
  "clientId": "SENIN_CLIENT_ID",
  "clientSecret": "SENIN_CLIENT_SECRET"
}
```

### 3. OAuth (bir kere)

```bash
node auth.js
```

Tarayıcı açılır, Spotify'a girip **Agree**'e basarsın, token `~/.spotify-mcp/tokens.json`'a kaydedilir. Refresh token otomatik yenilenir.

### 4. Hermes'e ekle

```bash
printf 'Y\n' | hermes mcp add spotify --command node --args C:/Users/<user>/Documents/GitHub/spotify-mcp/server.js
hermes mcp ls
hermes mcp test spotify
```

> MCP tool'ları **yeni oturumlarda** yüklenir — ekledikten sonra yeni bir sohbet başlat.

## Tool'lar

| Tool | Açıklama |
|---|---|
| `spotify_play_track(query[, device])` | Şarkı ara & hemen çal |
| `spotify_play_artist(name[, device])` | Sanatçı çal |
| `spotify_play_album(query[, device])` | Albüm çal |
| `spotify_play_playlist(name[, device])` | Playlist çal |
| `spotify_play_uri(uri[, device])` | Direkt spotify: URI çal |
| `spotify_queue_track(query)` | Sıraya ekle |
| `spotify_pause` / `spotify_resume([device])` | Duraklat / devam |
| `spotify_next` / `spotify_previous` | İleri / geri |
| `spotify_set_volume(percent[, device])` | Ses 0-100 |
| `spotify_playback_state` | Ne çalıyor, hangi cihazda |
| `spotify_list_devices` | Aktif cihazlar (id'leriyle) |
| `spotify_search(query, type)` | Arama |
| `spotify_auth_status` | Auth durumu |

> `device` = cihaz adı. **Önce tam eşleşme** aranır (örn. `"FURKAN"` → Windows PC), tam eşleşme yoksa alt dize (örn. `"Macbook"` → "Furkan Macbook Air"). Dikkat: `"FURKAN"` aynı zamanda "Furkan Macbook Air"in alt dizesi — bu yüzden tam eşleşme önceliklidir! Verilmezse aktif cihazda çalar. Cihaz değişiminde aktif cihaz önce pause edilir (~7sn oturum bırakma süresi), sonra hedefe play edilir.

## Notlar

- Playback kontrolü (play/pause/skip/volume) **Premium** hesap gerektirir (Spotify kuralı). Arama ve auth her hesapta çalışır.
- Playback, hesabında **aktif olan cihaza** gider. Cihaz yoksa: Spotify'ı aç, bir şarkı başlat, sonra tekrar dene.
- Sıfır npm bağımlılığı — Node >= 18 yeterli.

## Test (probe)

```bash
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1.0"}}}\n' | node server.js
```