Spotify MCP Server

Instructions

Implementation Reference

• src/albums.ts:17-96 (handler)

  The handler function for the 'getAlbums' tool. It validates input, fetches album data from Spotify API using handleSpotifyRequest, formats the response as markdown text for single or multiple albums, and handles errors.

  handler: async (args, _extra: SpotifyHandlerExtra) => {
    const { albumIds } = args;
    const ids = Array.isArray(albumIds) ? albumIds : [albumIds];
  
    if (ids.length === 0) {
      return {
        content: [
          {
            type: 'text',
            text: 'Error: No album IDs provided',
          },
        ],
      };
    }
  
    try {
      const albums = await handleSpotifyRequest(async (spotifyApi) => {
        return ids.length === 1
          ? [await spotifyApi.albums.get(ids[0])]
          : await spotifyApi.albums.get(ids);
      });
  
      if (albums.length === 0) {
        return {
          content: [
            {
              type: 'text',
              text: 'No albums found for the provided IDs',
            },
          ],
        };
      }
  
      if (albums.length === 1) {
        const album = albums[0];
        const artists = album.artists.map((a) => a.name).join(', ');
        const releaseDate = album.release_date;
        const totalTracks = album.total_tracks;
        const albumType = album.album_type;
  
        return {
          content: [
            {
              type: 'text',
              text: `# Album Details\n\n**Name**: "${album.name}"\n**Artists**: ${artists}\n**Release Date**: ${releaseDate}\n**Type**: ${albumType}\n**Total Tracks**: ${totalTracks}\n**ID**: ${album.id}`,
            },
          ],
        };
      }
  
      const formattedAlbums = albums
        .map((album, i) => {
          if (!album) return `${i + 1}. [Album not found]`;
  
          const artists = album.artists.map((a) => a.name).join(', ');
          return `${i + 1}. "${album.name}" by ${artists} (${album.release_date}) - ${album.total_tracks} tracks - ID: ${album.id}`;
        })
        .join('\n');
  
      return {
        content: [
          {
            type: 'text',
            text: `# Multiple Albums\n\n${formattedAlbums}`,
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error getting albums: ${
              error instanceof Error ? error.message : String(error)
            }`,
          },
        ],
      };
    }
  },

• src/albums.ts:12-16 (schema)

  Zod schema for 'getAlbums' tool input, accepting a single string or array of up to 20 album IDs.

  schema: {
    albumIds: z
      .union([z.string(), z.array(z.string()).max(20)])
      .describe('A single album ID or array of album IDs (max 20)'),
  },

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

  Registration loop that registers all tools, including getAlbums from albumTools, with the MCP server using server.tool().

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

• src/albums.ts:299-304 (registration)

  Export of albumTools array containing the getAlbums tool for use in index.ts registration.

  export const albumTools = [
    getAlbums,
    getAlbumTracks,
    saveOrRemoveAlbumForUser,
    checkUsersSavedAlbums,
  ];

• src/utils.ts:282-301 (helper)

  Utility function handleSpotifyRequest used in getAlbums handler to create SpotifyApi instance and execute API calls safely, handling certain errors.

  export async function handleSpotifyRequest<T>(
    action: (spotifyApi: SpotifyApi) => Promise<T>,
  ): Promise<T> {
    try {
      const spotifyApi = createSpotifyApi();
      return await action(spotifyApi);
    } catch (error) {
      // Skip JSON parsing errors as these are actually successful operations
      const errorMessage = error instanceof Error ? error.message : String(error);
      if (
        errorMessage.includes('Unexpected token') ||
        errorMessage.includes('Unexpected non-whitespace character') ||
        errorMessage.includes('Exponent part is missing a number in JSON')
      ) {
        return undefined as T;
      }
      // Rethrow other errors
      throw error;
    }
  }