MCP Spotify Server

Instructions

Implementation Reference

• src/handlers/albums.ts:65-91 (handler)

  Implements the core logic for fetching new album releases from Spotify's /browse/new-releases endpoint, including parameter validation and API request.

  async getNewReleases(args: NewReleasesArgs) {
    const { country, limit = 20, offset = 0 } = args;
  
    if (limit < 1 || limit > 50) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Limit must be between 1 and 50'
      );
    }
  
    if (offset < 0) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Offset must be non-negative'
      );
    }
  
    const params = {
      country,
      limit,
      offset
    };
  
    return this.api.makeRequest(
      `/browse/new-releases${this.api.buildQueryString(params)}`
    );
  }

• src/types/albums.ts:13-15 (schema)

  TypeScript interface defining the input arguments for the getNewReleases tool, extending PaginationParams with optional country.

  export interface NewReleasesArgs extends PaginationParams {
    country?: string;
  }

• src/index.ts:319-343 (registration)

  Registers the get_new_releases tool in the MCP server's listTools response, including name, description, and input schema.

    name: 'get_new_releases',
    description: 'Get a list of new album releases featured in Spotify',
    inputSchema: {
      type: 'object',
      properties: {
        country: {
          type: 'string',
          description: 'Optional. A country code (ISO 3166-1 alpha-2)'
        },
        limit: {
          type: 'number',
          description: 'Maximum number of releases to return (1-50)',
          minimum: 1,
          maximum: 50,
          default: 20
        },
        offset: {
          type: 'number',
          description: 'The index of the first release to return',
          minimum: 0,
          default: 0
        }
      }
    },
  },

• src/index.ts:789-795 (registration)

  Dispatches calls to the get_new_releases tool by invoking the AlbumsHandler's getNewReleases method with validated arguments.

  case 'get_new_releases': {
    const args = this.validateArgs<NewReleasesArgs>(request.params.arguments || {}, []);
    const result = await this.albumsHandler.getNewReleases(args);
    return {
      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
    };
  }