SeatGeek MCP Server

Instructions

Implementation Reference

• src/tools/findPerformerRecommendations.ts:89-233 (handler)

  Primary tool definition and handler implementation for 'find_performer_recommendations'. Handles input parsing, concurrent searches for performers/events, API calls to recommendations endpoint, and result processing/formatting.
  export const findPerformerRecommendationsTool = { name: 'find_performer_recommendations', description: 'Get personalized performer recommendations based on performers, events, or location. This tool first searches for performers and/or events based on the queries, then uses the IDs to find similar performers. Use location parameters (geoip, lat/lon, postal_code) for nearby performers.', inputSchema: inputSchema, handler: async (args: any, extra: any) => { try { const params = PerformerRecommendationsQuerySchema.parse(args); const performerIds: number[] = []; const eventIds: number[] = []; // If we have event_q or performer_q parameters, try to look up IDs concurrently if (params.event_q || params.performer_q) { try { // Create promises for concurrent execution const promises = []; // Add performer lookup promise if performer_q is provided if (params.performer_q) { const performerPromise = searchPerformers(params.performer_q, params.per_page, 1).then(performers => { if (performers.length > 0) { // Get unique performer IDs const uniqueIds = [...new Set(performers.map((p: any) => p.id).filter(Boolean))] as number[]; performerIds.push(...uniqueIds); } }); promises.push(performerPromise); } // Add event lookup promise if event_q is provided if (params.event_q) { // Prepare additional parameters for the event search const additionalParams: Record<string, any> = {}; // Add venue location parameters if (params.venue_city) { additionalParams["venue.city"] = params.venue_city; } if (params.venue_state) { additionalParams["venue.state"] = params.venue_state; } if (params.venue_country) { additionalParams["venue.country"] = params.venue_country; } // Add date filters if (params.start_utc) { additionalParams["datetime_utc.gte"] = params.start_utc; } if (params.end_utc) { additionalParams["datetime_utc.lte"] = params.end_utc; } const eventPromise = searchEvents(params.event_q, params.per_page, additionalParams).then(events => { if (events.length > 0) { // Get unique event IDs const uniqueIds = [...new Set(events.map((e: any) => e.id).filter(Boolean))] as number[]; eventIds.push(...uniqueIds); } }); promises.push(eventPromise); } // Execute both promises concurrently await Promise.all(promises); } catch (error) { // If lookup fails, continue with original query console.warn('Failed to lookup performer or event, continuing with original query:', error); } } // Build query with found IDs const query = buildQuery(params, performerIds, eventIds); // For performer recommendations, we need to use the correct endpoint // The recommendations endpoint for performers is still RECOMMENDATIONS_ENDPOINT // but with different query parameters const data = await fetchJson(`${RECOMMENDATIONS_ENDPOINT}/performers`, query); if (params.format === 'json') { return { content: [ { type: 'text' as const, text: JSON.stringify(data, null, 2) } ] }; } // Extract performers from recommendations const recommendationsRaw = Array.isArray(data) ? data : (data.recommendations || []); const results: Performer[] = []; for (const item of recommendationsRaw) { try { // Each recommendation has a performer object if (item.performer) { const performer = PerformerSchema.parse(item.performer); results.push(performer); } } catch (error) { // Skip invalid performers console.warn('Skipping invalid performer recommendation:', error); } } // Limit results to per_page const limitedResults = results.slice(0, params.per_page); return { content: [ { type: 'text' as const, text: JSON.stringify(limitedResults, null, 2) } ] }; } catch (error) { console.error('Error in find_performer_recommendations handler:', error); // Provide more detailed error information const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred'; const errorDetails = { error: 'API_REQUEST_FAILED', message: errorMessage, timestamp: new Date().toISOString(), endpoint: RECOMMENDATIONS_ENDPOINT, args: args }; return { content: [ { type: 'text' as const, text: JSON.stringify({ error: 'Failed to fetch performer recommendations', details: errorDetails, suggestion: 'Please check your parameters and try again. Common issues include invalid performer IDs, event IDs, or location parameters.' }, null, 2) } ] }; } }, };
• src/tools/findPerformerRecommendations.ts:67-78 (schema)

  Input schema definition using Zod for validation and descriptions of tool parameters.
  const inputSchema = { event_q: z.string().optional().describe('Search query to find events to base recommendations on. If provided, the system will first look up the event ID automatically.'), performer_q: z.string().optional().describe('Search query to find performers to base recommendations on. If provided, the system will first look up the performer ID automatically.'), venue_city: z.string().optional().describe('City name where the venue is located. Use full city name, e.g., "New York" or "Los Angeles".'), venue_state: z.string().optional().describe('State abbreviation where the venue is located, e.g., "CA" for California or "NY" for New York.'), venue_country: z.string().optional().describe('Country code where the venue is located, e.g., "US" for United States or "CA" for Canada.'), start_utc: z.string().optional().describe('Start date filter in ISO8601 UTC format (YYYY-MM-DD). Use for date ranges like "next month" or "this weekend".'), end_utc: z.string().optional().describe('End date filter in ISO8601 UTC format (YYYY-MM-DD). Use with start_utc to define date ranges.'), per_page: z.number().min(1).max(50).default(10).describe('Number of results to return per page (1-50). Default is 10.'), page: z.number().min(1).default(1).describe('Page number for pagination. Default is 1.'), format: z.enum(['structured', 'json']).default('structured').describe('Output format. Use "structured" for readable format (default) or "json" for raw API response. Only use "json" if explicitly requested.'), };
• src/server.ts:25-25 (registration)

  Registration of the find_performer_recommendations tool with the MCP server.
  mcpServer.tool(findPerformerRecommendationsTool.name, findPerformerRecommendationsTool.description, findPerformerRecommendationsTool.inputSchema, findPerformerRecommendationsTool.handler);
• src/index.ts:3-3 (registration)

  Export of the tool for use in other modules like server.ts.
  export { findPerformerRecommendationsTool } from './tools/findPerformerRecommendations';
• src/tools/findPerformerRecommendations.ts:22-65 (helper)

  Helper function to construct the query object for the recommendations API call.
  function buildQuery(params: PerformerRecommendationsQuery, performerIds: number[] = [], eventIds: number[] = []): Record<string, any> { const query: Record<string, any> = { per_page: Math.min(params.per_page, 50), page: params.page, }; // Add venue location - API expects flat format if (params.venue_city) { query["venue.city"] = params.venue_city; } if (params.venue_state) { query["venue.state"] = params.venue_state; } if (params.venue_country) { query["venue.country"] = params.venue_country; } // Add date filters if provided if (params.start_utc) { query["datetime_utc.gte"] = params.start_utc; } if (params.end_utc) { query["datetime_utc.lte"] = params.end_utc; } // Add performer and event IDs if provided if (performerIds.length > 0) { query["performer_ids"] = performerIds.join(','); } if (eventIds.length > 0) { query["event_ids"] = eventIds.join(','); } // Drop null/undefined values to avoid noisy query strings const filteredQuery: Record<string, any> = {}; for (const [key, value] of Object.entries(query)) { if (value !== null && value !== undefined && value !== '') { filteredQuery[key] = value; } } return filteredQuery; }