Spotify MCP Server

Instructions

Implementation Reference

• src/read.ts:307-367 (handler)

  Full implementation of the getRecentlyPlayed tool handler, which fetches recently played tracks using Spotify API, filters and formats them for display.

  const getRecentlyPlayed: tool<{
    limit: z.ZodOptional<z.ZodNumber>;
  }> = {
    name: 'getRecentlyPlayed',
    description: 'Get a list of recently played tracks on Spotify',
    schema: {
      limit: z
        .number()
        .min(1)
        .max(50)
        .optional()
        .describe('Maximum number of tracks to return (1-50)'),
    },
    handler: async (args, _extra: SpotifyHandlerExtra) => {
      const { limit = 50 } = args;
  
      const history = await handleSpotifyRequest(async (spotifyApi) => {
        return await spotifyApi.player.getRecentlyPlayedTracks(
          limit as MaxInt<50>,
        );
      });
  
      if (history.items.length === 0) {
        return {
          content: [
            {
              type: 'text',
              text: "You don't have any recently played tracks on Spotify",
            },
          ],
        };
      }
  
      const formattedHistory = history.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 playedAt = item.played_at
              ? new Date(item.played_at).toLocaleString()
              : 'Unknown time';
            return `${i + 1}. "${track.name}" by ${artists} (${duration}) - ID: ${track.id} - Played at: ${playedAt}`;
          }
  
          return `${i + 1}. Unknown item`;
        })
        .join('\n');
  
      return {
        content: [
          {
            type: 'text',
            text: `# Recently Played Tracks\n\n${formattedHistory}`,
          },
        ],
      };
    },
  };

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

  Registration of the getRecentlyPlayed tool in the readTools export array.

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

• src/read.ts:312-319 (schema)

  Zod schema definition for the tool's input parameter 'limit'.

  schema: {
    limit: z
      .number()
      .min(1)
      .max(50)
      .optional()
      .describe('Maximum number of tracks to return (1-50)'),
  },

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

  Helper function used in the handler to validate if an item is a SpotifyTrack.

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