get-top-tracks
Retrieve a user's top Spotify tracks over a specified time range. Customize results by adjusting the number of tracks, offset, and time frame (short, medium, or long term) using this integrated tool.
Instructions
Get the user's top played tracks over a specified time range
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | The number of tracks to return (1-50, default: 20) | |
| offset | No | The index of the first track to return (default: 0) | |
| time_range | No | Over what time frame the affinities are computed. short_term = ~4 weeks, medium_term = ~6 months, long_term = several years (default: medium_term) |
Implementation Reference
- index.ts:1350-1387 (handler)Handler function for the 'get-top-tracks' tool. Parses input using GetTopTracksSchema, calls Spotify API /me/top/tracks endpoint with parameters, formats the top tracks response with details like name, artist, album, ID, duration, URL.
if (name === "get-top-tracks") { const { limit, offset, time_range } = GetTopTracksSchema.parse(args); const params = new URLSearchParams(); params.append("limit", limit.toString()); params.append("offset", offset.toString()); params.append("time_range", time_range); const topTracks = await spotifyApiRequest(`/me/top/tracks?${params}`); const formattedTracks = topTracks.items .map( (track: any) => ` Track: ${track.name} Artist: ${track.artists.map((a: any) => a.name).join(", ")} Album: ${track.album.name} ID: ${track.id} Duration: ${Math.floor(track.duration_ms / 1000 / 60)}:${( Math.floor(track.duration_ms / 1000) % 60 ) .toString() .padStart(2, "0")} URL: ${track.external_urls.spotify} ---` ) .join("\n"); return { content: [ { type: "text", text: topTracks.items.length > 0 ? `Your top tracks:\n${formattedTracks}` : "No top tracks found for the specified time range.", }, ], }; } - index.ts:200-204 (schema)Zod schema for validating input parameters to the get-top-tracks tool: limit (1-50), offset (>=0), time_range (short_term|medium_term|long_term).
const GetTopTracksSchema = z.object({ limit: z.number().min(1).max(50).default(20), offset: z.number().min(0).default(0), time_range: z.enum(["short_term", "medium_term", "long_term"]).default("medium_term"), }); - index.ts:806-827 (registration)Tool registration in ListToolsRequestHandler, including name, description, and inputSchema matching the Zod schema.
{ name: "get-top-tracks", description: "Get the user's top played tracks over a specified time range", inputSchema: { type: "object", properties: { limit: { type: "number", description: "The number of tracks to return (1-50, default: 20)", }, offset: { type: "number", description: "The index of the first track to return (default: 0)", }, time_range: { type: "string", enum: ["short_term", "medium_term", "long_term"], description: "Over what time frame the affinities are computed. short_term = ~4 weeks, medium_term = ~6 months, long_term = several years (default: medium_term)", } } } },