iflow-mcp_jamiew-spotify-mcp 0.2.0__py3-none-any.whl

iflow_mcp_jamiew_spotify_mcp-0.2.0.dist-info/METADATA

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: iflow-mcp_jamiew-spotify-mcp
+Version: 0.2.0
+Summary: MCP spotify project
+Author-email: Varun Srivastava <varun.neal@berkeley.edu>
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp[cli]>=1.12.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: spotipy>=2.25.0
+Dynamic: license-file
+
+# spotify-mcp MCP server
+
+MCP server connecting Claude with Spotify. This fork of [varunneal/spotify-mcp](https://github.com/varunneal/spotify-mcp) adds smart-batching tools and advanced playlist features that optimize API usage.
+
+## Features
+
+### Core Functionality
+- **Playback Control**: Start, pause, skip tracks, manage queue
+- **Search & Discovery**: Find tracks, albums, artists, playlists with pagination  
+- **Real-time State**: Live user profile and playback status
+
+### Enhanced Playlist Tools (New in this fork)
+- **Smart Batch Operations**: Add/remove up to 100 tracks in single API calls
+- **Large Playlist Support**: Efficiently handle playlists with 1000+ tracks using pagination
+- **Advanced Playlist Management**: Create, modify details, bulk track operations
+- **API-Optimized Workflows**: Intelligent batching reduces API calls by 60-80%
+
+## Installation
+
+### 1. Get Spotify API Keys
+1. Create account at [developer.spotify.com](https://developer.spotify.com/)
+2. Create app with redirect URI: `http://localhost:8888`
+
+### 2. Install the MCP Server
+```bash
+git clone https://github.com/jamiew/spotify-mcp.git
+cd spotify-mcp
+uv sync
+```
+
+### 3. Configure Claude Desktop
+Add to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+```json
+"spotify": {
+  "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://localhost:8888"
+  }
+}
+```
+
+**Requirements**: Spotify Premium account, `uv` >= 0.54
+
+## Usage Examples
+
+- **"Create a chill study playlist with 20 tracks"** → Search + playlist creation + bulk track addition
+- **"Show me the first 50 tracks from my 'Liked Songs'"** → Pagination for large playlists  
+- **"Find similar artists to Radiohead and add their top tracks to my queue"** → Search + artist info + queue management
+
+## Development
+
+Built with **FastMCP framework** featuring 13 focused tools, type-safe APIs, and comprehensive test coverage.
+
+**Debug with MCP Inspector:**
+```bash
+npx @modelcontextprotocol/inspector uv --directory /path/to/spotify_mcp run spotify-mcp
+```

iflow_mcp_jamiew_spotify_mcp-0.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+iflow_mcp_jamiew_spotify_mcp-0.2.0.dist-info/licenses/LICENSE,sha256=AsY4d4FvHVVzMmKbGN_ej567i2ID07OwJ_O-QNndxNo,1077
+spotify_mcp/__init__.py,sha256=E0zThznQYn2uzuoIt7n3iMedc-TIQaOlnY7hTLItx9I,544
+spotify_mcp/errors.py,sha256=4RiE_wJPxK723RoILulss5rBIQ8pOY_9id6mwzXl86U,9925
+spotify_mcp/fastmcp_server.py,sha256=1oSwKWbgTbjhDNvarv1coPEk09fF1jayU1w1ru7ILrE,35985
+spotify_mcp/logging_utils.py,sha256=fkg7RhjrTx6TdciWSCSIn8zL6d50orPowrPD8AoiZ04,4842
+spotify_mcp/spotify_api.py,sha256=TG_buRYo_UaLT8EmWGBH0U-3CiWRoirc-0-lsUjpc_I,21711
+spotify_mcp/utils.py,sha256=4qlRhzAeMmBeRN-ygyZhyHxR41_q8nHkFMN1p-p9bNQ,7067
+iflow_mcp_jamiew_spotify_mcp-0.2.0.dist-info/METADATA,sha256=nhsD69LsgQ9cW-CiCEoGif8MYZWbX6V8W7sVW8_OoH0,2592
+iflow_mcp_jamiew_spotify_mcp-0.2.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+iflow_mcp_jamiew_spotify_mcp-0.2.0.dist-info/entry_points.txt,sha256=3zhK_-NjCgc0Gyt85Nz0h-TeX0CFvjye_RBS93o3m1Q,49
+iflow_mcp_jamiew_spotify_mcp-0.2.0.dist-info/top_level.txt,sha256=O_lkWQaCucJ2Ue8NZ6Bx_uQp_Hxtw7ME8DVgiE2obWo,12
+iflow_mcp_jamiew_spotify_mcp-0.2.0.dist-info/RECORD,,

iflow_mcp_jamiew_spotify_mcp-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

iflow_mcp_jamiew_spotify_mcp-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+spotify-mcp = spotify_mcp:main

iflow_mcp_jamiew_spotify_mcp-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Varun Neal Srivastava
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

iflow_mcp_jamiew_spotify_mcp-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+spotify_mcp

spotify_mcp/__init__.py

@@ -0,0 +1,23 @@
+import signal
+import sys
+
+from .fastmcp_server import mcp
+
+
+def main() -> None:
+    """Main entry point for the package."""
+    # Handle SIGPIPE gracefully (when client disconnects)
+    signal.signal(signal.SIGPIPE, signal.SIG_DFL)
+
+    try:
+        mcp.run()
+    except BrokenPipeError:
+        # Handle broken pipe gracefully when client disconnects
+        sys.exit(0)
+    except KeyboardInterrupt:
+        # Handle Ctrl+C gracefully
+        sys.exit(0)
+
+
+# Optionally expose other important items at package level
+__all__ = ["main", "mcp"]

spotify_mcp/errors.py

@@ -0,0 +1,276 @@
+"""Custom error handling for Spotify MCP server."""
+
+import json
+from collections.abc import Callable
+from enum import Enum
+from typing import Any
+
+import mcp.types as types
+from spotipy import SpotifyException
+
+
+class SpotifyMCPErrorCode(Enum):
+    """Error codes for Spotify MCP operations."""
+
+    # Authentication errors
+    AUTHENTICATION_FAILED = "authentication_failed"
+    TOKEN_EXPIRED = "token_expired"  # nosec B105 - not a hardcoded password
+    INSUFFICIENT_SCOPE = "insufficient_scope"
+
+    # API errors
+    API_RATE_LIMITED = "api_rate_limited"
+    API_UNAVAILABLE = "api_unavailable"
+    INVALID_REQUEST = "invalid_request"
+
+    # Device errors
+    NO_ACTIVE_DEVICE = "no_active_device"
+    DEVICE_NOT_FOUND = "device_not_found"
+    PREMIUM_REQUIRED = "premium_required"
+
+    # Resource errors
+    TRACK_NOT_FOUND = "track_not_found"
+    PLAYLIST_NOT_FOUND = "playlist_not_found"
+    USER_NOT_FOUND = "user_not_found"
+
+    # Playback errors
+    PLAYBACK_RESTRICTED = "playback_restricted"
+    ALREADY_PLAYING = "already_playing"
+    ALREADY_PAUSED = "already_paused"
+
+    # General errors
+    UNKNOWN_ERROR = "unknown_error"
+    VALIDATION_ERROR = "validation_error"
+
+
+class SpotifyMCPError(Exception):
+    """Custom exception for Spotify MCP operations with MCP-compliant error reporting."""
+
+    def __init__(
+        self,
+        code: SpotifyMCPErrorCode,
+        message: str,
+        details: dict[str, Any] | None = None,
+        suggestion: str | None = None,
+    ):
+        """
+        Initialize a Spotify MCP error.
+
+        Args:
+            code: Error code enum
+            message: Human-readable error message
+            details: Additional error details
+            suggestion: Suggestion for resolving the error
+        """
+        self.code = code
+        self.message = message
+        self.details = details or {}
+        self.suggestion = suggestion
+        super().__init__(message)
+
+    def to_mcp_error(self) -> types.TextContent:
+        """Convert to MCP-compliant error response."""
+        error_response = {
+            "error": {
+                "code": self.code.value,
+                "message": self.message,
+                "details": self.details,
+            }
+        }
+
+        if self.suggestion:
+            error_response["error"]["suggestion"] = self.suggestion
+
+        return types.TextContent(type="text", text=json.dumps(error_response, indent=2))
+
+    @classmethod
+    def from_spotify_exception(cls, exc: SpotifyException) -> "SpotifyMCPError":
+        """Create SpotifyMCPError from spotipy SpotifyException."""
+        status_code = getattr(exc, "http_status", None)
+        error_message = str(exc)
+
+        # Map HTTP status codes to our error codes
+        if status_code == 401:
+            if "token expired" in error_message.lower():
+                return cls(
+                    SpotifyMCPErrorCode.TOKEN_EXPIRED,
+                    "Spotify access token has expired",
+                    {"http_status": status_code},
+                    "Please re-authenticate with Spotify",
+                )
+            else:
+                return cls(
+                    SpotifyMCPErrorCode.AUTHENTICATION_FAILED,
+                    "Authentication with Spotify failed",
+                    {"http_status": status_code},
+                    "Check your Spotify API credentials",
+                )
+
+        elif status_code == 403:
+            if "premium" in error_message.lower():
+                return cls(
+                    SpotifyMCPErrorCode.PREMIUM_REQUIRED,
+                    "Spotify Premium is required for this operation",
+                    {"http_status": status_code},
+                    "Upgrade to Spotify Premium to use playback features",
+                )
+            elif "scope" in error_message.lower():
+                return cls(
+                    SpotifyMCPErrorCode.INSUFFICIENT_SCOPE,
+                    "Insufficient permissions for this operation",
+                    {"http_status": status_code},
+                    "Re-authenticate with required scopes",
+                )
+            else:
+                return cls(
+                    SpotifyMCPErrorCode.PLAYBACK_RESTRICTED,
+                    "Playback is restricted for this content",
+                    {"http_status": status_code},
+                )
+
+        elif status_code == 404:
+            if "track" in error_message.lower():
+                return cls(
+                    SpotifyMCPErrorCode.TRACK_NOT_FOUND,
+                    "The requested track was not found",
+                    {"http_status": status_code},
+                    "Check the track ID and try again",
+                )
+            elif "playlist" in error_message.lower():
+                return cls(
+                    SpotifyMCPErrorCode.PLAYLIST_NOT_FOUND,
+                    "The requested playlist was not found",
+                    {"http_status": status_code},
+                    "Check the playlist ID and try again",
+                )
+            elif "user" in error_message.lower():
+                return cls(
+                    SpotifyMCPErrorCode.USER_NOT_FOUND,
+                    "The requested user was not found",
+                    {"http_status": status_code},
+                )
+
+        elif status_code == 429:
+            return cls(
+                SpotifyMCPErrorCode.API_RATE_LIMITED,
+                "Spotify API rate limit exceeded",
+                {"http_status": status_code},
+                "Wait a moment before making more requests",
+            )
+
+        elif status_code and status_code >= 500:
+            return cls(
+                SpotifyMCPErrorCode.API_UNAVAILABLE,
+                "Spotify API is temporarily unavailable",
+                {"http_status": status_code},
+                "Try again in a few minutes",
+            )
+
+        # Handle specific device-related errors
+        if "no active device" in error_message.lower():
+            return cls(
+                SpotifyMCPErrorCode.NO_ACTIVE_DEVICE,
+                "No active Spotify device found",
+                {"original_error": error_message},
+                "Open Spotify on a device to start playback",
+            )
+
+        if "device not found" in error_message.lower():
+            return cls(
+                SpotifyMCPErrorCode.DEVICE_NOT_FOUND,
+                "The specified device was not found",
+                {"original_error": error_message},
+                "Check available devices and try again",
+            )
+
+        # Default case
+        return cls(
+            SpotifyMCPErrorCode.UNKNOWN_ERROR,
+            f"Spotify API error: {error_message}",
+            {"http_status": status_code, "original_error": error_message},
+        )
+
+    @classmethod
+    def validation_error(cls, field: str, message: str) -> "SpotifyMCPError":
+        """Create a validation error."""
+        return cls(
+            SpotifyMCPErrorCode.VALIDATION_ERROR,
+            f"Validation error for '{field}': {message}",
+            {"field": field},
+            "Check the input parameters and try again",
+        )
+
+    @classmethod
+    def no_active_device(cls) -> "SpotifyMCPError":
+        """Create a no active device error."""
+        return cls(
+            SpotifyMCPErrorCode.NO_ACTIVE_DEVICE,
+            "No active Spotify device found for playback",
+            {},
+            "Open Spotify on a device (phone, computer, etc.) to enable playback control",
+        )
+
+    @classmethod
+    def premium_required(cls, operation: str) -> "SpotifyMCPError":
+        """Create a premium required error."""
+        return cls(
+            SpotifyMCPErrorCode.PREMIUM_REQUIRED,
+            f"Spotify Premium is required for {operation}",
+            {"operation": operation},
+            "Upgrade to Spotify Premium to access this feature",
+        )
+
+
+def convert_spotify_error(e: Exception) -> Exception:
+    """Convert Spotify exceptions to appropriate exception types for FastMCP."""
+    if isinstance(e, SpotifyException):
+        error = SpotifyMCPError.from_spotify_exception(e)
+        # For FastMCP, we'll raise a ValueError with the error message
+        return ValueError(error.message)
+    elif isinstance(e, SpotifyMCPError):
+        return ValueError(e.message)
+    else:
+        return ValueError(f"Unexpected error: {str(e)}")
+
+
+def handle_spotify_error(func: Callable[..., Any]) -> Callable[..., Any]:
+    """Decorator to handle Spotify API errors and convert them to MCP-compliant responses."""
+
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return func(*args, **kwargs)
+        except SpotifyException as e:
+            error = SpotifyMCPError.from_spotify_exception(e)
+            return [error.to_mcp_error()]
+        except SpotifyMCPError as e:
+            return [e.to_mcp_error()]
+        except Exception as e:
+            error = SpotifyMCPError(
+                SpotifyMCPErrorCode.UNKNOWN_ERROR,
+                f"Unexpected error: {str(e)}",
+                {"error_type": type(e).__name__},
+            )
+            return [error.to_mcp_error()]
+
+    return wrapper
+
+
+async def handle_spotify_error_async(func: Callable[..., Any]) -> Callable[..., Any]:
+    """Async decorator to handle Spotify API errors and convert them to MCP-compliant responses."""
+
+    async def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return await func(*args, **kwargs)
+        except SpotifyException as e:
+            error = SpotifyMCPError.from_spotify_exception(e)
+            return [error.to_mcp_error()]
+        except SpotifyMCPError as e:
+            return [e.to_mcp_error()]
+        except Exception as e:
+            error = SpotifyMCPError(
+                SpotifyMCPErrorCode.UNKNOWN_ERROR,
+                f"Unexpected error: {str(e)}",
+                {"error_type": type(e).__name__},
+            )
+            return [error.to_mcp_error()]
+
+    return wrapper