search
Find tracks, albums, artists, or playlists in Spotify's music catalog using specific search queries and filters.
Instructions
Search for tracks, albums, artists, or playlists
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query | |
| type | Yes | Type of item to search for | |
| limit | No | Maximum number of results (1-50) |
Implementation Reference
- src/handlers/search.ts:5-26 (handler)The SearchHandler class provides the core implementation of the 'search' tool, handling input validation and making an API request to Spotify's search endpoint.
export class SearchHandler { constructor(private api: SpotifyApi) {} async search(args: SearchArgs) { const { query, type, limit = 20 } = args; if (limit < 1 || limit > 50) { throw new McpError( ErrorCode.InvalidParams, 'Limit must be between 1 and 50' ); } const params = { q: encodeURIComponent(query), type, limit }; return this.api.makeRequest(`/search${this.api.buildQueryString(params)}`); } } - src/types/search.ts:1-40 (schema)TypeScript interfaces defining the input (SearchArgs) and output (SearchResponse) structures for the 'search' tool.
export interface SearchArgs { query: string; type: 'track' | 'album' | 'artist' | 'playlist'; limit?: number; } export interface SearchResponse { tracks?: { items: any[]; limit: number; next: string | null; offset: number; previous: string | null; total: number; }; albums?: { items: any[]; limit: number; next: string | null; offset: number; previous: string | null; total: number; }; artists?: { items: any[]; limit: number; next: string | null; offset: number; previous: string | null; total: number; }; playlists?: { items: any[]; limit: number; next: string | null; offset: number; previous: string | null; total: number; }; } - src/index.ts:116-140 (registration)Registration of the 'search' tool in the ListTools response, including name, description, and input schema.
name: 'search', description: 'Search for tracks, albums, artists, or playlists', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query' }, type: { type: 'string', description: 'Type of item to search for', enum: ['track', 'album', 'artist', 'playlist'] }, limit: { type: 'number', description: 'Maximum number of results (1-50)', minimum: 1, maximum: 50, default: 20 } }, required: ['query', 'type'] }, }, - src/index.ts:702-708 (registration)Handler for CallTool requests named 'search', which validates arguments and delegates to SearchHandler.search().
case 'search': { const args = this.validateArgs<SearchArgsType>(request.params.arguments, ['query', 'type']); const result = await this.searchHandler.search(args); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], }; } - src/index.ts:87-87 (registration)Instantiation of the SearchHandler instance used by the MCP server.
this.searchHandler = new SearchHandler(this.api);