Spotify MCP Server

Instructions

Implementation Reference

• src/spotify.ts:442-448 (handler)

  Core implementation of the saveTracks function in SpotifyService. Extracts track IDs, formats them, and makes a PUT request to Spotify API endpoint /me/tracks to save tracks to user's library.

  async saveTracks(token: string, trackIds: string | string[]): Promise<void> {
    const ids = Array.isArray(trackIds)
      ? trackIds.map((id) => this.extractId(id))
      : [this.extractId(trackIds)];
    const params = { ids: ids.join(",") };
    return await this.makeRequest<void>("me/tracks", token, params, "PUT");
  }

• src/mcp/tools/tracks.ts:204-207 (handler)

  The MCP tool handler for 'save_tracks' that validates arguments and delegates execution to the SpotifyService.saveTracks method.

  handler: async (args: any, spotifyService: SpotifyService) => {
    const { token, trackIds } = args;
    return await spotifyService.saveTracks(token, trackIds);
  },

• src/mcp/tools/tracks.ts:198-203 (schema)

  Zod-based input schema definition for the 'save_tracks' tool, requiring a Spotify token and an array of track IDs.

  schema: createSchema({
    token: commonSchemas.token(),
    trackIds: z
      .array(z.string())
      .describe("Array of Spotify track IDs to save"),
  }),

• src/mcp/tools/tracks.ts:156-208 (registration)

  Complete registration of the 'save_tracks' tool as part of the trackTools object, including title, detailed description, schema, and handler reference.

    save_tracks: {
      title: "Save Tracks to Library",
      description: `Add tracks to the user's personal library, creating a permanent collection of favorite music.
  
  🎯 USE CASES:
  • Save discovered tracks for future listening
  • Build personal music library from recommendations
  • Like tracks during music discovery sessions
  • Create permanent collections of favorite songs
  • Save music for offline listening and easy access
  
  📝 WHAT IT RETURNS:
  • Confirmation of successful track saves
  • Updated library count and collection size
  • Timestamp information for when tracks were saved
  • Error details for tracks that couldn't be saved
  • Success status for bulk save operations
  
  🔍 EXAMPLES:
  • "Save 'Bohemian Rhapsody' to my library"
  • "Add these 5 discovered tracks to my liked songs"
  • "Save track IDs: 4uLU6hMCjMI75M1A2tKUQC, 7qiZfU4dY1lWllzX7mkmht"
  • "Like all tracks from this great album"
  
  💖 BUILDING YOUR COLLECTION:
  • Creates permanent access to favorite music
  • Tracks appear in your "Liked Songs" playlist
  • Enables offline playback for saved content
  • Perfect for building personalized music libraries
  • Essential for music discovery and curation
  
  💡 COLLECTION STRATEGIES:
  • Save tracks immediately during discovery
  • Build thematic collections of related music
  • Use bulk saves for efficiency with multiple tracks
  • Regular saving helps track music evolution
  • Create personal "greatest hits" collections
  
  ⚠️ REQUIREMENTS:
  • Valid Spotify access token with user-library-modify scope
  • Tracks must be available in user's market
  • Maximum 50 tracks can be saved per request`,
      schema: createSchema({
        token: commonSchemas.token(),
        trackIds: z
          .array(z.string())
          .describe("Array of Spotify track IDs to save"),
      }),
      handler: async (args: any, spotifyService: SpotifyService) => {
        const { token, trackIds } = args;
        return await spotifyService.saveTracks(token, trackIds);
      },
    },

• src/mcp/tools/index.ts:27-27 (registration)

  Registration of trackTools (including save_tracks) into the central allTools registry used by ToolRegistrar for MCP tool definitions.

  ...trackTools,