MCP Spotify Server

Instructions

Implementation Reference

• src/handlers/playlists.ts:38-52 (handler)

  The core handler function implementing the get_playlist_items tool. It extracts the playlist ID, builds query parameters (market, limit, offset, fields), and makes a GET request to Spotify's /playlists/{id}/items endpoint via the SpotifyApi utility.

  async getPlaylistItems(args: PlaylistItemsArgs) {
    const playlistId = this.extractPlaylistId(args.id);
    const { market, limit, offset, fields } = args;
  
    const params = {
      market,
      ...(limit !== undefined && { limit }),
      ...(offset !== undefined && { offset }),
      ...(fields !== undefined && { fields })
    };
  
    return this.api.makeRequest(
      `/playlists/${playlistId}/items${this.api.buildQueryString(params)}`
    );
  }

• src/types/playlists.ts:12-15 (schema)

  TypeScript interface defining the input arguments for the getPlaylistItems handler: playlist ID (required), fields (optional), extending MarketParams (market) and PaginationParams (limit, offset). Used for type safety and validation.

  export interface PlaylistItemsArgs extends MarketParams, PaginationParams {
    id: string;
    fields?: string;
  }

• src/index.ts:495-526 (registration)

  MCP tool registration in listTools response: defines name, description, and inputSchema matching the handler arguments.

    name: 'get_playlist_items',
    description: 'Get full details of the items of a playlist',
    inputSchema: {
      type: 'object',
      properties: {
        id: {
          type: 'string',
          description: 'The Spotify ID or URI of the playlist'
        },
        market: {
          type: 'string',
          description: 'Optional. An ISO 3166-1 alpha-2 country code'
        },
        fields: {
          type: 'string',
          description: 'Optional. Filters for the query'
        },
        limit: {
          type: 'number',
          description: 'Optional. Maximum number of items to return (1-100)',
          minimum: 1,
          maximum: 100
        },
        offset: {
          type: 'number',
          description: 'Optional. Index of the first item to return',
          minimum: 0
        }
      },
      required: ['id']
    },
  },

• src/index.ts:845-851 (registration)

  Dispatch handler in the main CallToolRequest switch statement: validates arguments, calls the playlistsHandler.getPlaylistItems, and returns JSON stringified result.

  case 'get_playlist_items': {
    const args = this.validateArgs<PlaylistItemsArgs>(request.params.arguments, ['id']);
    const result = await this.playlistsHandler.getPlaylistItems(args);
    return {
      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
    };
  }

• src/handlers/playlists.ts:8-10 (helper)

  Helper method used by getPlaylistItems (and other playlist methods) to normalize playlist ID from Spotify URI or plain ID.

  private extractPlaylistId(id: string): string {
    return id.startsWith('spotify:playlist:') ? id.split(':')[2] : id;
  }