feat: add Spotify Web API MCP connector with OAuth2 and comprehensive music tools

[MarsZDF]

Summary

• Add comprehensive Spotify Web API MCP connector with OAuth2 Authorization Code flow
• 12 essential tools covering music discovery, user data, and playback control
• Robust TypeScript interfaces and comprehensive test coverage

Key Features

• Music Discovery: Advanced search for tracks, artists, albums, and playlists with market filtering
• User Integration: Access user profile, playlists, and saved tracks
• Playback Control: Full control over Spotify playback (play/pause/skip) with device targeting
• OAuth2 Flow: Secure Authorization Code flow with automatic token refresh
• Production Ready: Comprehensive error handling, rate limiting awareness, and pagination support

Tools Included

1. SEARCH_TRACKS - Advanced track search with market and filter support
2. SEARCH_ARTISTS - Artist discovery and search
3. SEARCH_ALBUMS - Album search and discovery
4. SEARCH_PLAYLISTS - Public playlist search
5. GET_USER_PROFILE - User account information and statistics
6. GET_USER_PLAYLISTS - User's personal and collaborative playlists
7. GET_USER_SAVED_TRACKS - User's liked/saved tracks
8. GET_CURRENT_PLAYING - Real-time playback information
9. PAUSE_PLAYBACK - Pause current playback
10. RESUME_PLAYBACK - Resume/start playback
11. SKIP_TO_NEXT - Skip to next track
12. SKIP_TO_PREVIOUS - Skip to previous track

Technical Implementation

• Authentication: OAuth2 Authorization Code flow with refresh token support
• Type Safety: Comprehensive TypeScript interfaces for all Spotify API responses
• Error Handling: Robust error handling following repository patterns
• Testing: 21 comprehensive tests with MSW mocking (100% passing)
• Rate Limiting: Built-in awareness of Spotify's 30-second rolling window limits
• Market Support: Region-specific content filtering (US, GB, etc.)
• Pagination: Proper pagination support for large datasets
• Device Targeting: Optional device ID support for playback controls

OAuth2 Scopes Required

• user-read-private - Access user profile
• user-read-email - Access user email
• user-library-read - Access saved tracks
• playlist-read-private - Access private playlists
• playlist-read-collaborative - Access collaborative playlists
• user-read-currently-playing - Access current playback
• user-read-playback-state - Access playback state
• user-modify-playback-state - Control playback

Test Plan

• All 21 tests passing with comprehensive MSW mocking
• TypeScript compilation successful with strict type checking
• Biome lint checks passing with zero warnings
• Code formatting consistent with repository standards
• Proper OAuth2 token refresh flow testing
• Error handling validation for API failures
• Integration testing with mock Spotify API responses

Usage Examples

// Search for tracks
await spotify.searchTracks({ q: "Bohemian Rhapsody", market: "US", limit: 10 });

// Get user's playlists  
await spotify.getUserPlaylists({ limit: 20 });

// Control playback
await spotify.pausePlayback();
await spotify.skipToNext();

🤖 Generated with Claude Code

---

Summary by cubic

Add a production-ready Spotify Web API MCP connector with OAuth2 (Authorization Code + refresh). It provides search, user library, and playback tools, with strong typing and thorough tests.

• New Features

  • 12 tools across discovery, user data, and playback: search tracks/artists/albums/playlists; get profile/playlists/saved tracks/currently playing; pause/resume/next/previous.
  • OAuth2 with automatic token refresh and robust error handling.
  • Type-safe interfaces, pagination, market filtering, device targeting, and rate-limit awareness.
  • 21 MSW + Vitest tests; connector added to Connectors and exports in index.

• Migration

  • Create a Spotify app and set credentials (clientId, clientSecret).
  • Use the web OAuth2 flow to obtain initial tokens; the connector handles refresh.
  • Required scopes: user-read-private, user-read-email, user-library-read, playlist-read-private, playlist-read-collaborative, user-read-currently-playing, user-read-playback-state, user-modify-playback-state.

[cubic-dev-ai]

No issues found across 3 files