search_youtube
Search YouTube videos with customizable filters for date, duration, and sorting. Get results with titles, thumbnails, descriptions, and links using SearchAPI.site integration.
Instructions
Performs a YouTube search using SearchAPI.site. Requires a search query and your SearchAPI.site API key. Returns formatted YouTube search results including video titles, thumbnails, descriptions, and links. Supports optional parameters for pagination, sorting, filtering by date and duration.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The YouTube search query to perform | |
| maxResults | No | Maximum number of results to return (1-50) | |
| pageToken | No | Token for pagination to get next/previous page of results | |
| order | No | Sort order for results | |
| publishedAfter | No | Number of days to filter videos from | |
| videoDuration | No | Filter by video duration |
Implementation Reference
- src/tools/searchapi.tool.ts:106-145 (handler)MCP tool handler that maps arguments to controller options, calls the YouTube search controller, and formats the response for MCP.async function handleYouTubeSearch(args: YouTubeSearchToolArgsType) { const methodLogger = Logger.forContext( 'tools/searchapi.tool.ts', 'handleYouTubeSearch', ); methodLogger.debug(`Performing YouTube search for query: ${args.query}`); try { // Map tool arguments to controller options const controllerOptions = { query: args.query, maxResults: args.maxResults, pageToken: args.pageToken, order: args.order, publishedAfter: args.publishedAfter, videoDuration: args.videoDuration, }; // Call the controller with the mapped options const result = await searchApiController.youtubeSearch(controllerOptions); methodLogger.debug(`Got the response from the controller`, result); // Format the response for the MCP tool return { content: [ { type: 'text' as const, text: result.content, }, ], }; } catch (error) { methodLogger.error( `Error performing YouTube search for query: ${args.query}`, error, ); return formatErrorForMcpTool(error); } }
- src/tools/searchapi.types.ts:77-102 (schema)Zod schema defining the input arguments for the search_youtube tool.export const YouTubeSearchToolArgs = z.object({ query: z.string().describe('The YouTube search query to perform'), // apiKey: z.string().optional().describe('Your SearchAPI.site API key'), maxResults: z .number() .min(1) .max(50) .optional() .describe('Maximum number of results to return (1-50)'), pageToken: z .string() .optional() .describe('Token for pagination to get next/previous page of results'), order: z .enum(['date', 'viewCount', 'rating', 'relevance']) .optional() .describe('Sort order for results'), publishedAfter: z .number() .optional() .describe('Number of days to filter videos from'), videoDuration: z .enum(['short', 'medium', 'long', 'any']) .optional() .describe('Filter by video duration'), });
- src/tools/searchapi.tool.ts:182-191 (registration)Registration of the search_youtube tool with the MCP server, including name, description, input schema, and handler function.server.tool( 'search_youtube', `Performs a YouTube search using SearchAPI.site. Requires a search query and your SearchAPI.site API key. Returns formatted YouTube search results including video titles, thumbnails, descriptions, and links. Supports optional parameters for pagination, sorting, filtering by date and duration. `, YouTubeSearchToolArgs.shape, handleYouTubeSearch, );
- Controller function that handles the core YouTube search logic, applies defaults, calls the service, formats results, and handles errors. Called by the tool handler.async function youtubeSearch( options: YouTubeSearchOptions, ): Promise<ControllerResponse> { const methodLogger = Logger.forContext( 'controllers/searchapi.controller.ts', 'youtubeSearch', ); methodLogger.debug(`Performing YouTube search for query: ${options.query}`); try { // Validate required parameters if (!options.query) { throw new Error('Query is required for YouTube search'); } const apiKey = config.get('SEARCHAPI_API_KEY'); if (!apiKey) { throw new Error('API key is required for SearchAPI.site'); } // Define controller defaults const defaults: Partial<YouTubeSearchOptions> = { maxResults: 10, order: 'relevance', videoDuration: 'any', }; // Apply defaults to provided options const mergedOptions = applyDefaults<YouTubeSearchOptions>( options, defaults, ); methodLogger.debug('Using options after defaults:', mergedOptions); // Call the service with the options const searchResponse = await searchApiService.youtubeSearch( { query: mergedOptions.query, maxResults: mergedOptions.maxResults, pageToken: mergedOptions.pageToken, order: mergedOptions.order, publishedAfter: mergedOptions.publishedAfter, videoDuration: mergedOptions.videoDuration, }, apiKey, ); methodLogger.debug(`Got the response from the service`, searchResponse); // Format the data using the formatter const formattedContent = formatYouTubeResults(searchResponse); // Return the standard ControllerResponse structure return { content: formattedContent }; } catch (error) { // Use the standardized error handler with return return handleControllerError(error, { entityType: 'YouTube Search Results', operation: 'searching', source: 'controllers/searchapi.controller.ts@youtubeSearch', additionalInfo: { query: options.query }, }); } }