SearchAPI MCP Server

Instructions

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,
  	);

• src/controllers/searchapi.controller.ts:179-241 (helper)

  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 },
  		});
  	}
  }