Elnor Repo Reader

ELNOR REPO READER TEXT MIRROR
Original path: Current Specs/Connector and Integration Specs/SPOTIFY_INTEGRATION_PART_1_IMMEDIATE_BUILD.md
Source repo: /Users/OpenClaw1/Elnor/Elnor Specs
Git branch: main
Git commit: dbaa25962edc11ab30e8d4ca1715f9ae5bf77331
Generated: 2026-06-09T01:23:58.539Z

---

# Spotify Integration — Part 1: Immediate Build (No Backend Required)

**Date:** 2026-04-11
**Status:** Ready to build now — no EC, OpenClaw, or backend dependencies
**Scope:** Spotify playback control, search, playlists, listening data access, and web player viewing within Q Dashboard
**Dependencies:** Spotify Premium account, Spotify Developer app registration, Spotify MCP server

---

## 1. What You're Building

Three things that work together:

1. **Spotify web player in a Q browser tab** — visual surface for browsing and seeing what's playing
2. **Spotify MCP server** — gives Elnor tools to control playback, search, manage playlists, read listening history
3. **Conversational music interaction** — talk to Elnor about music through any chat surface, Elnor uses the MCP tools

No backend infrastructure needed. The MCP server runs as a local process. The web player is just a URL in a Q tab. Elnor's tools work through the existing OpenClaw runtime.

---

## 2. Spotify Developer Setup (One-Time, ~10 Minutes)

### Step 1: Create a Spotify Developer Account
1. Go to https://developer.spotify.com/dashboard
2. Log in with your Spotify Premium account
3. Accept the Developer Terms of Service

### Step 2: Register an Application
1. Click **"Create App"**
2. Fill in:
   - **App name:** `Q Dashboard - ELNOR`
   - **App description:** `AI music assistant for Q Dashboard`
   - **Redirect URI:** `http://127.0.0.1:8080/callback`
   - **Which APIs are you planning to use?** Select **"Web API"**
3. Click **Create**

### Step 3: Note Your Credentials
- **Client ID** — copy this
- **Client Secret** — click "Show Client Secret" and copy this

### Step 4: Required Scopes

The MCP server will request these OAuth scopes during first authentication:

```
user-read-playback-state        # See what's currently playing
user-modify-playback-state      # Play, pause, skip, volume, transfer devices
user-read-currently-playing     # Get the current track
user-read-recently-played       # Listening history (last 50 tracks)
user-top-read                   # Top tracks and artists (short/medium/long term)
playlist-read-private           # Read private playlists
playlist-read-collaborative     # Read collaborative playlists
playlist-modify-public          # Create/edit public playlists
playlist-modify-private         # Create/edit private playlists
user-library-read               # See saved albums/tracks
user-library-modify             # Save/remove albums/tracks
user-read-playback-position     # Podcast playback position
```

---

## 3. MCP Server Setup

### 3.1 Recommended MCP Server

Use `varunneal/spotify-mcp` (Python) or `tylerpina/spotify-mcp` (TypeScript). Both are well-maintained and cover the full Spotify API surface.

**Python option (recommended — matches your stack):**

```bash
# Clone
git clone https://github.com/varunneal/spotify-mcp.git
cd spotify-mcp

# Install
pip install -e .

# Configure
export SPOTIFY_CLIENT_ID="your-client-id"
export SPOTIFY_CLIENT_SECRET="your-client-secret"
export SPOTIFY_REDIRECT_URI="http://127.0.0.1:8080/callback"
```

### 3.2 Register with OpenClaw

Add the MCP server to OpenClaw's configuration so Elnor can discover and use its tools:

```json
// In OpenClaw MCP server config
{
  "name": "spotify",
  "transport": "stdio",
  "command": "uv",
  "args": ["--directory", "/path/to/spotify-mcp", "run", "spotify-mcp"],
  "env": {
    "SPOTIFY_CLIENT_ID": "your-client-id",
    "SPOTIFY_CLIENT_SECRET": "your-client-secret",
    "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8080/callback"
  }
}
```

### 3.3 First Authentication

On first use, the MCP server opens a browser window for Spotify OAuth. You log in, authorize the app, and it stores the token locally (auto-refreshes). This is a one-time step — after that, Elnor has persistent access.

### 3.4 Available Tools After Setup

Once registered, Elnor has these tools available:

| Tool | What It Does |
|------|-------------|
| `spotify_play` | Play a track, album, playlist, or resume playback |
| `spotify_pause` | Pause playback |
| `spotify_skip` | Skip to next track |
| `spotify_previous` | Go to previous track |
| `spotify_volume` | Set volume (0-100) |
| `spotify_search` | Search for tracks, artists, albums, playlists |
| `spotify_get_current` | Get currently playing track |
| `spotify_get_queue` | View upcoming tracks |
| `spotify_add_to_queue` | Add a track to the queue |
| `spotify_get_recently_played` | Get last 50 played tracks |
| `spotify_get_top_tracks` | Get top tracks (short/medium/long term) |
| `spotify_get_top_artists` | Get top artists (short/medium/long term) |
| `spotify_get_devices` | List available playback devices |
| `spotify_transfer_playback` | Move playback to a different device |
| `spotify_create_playlist` | Create a new playlist |
| `spotify_add_to_playlist` | Add tracks to a playlist |
| `spotify_remove_from_playlist` | Remove tracks from a playlist |
| `spotify_get_playlist` | Get playlist details and tracks |
| `spotify_get_playlists` | List user's playlists |
| `spotify_get_audio_features` | Get audio analysis (tempo, energy, danceability, etc.) |
| `spotify_save_track` | Save a track to library |
| `spotify_remove_saved_track` | Remove a track from library |
| `spotify_shuffle` | Toggle shuffle mode |
| `spotify_repeat` | Set repeat mode (off/context/track) |

---

## 4. Spotify Web Player in Q

### 4.1 Opening the Web Player

The Spotify web player at `open.spotify.com` renders in a Q web browser tab. No special integration needed — it's just a URL.

**Suggested setup:**
- Bookmark `https://open.spotify.com` in Q's bookmarks bar for one-click access
- Or add a "Spotify" entry to the Pages section in the Nav pane (custom page type)
- The web player shows album art, track progress, queue, playlists — full visual interface

### 4.2 API ↔ Web Player Sync

When Elnor controls playback via the API:
- Track changes appear instantly in the web player tab (Spotify pushes state to all connected clients)
- Volume changes reflect immediately
- Queue additions show up in the web player's queue view
- Playlist modifications are visible when you navigate to the playlist

When you control playback via the web player:
- Elnor's `spotify_get_current` tool sees the new state immediately
- Listening history is tracked regardless of whether you or Elnor initiated playback

**They are fully synced.** The API and web player both talk to Spotify's backend — they see the same state.

### 4.3 Device Targeting

If you have the Spotify web player open in Q AND the Spotify desktop app running, Elnor needs to know which device to target. By default, the API sends commands to the last active device. If the Q web tab is focused and playing, commands go there.

Elnor can explicitly target a device:
```
You: "Play this on my MacBook speakers, not the web player"
Elnor: [calls spotify_get_devices → finds devices → calls spotify_transfer_playback to MacBook → calls spotify_play]
```

---

## 5. Conversational Music Interaction

### 5.1 What Works Immediately (No Skills Needed)

With just the MCP server running, you can talk to Elnor about music through any chat surface:

**Playback control:**
- "Play some jazz"
- "Pause" / "Skip this" / "Go back"
- "Turn it up" / "Volume to 30"
- "What's playing right now?"
- "Play this on my phone instead"

**Search and discovery:**
- "Find me something by Coltrane"
- "Search for ambient electronic playlists"
- "What's the tempo of this song?"

**Listening history:**
- "What have I been listening to lately?"
- "Who are my most-played artists this month?"
- "What are my top tracks of all time?"

**Playlist management:**
- "Create a playlist called 'Trial Prep Focus'"
- "Add this song to my Trial Prep playlist"
- "Show me what's in my Henderson playlist"
- "Remove the last three tracks from that playlist"

**Library:**
- "Save this album"
- "Do I have any Miles Davis in my library?"

### 5.2 Conversational Learning (DOC3 Passive Capture)

When you interact with Elnor about music, the normal DOC3 knowledge extraction pipeline captures preferences from conversation — the same way it learns any other preference:

- "I love this song" → DOC72 preference node: `{type: "preference", entity: "song_name", valence: "positive"}`
- "I hate country" → DOC72 preference node: `{type: "preference", entity: "country_genre", valence: "negative"}`
- "Play something calm, I'm stressed" → DOC72 observation: `{type: "observation", context: "stressed", music_preference: "calm"}`
- "This is my trial prep music" → DOC72 association: `{type: "association", entity: "trial_prep", linked_entity: "current_playlist"}`

This requires no special configuration — it's just the standard DOC3 extraction running on music-related conversations. The only requirement is that DOC3's extraction pipeline is active (which it will be once the backend is built). Until then, these preferences exist only in conversation context.

---

## 6. Q Settings: Spotify

Add to Q Settings page:

```
Settings > Integrations > Spotify
├─ Account
│   ├─ Status: ● Connected as [spotify_username]
│   ├─ [Disconnect] [Re-authenticate]
│   └─ Subscription: Premium ✓
├─ Playback defaults
│   ├─ Default device: [Auto (last active) ▾]
│   ├─ Default volume: [50        ] (when Elnor initiates playback)
│   └─ Shuffle default: ○ On  ● Off
├─ Privacy
│   ├─ ☑ Allow Elnor to view listening history
│   ├─ ☑ Allow Elnor to control playback
│   ├─ ☑ Allow Elnor to modify playlists
│   └─ ☐ Allow Elnor to modify library (save/remove albums)
└─ Web player
    ├─ ☑ Show Spotify in Pages navigation
    └─ Bookmark URL: [https://open.spotify.com]
```

---

## 7. Implementation Checklist

```
□ Create Spotify Developer account and register app
□ Clone and configure Spotify MCP server
□ Register MCP server with OpenClaw
□ Complete first OAuth authentication
□ Test basic commands: play, pause, search, get current track
□ Bookmark open.spotify.com in Q browser
□ Test API ↔ web player sync (Elnor plays something → appears in web tab)
□ Add Spotify settings section to Q Settings page
□ Test playlist creation and modification
□ Test device listing and transfer
```

**Estimated build time:** 1-2 hours for setup and basic testing. The MCP server is pre-built — you're just configuring it and connecting it to OpenClaw.

---

## 8. Edge Cases

| Scenario | Behavior |
|----------|----------|
| No Spotify Premium | MCP server fails on playback control. Search and metadata still work. Toast: "Spotify Premium required for playback control." |
| Spotify not playing on any device | `spotify_play` needs a device. Elnor calls `spotify_get_devices` first. If no device is active, Elnor suggests opening the web player in Q. |
| Token expired | MCP server auto-refreshes tokens. If refresh fails, toast: "Spotify session expired. Re-authenticate in Settings." |
| Spotify web player tab closed | API still works — commands go to whatever other device is active (desktop app, phone, speaker). Web player is visual only. |
| Rate limiting | Spotify API allows ~180 requests/minute. Normal usage won't hit this. Scheduled intake (Part 2) should batch requests. |
| No internet | Nothing works. Spotify is cloud-only. Toast: "Spotify requires internet connection." |