@darrenjaws/spotify-mcp 0.4.0 → 0.6.0

package/README.md

@@ -1,5 +1,6 @@
 # Spotify MCP Server
 
+[![Static Checks](https://github.com/darrenjaworski/spotify-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/darrenjaworski/spotify-mcp/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/@darrenjaws/spotify-mcp)](https://www.npmjs.com/package/@darrenjaws/spotify-mcp)
 [![npm downloads](https://img.shields.io/npm/dm/@darrenjaws/spotify-mcp)](https://www.npmjs.com/package/@darrenjaws/spotify-mcp)
 [![license](https://img.shields.io/npm/l/@darrenjaws/spotify-mcp)](https://github.com/darrenjaworski/spotify-mcp/blob/main/LICENSE)
@@ -17,7 +18,6 @@ A Model Context Protocol (MCP) server that provides seamless integration with Sp
 - [Configuration](#configuration)
   - [Automated Setup](#automated-setup-recommended)
   - [Manual Setup](#manual-setup)
-  - [Spotify App Setup](#spotify-app-setup)
   - [Environment Variables](#environment-variables)
   - [MCP Configuration](#mcp-configuration)
 - [Usage](#usage)
@@ -162,12 +162,13 @@ SPOTIFY_REDIRECT_URI=http://127.0.0.1:3000/callback
 
 ### MCP Configuration
 
+#### Claude Desktop
+
 Add to your Claude Desktop config file:
 
-**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
 
-**Using npx (recommended):**
 ```json
 {
   "mcpServers": {
@@ -184,61 +185,22 @@ Add to your Claude Desktop config file:
 }
 ```
 
-**Using global installation:**
-```json
-{
-  "mcpServers": {
-    "spotify": {
-      "command": "spotify-mcp",
-      "env": {
-        "SPOTIFY_CLIENT_ID": "your_client_id_here",
-        "SPOTIFY_CLIENT_SECRET": "your_client_secret_here",
-        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:3000/callback"
-      }
-    }
-  }
-}
-```
-
-**From source (development):**
-```json
-{
-  "mcpServers": {
-    "spotify": {
-      "command": "node",
-      "args": ["/absolute/path/to/spotify-mcp/build/bin.js"],
-      "env": {
-        "SPOTIFY_CLIENT_ID": "your_client_id_here",
-        "SPOTIFY_CLIENT_SECRET": "your_client_secret_here",
-        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:3000/callback"
-      }
-    }
-  }
-}
-```
-
-**Note**: When using npx or global install, environment variables must be specified in the MCP config (not in a `.env` file).
-
-### Claude Code (Terminal) Configuration
+Restart Claude Desktop after saving.
 
-If you're using [Claude Code](https://claude.com/code) (the terminal CLI), you can add this MCP server to your project or global configuration.
+#### Claude Code (CLI)
 
-#### Option 1: Using Claude Code's MCP Command (Recommended)
+The easiest way is the `claude mcp add` command:
 
 ```bash
-# Add the server interactively
-claude mcp add
-
-# Follow the prompts:
-# - Server name: spotify
-# - Command: npx
-# - Args: -y @darrenjaws/spotify-mcp
-# - Add environment variables when prompted
+claude mcp add spotify \
+  -e SPOTIFY_CLIENT_ID=your_client_id_here \
+  -e SPOTIFY_CLIENT_SECRET=your_client_secret_here \
+  -e SPOTIFY_REDIRECT_URI=http://127.0.0.1:3000/callback \
+  -- npx -y @darrenjaws/spotify-mcp
 ```
 
-#### Option 2: Manual Configuration
+Or add it manually to `~/.claude.json` (global) or `.claude/settings.json` (project):
 
-**Global config** (`~/.claude/config.json`):
 ```json
 {
   "mcpServers": {
@@ -255,13 +217,16 @@ claude mcp add
 }
 ```
 
-**Project-specific config** (`.claude/config.json` in your project):
+Verify with `claude mcp list` — you should see `spotify` in the list.
+
+#### From Source (Development)
+
 ```json
 {
   "mcpServers": {
     "spotify": {
-      "command": "npx",
-      "args": ["-y", "@darrenjaws/spotify-mcp"],
+      "command": "node",
+      "args": ["/absolute/path/to/spotify-mcp/build/bin.js"],
       "env": {
         "SPOTIFY_CLIENT_ID": "your_client_id_here",
         "SPOTIFY_CLIENT_SECRET": "your_client_secret_here",
@@ -272,38 +237,7 @@ claude mcp add
 }
 ```
 
-#### Migrating from Claude Desktop to Claude Code
-
-If you already have this configured in Claude Desktop, you can copy your configuration:
-
-**1. View your Claude Desktop config:**
-```bash
-# macOS
-cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
-
-# Windows (PowerShell)
-Get-Content $env:APPDATA\Claude\claude_desktop_config.json
-```
-
-**2. Copy the `spotify` server config to Claude Code:**
-```bash
-# Create Claude Code config directory if it doesn't exist
-mkdir -p ~/.claude
-
-# Edit your Claude Code config
-nano ~/.claude/config.json
-# or
-code ~/.claude/config.json
-```
-
-**3. Paste the same `mcpServers` configuration** - the format is identical!
-
-**4. Verify it works:**
-```bash
-claude mcp list
-```
-
-You should see `spotify` in the list of available MCP servers.
+**Note**: When using npx or global install, environment variables must be specified in the MCP config (not in a `.env` file).
 
 ## Usage
 
@@ -514,21 +448,22 @@ Run the test suite to verify tool registration and functionality:
 ```bash
 npm test              # Run all tests
 npm run test:watch    # Run tests in watch mode
-npm run test:coverage # Generate coverage report
 ```
 
 **Test Coverage:**
-- ✅ 30 tests covering tool registration
-- ✅ Validates all 15 tools are registered correctly
-- ✅ Verifies tool naming conventions
-- ✅ Checks input schema validation with Zod
-- ✅ Integration tests for MCP server setup
+- ✅ 160 tests across 10 test files
+- ✅ Tool-level unit tests for playback, search, playlists, user, and system
+- ✅ Auth tests (credentials, token management, file permissions, refresh)
+- ✅ Logger tests (sensitive data redaction, log levels)
+- ✅ Error handling tests (all HTTP status codes, security)
+- ✅ Server registration and integration tests
 
 ### Linting and Code Quality
 
 ```bash
-npm run lint        # Check code style
-npm run lint:fix    # Auto-fix linting issues
+npm run lint           # Check code style
+npm run lint:fix       # Auto-fix linting issues
+npm run static-checks  # Run lint, build, and test together
 ```
 
 ### Troubleshooting

package/build/index.js

@@ -64,6 +64,10 @@ server.registerTool("spotify_get_playback_state", {
     description: "Get current playback state including track, artist, album, and playback status",
     inputSchema: {},
 }, async () => playbackTools.getPlaybackState());
+server.registerTool("spotify_get_devices", {
+    description: "List available Spotify Connect devices",
+    inputSchema: {},
+}, async () => playbackTools.getDevices());
 // Register search tool
 server.registerTool("spotify_search", {
     description: "Search for tracks, albums, artists, or playlists",

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/build/spotify/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Centralized error handling for tool implementations.
+ * Transforms raw Spotify API errors into safe, user-friendly responses.
+ */
+import type { ToolResponse } from "../types.js";
+/**
+ * Handle errors from tool functions.
+ * Logs the real error (with auto-redaction) and returns a safe ToolResponse.
+ */
+export declare function handleToolError(error: unknown, toolName: string): ToolResponse;
+//# sourceMappingURL=errors.d.ts.map

package/build/spotify/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/spotify/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAyChD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,CAe9E"}

package/build/spotify/errors.js

@@ -0,0 +1,61 @@
+/**
+ * Centralized error handling for tool implementations.
+ * Transforms raw Spotify API errors into safe, user-friendly responses.
+ */
+import { logger } from "../utils/logger.js";
+/**
+ * Extract HTTP status code from various error shapes.
+ * spotify-web-api-node can throw errors with .statusCode or .body.error.status
+ */
+function getStatusCode(error) {
+    if (typeof error?.statusCode === "number") {
+        return error.statusCode;
+    }
+    if (typeof error?.body?.error?.status === "number") {
+        return error.body.error.status;
+    }
+    return 0;
+}
+/**
+ * Map HTTP status codes to safe, user-friendly messages.
+ */
+function getUserMessage(statusCode, toolName) {
+    if (statusCode === 400) {
+        return "Bad request. Please check your input and try again.";
+    }
+    if (statusCode === 401) {
+        return "Authentication expired. Please restart the server to re-authenticate.";
+    }
+    if (statusCode === 403) {
+        return "Insufficient permissions. Your Spotify account may not have access to this feature.";
+    }
+    if (statusCode === 404) {
+        return "Resource not found. Please check the ID or URI and try again.";
+    }
+    if (statusCode === 429) {
+        return "Rate limited by Spotify. Please wait a moment and try again.";
+    }
+    if (statusCode >= 500 && statusCode < 600) {
+        return "Spotify is experiencing issues. Please try again in a moment.";
+    }
+    return `An unexpected error occurred while executing ${toolName}.`;
+}
+/**
+ * Handle errors from tool functions.
+ * Logs the real error (with auto-redaction) and returns a safe ToolResponse.
+ */
+export function handleToolError(error, toolName) {
+    logger.error(`${toolName} failed:`, error);
+    const statusCode = getStatusCode(error);
+    const message = getUserMessage(statusCode, toolName);
+    return {
+        content: [
+            {
+                type: "text",
+                text: message,
+            },
+        ],
+        isError: true,
+    };
+}
+//# sourceMappingURL=errors.js.map

package/build/spotify/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/spotify/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAG5C;;;GAGG;AACH,SAAS,aAAa,CAAC,KAAU;IAC/B,IAAI,OAAO,KAAK,EAAE,UAAU,KAAK,QAAQ,EAAE,CAAC;QAC1C,OAAO,KAAK,CAAC,UAAU,CAAC;IAC1B,CAAC;IACD,IAAI,OAAO,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,KAAK,QAAQ,EAAE,CAAC;QACnD,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IACjC,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;GAEG;AACH,SAAS,cAAc,CAAC,UAAkB,EAAE,QAAgB;IAC1D,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;QACvB,OAAO,qDAAqD,CAAC;IAC/D,CAAC;IACD,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;QACvB,OAAO,uEAAuE,CAAC;IACjF,CAAC;IACD,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;QACvB,OAAO,qFAAqF,CAAC;IAC/F,CAAC;IACD,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;QACvB,OAAO,+DAA+D,CAAC;IACzE,CAAC;IACD,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;QACvB,OAAO,8DAA8D,CAAC;IACxE,CAAC;IACD,IAAI,UAAU,IAAI,GAAG,IAAI,UAAU,GAAG,GAAG,EAAE,CAAC;QAC1C,OAAO,+DAA+D,CAAC;IACzE,CAAC;IACD,OAAO,gDAAgD,QAAQ,GAAG,CAAC;AACrE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc,EAAE,QAAgB;IAC9D,MAAM,CAAC,KAAK,CAAC,GAAG,QAAQ,UAAU,EAAE,KAAK,CAAC,CAAC;IAE3C,MAAM,UAAU,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IACxC,MAAM,OAAO,GAAG,cAAc,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IAErD,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,OAAO;aACd;SACF;QACD,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC"}

package/build/tools/playback.d.ts

@@ -14,4 +14,5 @@ export declare function previous(args: {
 }): Promise<ToolResponse>;
 export declare function setVolume(args: VolumeArgs): Promise<ToolResponse>;
 export declare function getPlaybackState(): Promise<ToolResponse>;
+export declare function getDevices(): Promise<ToolResponse>;
 //# sourceMappingURL=playback.d.ts.map

package/build/tools/playback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"playback.d.ts","sourceRoot":"","sources":["../../src/tools/playback.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE1E,wBAAsB,IAAI,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAmDpE;AAED,wBAAsB,KAAK,CAAC,IAAI,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAkB/E;AAED,wBAAsB,IAAI,CAAC,IAAI,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAkB9E;AAED,wBAAsB,QAAQ,CAAC,IAAI,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAkBlF;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC,CAkBvE;AAED,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,YAAY,CAAC,CAoD9D"}
+{"version":3,"file":"playback.d.ts","sourceRoot":"","sources":["../../src/tools/playback.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAiC1E,wBAAsB,IAAI,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CA0DpE;AAED,wBAAsB,KAAK,CAAC,IAAI,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAyB/E;AAED,wBAAsB,IAAI,CAAC,IAAI,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAyB9E;AAED,wBAAsB,QAAQ,CAAC,IAAI,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAyBlF;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC,CAyBvE;AAED,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,YAAY,CAAC,CA6D9D;AAED,wBAAsB,UAAU,IAAI,OAAO,CAAC,YAAY,CAAC,CAsCxD"}