SeatGeek MCP Server

Instructions

Implementation Reference

• src/tools/findEventRecommendations.ts:90-229 (handler)

  The main handler function that executes the tool logic: parses input parameters, optionally looks up performer or event IDs based on query 'q', builds the API query, fetches recommendations from the endpoint, processes and condenses event data, and returns formatted JSON output or error details.
  handler: async (args: any, extra: any) => { try { const params = EventRecommendationsQuerySchema.parse(args); let performerId: number | null = null; let eventId: number | null = null; // If we have a q parameter, try to look up performer and event IDs if (params.q) { try { // First try to find performers with the query const performers = await searchPerformers(params.q, params.per_page, 1); // If we found performers, aggregate unique performer slugs and make Promise.all query if (performers.length > 0) { // Get unique performer slugs const uniqueSlugs = [...new Set(performers.map((p: any) => p.slug).filter(Boolean))] as string[]; if (uniqueSlugs.length > 0) { // Create promises for each unique performer slug const promises = uniqueSlugs.map(slug => { return searchEvents(slug, params.per_page, { "performers.slug": slug }); }); // Execute all promises const results = await Promise.all(promises); // Merge events from all results const allEvents: any[] = []; for (const result of results) { if (Array.isArray(result)) { allEvents.push(...result); } } // Remove duplicates based on event id const eventIds = new Set(); const uniqueEvents = allEvents.filter(event => { if (eventIds.has(event.id)) { return false; } eventIds.add(event.id); return true; }); // Use the first event's ID for recommendations if available if (uniqueEvents.length > 0 && uniqueEvents[0].id) { eventId = uniqueEvents[0].id; } } else { // If no valid slugs found, search events directly with the q parameter const events = await searchEvents(params.q, params.per_page, {}); if (events.length > 0 && events[0].id) { eventId = events[0].id; } } } else { // If no performer found, search events directly with the q parameter const events = await searchEvents(params.q, params.per_page, {}); if (events.length > 0 && events[0].id) { eventId = events[0].id; } } } 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 (convert null to undefined for TypeScript) const query = buildQuery( params, performerId !== null ? performerId : undefined, eventId !== null ? eventId : undefined ); const data = await fetchJson(RECOMMENDATIONS_ENDPOINT, query); if (params.format === 'json') { return { content: [ { type: 'text' as const, text: JSON.stringify(data, null, 2) } ] }; } // Extract events from recommendations const recommendationsRaw = Array.isArray(data) ? data : (data.recommendations || []); const results: CondensedEvent[] = []; for (const item of recommendationsRaw) { try { // Each recommendation has an event object if (item.event) { // Condense the event data const condensedEvent = condenseEventData(item.event); results.push(condensedEvent); } } catch (error) { // Skip invalid events console.warn('Skipping invalid event recommendation:', error); } } return { content: [ { type: 'text' as const, text: JSON.stringify(results, null, 2) } ] }; } catch (error) { console.error('Error in find_event_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 event 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/findEventRecommendations.ts:63-75 (schema)

  Zod-based input schema defining parameters for event recommendations, including search query, location filters, date ranges, pagination, and output format with detailed descriptions for the MCP tool.
  const inputSchema = { q: z.string().optional().describe('Search query to find either an event or performer to base recommendations on. If provided, the system will first look up the event ID or performer ID/slug automatically.'), geoip: z.boolean().optional().describe('Use IP geolocation to provide recommendations for events near the user.'), lat: z.number().optional().describe('Latitude coordinate for location-based recommendations. Use with lon and optionally range.'), lon: z.number().optional().describe('Longitude coordinate for location-based recommendations. Use with lat and optionally range.'), postal_code: z.string().optional().describe('Postal code for location-based recommendations. Use with country code for better accuracy.'), range: z.string().optional().describe('Search radius for location-based recommendations (e.g., "50mi", "25km"). Use with lat/lon or postal_code.'), 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:24-24 (registration)

  Registers the 'find_event_recommendations' tool with the MCP server using its name, description, input schema, and handler function.
  mcpServer.tool(findEventRecommendationsTool.name, findEventRecommendationsTool.description, findEventRecommendationsTool.inputSchema, findEventRecommendationsTool.handler);
• src/tools/findEventRecommendations.ts:23-61 (helper)

  Helper function that constructs and filters the query parameters for the recommendations API endpoint, incorporating location, date filters, pagination, and optional performer/event IDs.
  function buildQuery(params: EventRecommendationsQuery, performerId?: number, eventId?: number): Record<string, any> { const query: Record<string, any> = { "geoip": params.geoip, "lat": params.lat, "lon": params.lon, "postal_code": params.postal_code, "range": params.range, per_page: Math.min(params.per_page, 50), page: params.page, }; // Add performer and event IDs if provided if (performerId) { query["performers.id"] = performerId; } if (eventId) { query["events.id"] = eventId; }; // 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; } // 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) { filteredQuery[key] = value; } } return filteredQuery; }