🎉 Spotify MCPB v0.2.4-enhanced

Major Feature Release: Enhanced Smart Play & User Library Management

✨ Enhanced Smart Play Functionality

The flagship feature of this release! The spotify_play tool now intelligently handles multiple scenarios:

• 🔄 Resume Playback - Call with no parameters to resume current playback
• 🎵 Search & Play - Call with a query to search and play tracks instantly
• 📂 Playlist by Name - Call with playlist name to find and play user playlists
• 🧠 Context Aware - Remembers recently created playlists for smart suggestions

Example Usage:

"Play" → Resumes current playback
"Play some jazz music" → Searches for jazz tracks and plays them
"Play my workout playlist" → Finds and plays your workout playlist
"Play Study Music" → Plays recently created "Study Music" playlist

📚 User Library Management (5 New Tools)

Complete management of your Spotify library:

• spotify_get_saved_tracks - Get your Liked Songs with pagination support
• spotify_save_tracks - Add tracks to your Liked Songs (batch operations)
• spotify_remove_saved_tracks - Remove tracks from Liked Songs
• spotify_check_saved_tracks - Check if tracks are already saved
• spotify_get_saved_albums - Browse your saved albums with pagination

🎵 Playlist Playback

• spotify_play_playlist - Direct playlist playback by name or Spotify ID
• Fuzzy Matching - Supports partial playlist name matching
• Smart Search - Automatically searches your playlist collection

🔧 Technical Improvements

• Context Tracking - Server remembers recently created/accessed playlists
• Smart Detection - Intelligent content type detection (tracks vs playlists)
• Enhanced Error Handling - Comprehensive validation and user-friendly error messages
• Rich Responses - Detailed feedback about what's playing and why
• Performance Optimized - Efficient API usage with caching and batching

📊 Release Statistics

🚀 What's Included

Complete Tool List (22 Tools)

Setup & Authentication:

• spotify_get_refresh_token - Interactive OAuth flow

Enhanced Playback Control:

• spotify_play - ENHANCED Smart play with multiple scenarios
• spotify_play_playlist - NEW Direct playlist playback
• spotify_pause - Pause playback
• spotify_next_track - Skip to next
• spotify_previous_track - Skip to previous
• spotify_set_volume - Volume control (0-100)

Track Information:

• spotify_get_current_track - Currently playing info
• spotify_get_playback_state - Full playback state
• spotify_search_tracks - Search Spotify catalog

Playlist Management:

• spotify_create_playlist - Create new playlists
• spotify_add_tracks_to_playlist - Add tracks with deduplication
• spotify_get_playlist - Get playlist details
• spotify_get_user_playlists - List user playlists

User Library Management (NEW):

• spotify_get_saved_tracks - Get Liked Songs
• spotify_save_tracks - Save tracks to library
• spotify_remove_saved_tracks - Remove from library
• spotify_check_saved_tracks - Check saved status
• spotify_get_saved_albums - Get saved albums

Recommendations & Analysis:

• spotify_get_recommendations - AI-powered recommendations
• spotify_get_audio_features - Audio feature analysis
• spotify_analyze_playlist - Playlist statistics

📥 Installation

1. Download the bundle below: spotify-mcpb-0.2.4-enhanced.mcpb
2. Double-click the file to install in Claude Desktop
3. Configure your Spotify API credentials when prompted
4. Start using all 22 tools immediately!

🆕 What's New in This Version

• ✅ Enhanced Smart Play - Multi-scenario play functionality
• ✅ User Library Management - 5 new tools for Liked Songs/Albums
• ✅ Playlist Playback - Direct playlist control by name
• ✅ Context Tracking - Remembers recent playlists and searches
• ✅ Smart Detection - Automatic content type recognition
• ✅ Rich Responses - Detailed feedback and status information
• ✅ Documentation Updates - Comprehensive docs across all files
• ✅ Version Management - Consistent v0.2.4 references throughout

🔄 Migration from Previous Versions

• Backward Compatible - All existing functionality preserved
• Enhanced Features - spotify_play now has additional capabilities
• New Tools - 6 new tools added (library management + playlist playback)
• Same Installation - Just download and install the new bundle

🛠️ Development & Technical Details

• MCP SDK: v1.20.1 (latest)
• Node.js: ≥18.0.0 required
• Spotify API: Full Web API v1 compliance
• Authentication: OAuth 2.0 with refresh token auto-renewal
• Error Handling: Comprehensive validation and retry logic
• Performance: Caching, batching, and concurrency limiting

🎯 Perfect For

• Music Discovery - AI-powered recommendations and smart search
• Playlist Management - Create, analyze, and organize playlists
• Library Organization - Manage Liked Songs and saved albums
• Daily Listening - Smart play functionality for any scenario
• Cross-Platform Use - Works on Windows, macOS, and Linux

❤️ Acknowledgments

• Kenneth Lien - Original spotify-dxt project
• Anthropic - MCPB specification and Claude Desktop integration
• Spotify - Web API platform enabling this integration
• Community - Feedback and feature requests

Download & Get Started

Bundle: spotify-mcpb-0.2.4-enhanced.mcpb (attached below)
Setup Guide: See SETUP.md
Documentation: Complete Documentation Index

Ready to transform your Spotify experience with AI? Download now! 🎵

🎉 Major Authentication Fix Release

This release resolves the critical refresh token requirement issue that was blocking user installations. Users can now install the bundle without needing a refresh token upfront!

🔧 Critical Fixes

Authentication Flow ✅ RESOLVED

• Issue: manifest.json required refresh_token, blocking installation in Claude Desktop
• Solution: Made refresh_token optional (required: false, default: "")
• Impact: Users can now install seamlessly and get refresh token via Claude after installation

Missing Authentication Checks ✅ RESOLVED

• Issue: 8 handler methods lacked proper authentication validation
• Solution: Added ensureReady() calls to all handler methods:
  • handleGetRefreshToken, handleSearchTracks, handleCreatePlaylist
  • handleAddTracksToPlaylist, handleGetPlaylist, handleGetUserPlaylists
  • handleGetRecommendations, handleAnalyzePlaylist
• Impact: Robust authentication across all 16 MCP tools

🚀 New Features

Interactive OAuth Flow 🆕

• New get-refresh-token.js - Interactive OAuth server on 127.0.0.1:8888
• New manual-token.js - Fallback manual token generation
• New npm scripts: npm run get-token, npm run manual-token
• Automated OAuth 2.0 authorization code exchange

Enhanced Documentation 📚

• New LOCAL_TESTING.md - Complete local development guide
• Updated all documentation with v0.2.2 information
• Enhanced copilot instructions with new learnings and best practices

⚡ Technical Improvements

Network Compatibility 🌐

• Updated all redirect URIs from localhost to 127.0.0.1
• Better cross-platform compatibility (Windows/macOS/Linux)
• Improved OAuth flow reliability

Dependencies & Performance ��

• Updated MCP SDK from v0.6.0 to v1.20.1
• Bundle size: 3.0MB compressed, 10.2MB unpacked
• Zero vulnerabilities in production dependencies
• 1,771 total files (628 ignored in bundle)

🛠️ For Developers

Local Development 💻

• Enhanced server initialization for partial credentials
• Graceful degradation without refresh token
• Comprehensive error messages and logging
• Interactive token generation tools

Code Quality ✨

• All 16 MCP tools have proper authentication validation
• Improved error handling across all endpoints
• Enhanced input validation and sanitization
• Updated GitHub issue templates and documentation

📋 Installation

One-Click Install (Recommended)

1. Download spotify-mcpb-0.2.2.mcpb
2. Double-click to install in Claude Desktop
3. Enter your Spotify Client ID and Client Secret
4. Ask Claude: "Help me get a Spotify refresh token"
5. Start using: "What's playing on Spotify?" 🎵

Manual Install (Developers)
�ash git clone https://github.com/fabioc-aloha/spotify-mcpb.git cd spotify-mcpb npm install npm run get-token # Interactive token generation npm start # Run locally

🔗 What's Included

16 MCP Tools 🎵

• Playback control (play, pause, next, previous, volume)
• Track info (current track, playback state, search)
• Playlist management (create, add tracks, get details, list playlists)
• Recommendations & analysis (get recommendations, audio features, playlist stats)
• Interactive setup (get refresh token via OAuth flow)

🙏 Acknowledgments

• Original Project: spotify-dxt by Kenneth Lien (macOS version)
• MCPB Specification: Anthropic for the MCP Bundle format
• Spotify Web API: Spotify for the comprehensive developer platform

📊 Bundle Statistics

• Bundle Size: 3.0MB compressed, 10.2MB unpacked
• Total Files: 1,771 files
• Production Dependencies: 60 packages (5 direct)
• MCP Tools: 16 comprehensive Spotify control tools
• Cross-Platform: Windows 11, macOS, Linux support
• Security: 0 vulnerabilities found

The refresh token installation issue is now completely resolved! 🎉

Users can install the bundle immediately and Claude will help them get their refresh token through an easy interactive process.

🎉 Spotify MCPB v0.2.1 - Major Fixes & Improvements

🐛 Critical Fixes

Fixed Refresh Token Authentication Issue

• Issue: Server required refresh token to start, but users needed server to GET refresh token (chicken-and-egg problem)
• Fix: Server now starts with just CLIENT_ID and CLIENT_SECRET
• Result: Users can now use spotify_get_refresh_token tool to get initial tokens ✅

Enhanced Error Handling

• Better OAuth error messages for expired codes (invalid_grant)
• Clear guidance for wrong credentials (invalid_client)
• User-friendly instructions for each error scenario

🏆 100% GitHub Health Score Achieved

Added all community health files:

• CONTRIBUTING.md - Comprehensive contribution guidelines (+15%)
• CODE_OF_CONDUCT.md - Contributor Covenant v2.1 (+15%)
• SECURITY.md - Vulnerability reporting & security best practices (+10%)
• Issue Templates - Bug report, feature request, question templates (+10%)
• Pull Request Template - Comprehensive PR checklist (+8%)

📦 Bundle Information

• File: spotify-mcpb-0.2.1.mcpb (3.0 MB)
• Total Files: 1,768 (627 ignored)
• Dependencies: 117 packages, 0 vulnerabilities
• Platforms: Windows, macOS, Linux
• MCP Tools: 16 comprehensive tools

🚀 Complete Working Flow

1. Install Bundle - Double-click .mcpb file in Claude Desktop
2. Minimal Setup - Add just CLIENT_ID and CLIENT_SECRET
3. Generate Token - Use spotify_get_refresh_token tool
4. Configure - Add refresh token to configuration
5. Use All Tools - Full Spotify control and playlist management

Download the bundle below and get started in minutes!