getUserTopItems
Retrieve a user's top artists or tracks from Spotify based on specified time ranges and quantity limits.
Instructions
Get a list of the user's top artists or tracks
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | The type of items to get top for. Must be "artists" or "tracks" | |
| time_range | Yes | The time range for the top items. Must be "short_term", "medium_term", or "long_term" | |
| limit | No | Maximum number of items to return (1-50) | |
| offset | No | The index of the first item to return. Defaults to 0 |
Implementation Reference
- src/read.ts:468-517 (handler)The handler function for the 'getUserTopItems' tool. It takes parameters type ('artists' or 'tracks'), time_range ('short_term', 'medium_term', 'long_term'), limit, and offset. It calls the Spotify API's currentUser.topItems method and formats the top items into a numbered list with names, artists (for tracks), and IDs.handler: async (args, extra: SpotifyHandlerExtra) => { const { type, time_range, limit = 50, offset = 0 } = args; const topItems = await handleSpotifyRequest(async (spotifyApi) => { return await spotifyApi.currentUser.topItems( type as 'artists' | 'tracks', time_range as 'short_term' | 'medium_term' | 'long_term', limit as MaxInt<50>, offset, ); }); if (topItems.items.length === 0) { return { content: [ { type: 'text', text: `User doesn't have any top ${type} on Spotify`, }, ], }; } const formattedItems = topItems.items .map((item, i) => { if (type === 'artists') { return `${i + 1}. "${item.name}" - ID: ${item.id}`; } else if ( type === 'tracks' && 'artists' in item && Array.isArray(item.artists) ) { const artists = item.artists.map((a) => a.name).join(', '); return `${i + 1}. "${item.name}" by ${artists} - ID: ${item.id}`; } else { // fallback for type safety return `${i + 1}. "${item.name}" - ID: ${item.id}`; } }) .join('\n'); return { content: [ { type: 'text', text: `# Top ${type}\n\n${formattedItems}`, }, ], }; },
- src/read.ts:446-467 (schema)The input schema for the 'getUserTopItems' tool using Zod validators for type, time_range, limit, and offset parameters.schema: { type: z .string() .describe( 'The type of items to get top for. Must be "artists" or "tracks"', ), time_range: z .string() .describe( 'The time range for the top items. Must be "short_term", "medium_term", or "long_term"', ), limit: z .number() .min(1) .max(50) .optional() .describe('Maximum number of items to return (1-50)'), offset: z .number() .optional() .describe('The index of the first item to return. Defaults to 0'), },
- src/read.ts:521-529 (registration)The 'getUserTopItems' tool is included in the exported readTools array, which collects read-related tools.export const readTools = [ searchSpotify, getNowPlaying, getUserPlaylists, getPlaylistTracks, getRecentlyPlayed, getFollowedArtists, getUserTopItems, ];
- src/index.ts:12-14 (registration)All tools from playTools, readTools (including getUserTopItems), and writeTools are registered to the MCP server using server.tool() in a forEach loop.[...playTools, ...readTools, ...writeTools].forEach((tool) => { server.tool(tool.name, tool.description, tool.schema, tool.handler); });