getUsersSavedTracks

Instructions

Implementation Reference

• src/read.ts:389-434 (handler)

  The core handler function that executes the tool logic: fetches user's saved tracks ("Liked Songs") via Spotify API with pagination (limit/offset), handles empty results, formats track details (name, artists, duration, ID, added date) using helpers like isTrack and formatDuration, and returns a formatted text response.

  handler: async (args, _extra: SpotifyHandlerExtra) => {
    const { limit = 50, offset = 0 } = args;
  
    const savedTracks = await handleSpotifyRequest(async (spotifyApi) => {
      return await spotifyApi.currentUser.tracks.savedTracks(
        limit as MaxInt<50>,
        offset,
      );
    });
  
    if (savedTracks.items.length === 0) {
      return {
        content: [
          {
            type: 'text',
            text: "You don't have any saved tracks in your Liked Songs",
          },
        ],
      };
    }
  
    const formattedTracks = savedTracks.items
      .map((item, i) => {
        const track = item.track;
        if (!track) return `${i + 1}. [Removed track]`;
  
        if (isTrack(track)) {
          const artists = track.artists.map((a) => a.name).join(', ');
          const duration = formatDuration(track.duration_ms);
          const addedDate = new Date(item.added_at).toLocaleDateString();
          return `${offset + i + 1}. "${track.name}" by ${artists} (${duration}) - ID: ${track.id} - Added: ${addedDate}`;
        }
  
        return `${i + 1}. Unknown item`;
      })
      .join('\n');
  
    return {
      content: [
        {
          type: 'text',
          text: `# Your Liked Songs (${offset + 1}-${offset + savedTracks.items.length} of ${savedTracks.total})\n\n${formattedTracks}`,
        },
      ],
    };
  },

• src/read.ts:373-388 (schema)

  Input schema definition using Zod for validation: optional limit (1-50) and offset (>=0). Includes tool name and description.

  name: 'getUsersSavedTracks',
  description:
    'Get a list of tracks saved in the user\'s "Liked Songs" library',
  schema: {
    limit: z
      .number()
      .min(1)
      .max(50)
      .optional()
      .describe('Maximum number of tracks to return (1-50)'),
    offset: z
      .number()
      .min(0)
      .optional()
      .describe('Offset for pagination (0-based index)'),
  },

• src/read.ts:531-539 (registration)

  Local registration: getUsersSavedTracks is added to the readTools array alongside other read-related tools for collective export.

  export const readTools = [
    searchSpotify,
    getNowPlaying,
    getMyPlaylists,
    getPlaylistTracks,
    getRecentlyPlayed,
    getUsersSavedTracks,
    getQueue,
  ];

• src/index.ts:12-14 (registration)

  Global registration: All tools from readTools (including getUsersSavedTracks) are looped over and registered with the MCP server using server.tool().

  [...readTools, ...playTools, ...albumTools].forEach((tool) => {
    server.tool(tool.name, tool.description, tool.schema, tool.handler);
  });

• src/read.ts:6-13 (helper)

  Supporting helper function used in the handler to type-guard and validate Spotify track items before formatting.

  function isTrack(item: any): item is SpotifyTrack {
    return (
      item &&
      item.type === 'track' &&
      Array.isArray(item.artists) &&
      item.album &&
      typeof item.album.name === 'string'
    );