tavily-search

Instructions

Implementation Reference

• src/index.ts:529-591 (handler)

  The primary handler function that executes the 'tavily-search' tool logic by calling the Tavily search API, processing input parameters, applying defaults from environment, cleaning the payload, making the HTTP POST request, and handling specific API errors.

  async search(params: any): Promise<TavilyResponse> {
    try {
      const endpoint = this.baseURLs.search;
      
      const defaults = this.getDefaultParameters();
      
      // Prepare the request payload
      const searchParams: any = {
        query: params.query,
        search_depth: params.search_depth,
        topic: params.topic,
        days: params.days,
        time_range: params.time_range,
        max_results: params.max_results,
        include_images: params.include_images,
        include_image_descriptions: params.include_image_descriptions,
        include_raw_content: params.include_raw_content,
        include_domains: params.include_domains || [],
        exclude_domains: params.exclude_domains || [],
        country: params.country,
        include_favicon: params.include_favicon,
        start_date: params.start_date,
        end_date: params.end_date,
        api_key: API_KEY,
      };
      
      // Apply default parameters
      for (const key in searchParams) {
        if (key in defaults) {
          searchParams[key] = defaults[key];
        }
      }
      
      // We have to set defaults due to the issue with optional parameter types or defaults = None
      // Because of this, we have to set the time_range to None if start_date or end_date is set 
      // or else start_date and end_date will always cause errors when sent
      if ((searchParams.start_date || searchParams.end_date) && (searchParams.time_range || searchParams.days)) {
        searchParams.days = undefined;
        searchParams.time_range = undefined;
      }
      
      // Remove empty values
      const cleanedParams: any = {};
      for (const key in searchParams) {
        const value = searchParams[key];
        // Skip empty strings, null, undefined, and empty arrays
        if (value !== "" && value !== null && value !== undefined && 
            !(Array.isArray(value) && value.length === 0)) {
          cleanedParams[key] = value;
        }
      }
      
      const response = await this.axiosInstance.post(endpoint, cleanedParams);
      return response.data;
    } catch (error: any) {
      if (error.response?.status === 401) {
        throw new Error('Invalid API key');
      } else if (error.response?.status === 429) {
        throw new Error('Usage limit exceeded');
      }
      throw error;
    }
  }

• src/index.ts:147-242 (schema)

  Input schema definition for the tavily-search tool, specifying all parameters like query, search_depth, topic, time filters, result limits, domain includes/excludes, and country with types, descriptions, defaults, and enums.

  inputSchema: {
    type: "object",
    properties: {
      query: { 
        type: "string", 
        description: "Search query" 
      },
      search_depth: {
        type: "string",
        enum: ["basic","advanced"],
        description: "The depth of the search. It can be 'basic' or 'advanced'",
        default: "basic"
      },
      topic : {
        type: "string",
        enum: ["general","news"],
        description: "The category of the search. This will determine which of our agents will be used for the search",
        default: "general"
      },
      days: {
        type: "number",
        description: "The number of days back from the current date to include in the search results. This specifies the time frame of data to be retrieved. Please note that this feature is only available when using the 'news' search topic",
        default: 3
      },
      time_range: {
        type: "string",
        description: "The time range back from the current date to include in the search results. This feature is available for both 'general' and 'news' search topics",
        enum: ["day", "week", "month", "year", "d", "w", "m", "y"],
      },
      start_date: {
        type: "string",
        description: "Will return all results after the specified start date. Required to be written in the format YYYY-MM-DD.",
        default: "",
      },
      end_date: { 
        type: "string",
        description: "Will return all results before the specified end date. Required to be written in the format YYYY-MM-DD",
        default: "",
      },
      max_results: { 
        type: "number", 
        description: "The maximum number of search results to return",
        default: 10,
        minimum: 5,
        maximum: 20
      },
      include_images: { 
        type: "boolean", 
        description: "Include a list of query-related images in the response",
        default: false,
      },
      include_image_descriptions: { 
        type: "boolean", 
        description: "Include a list of query-related images and their descriptions in the response",
        default: false,
      },
      /*
      // Since the mcp server is using AI clients to generate answers form the search results, we don't need to include this feature.
      include_answer: { 
        type: ["boolean", "string"],
        enum: [true, false, "basic", "advanced"],
        description: "Include an answer to original query, generated by an LLM based on Tavily's search results. Can be boolean or string ('basic'/'advanced'). 'basic'/true answer will be quick but less detailed, 'advanced' answer will be more detailed but take longer to generate",
        default: false,
      },
      */
      include_raw_content: { 
        type: "boolean", 
        description: "Include the cleaned and parsed HTML content of each search result",
        default: false,
      },
      include_domains: {
        type: "array",
        items: { type: "string" },
        description: "A list of domains to specifically include in the search results, if the user asks to search on specific sites set this to the domain of the site",
        default: []
      },
      exclude_domains: {
        type: "array",
        items: { type: "string" },
        description: "List of domains to specifically exclude, if the user asks to exclude a domain set this to the domain of the site",
        default: []
      },
      country: {
        type: "string",
        enum: ['afghanistan', 'albania', 'algeria', 'andorra', 'angola', 'argentina', 'armenia', 'australia', 'austria', 'azerbaijan', 'bahamas', 'bahrain', 'bangladesh', 'barbados', 'belarus', 'belgium', 'belize', 'benin', 'bhutan', 'bolivia', 'bosnia and herzegovina', 'botswana', 'brazil', 'brunei', 'bulgaria', 'burkina faso', 'burundi', 'cambodia', 'cameroon', 'canada', 'cape verde', 'central african republic', 'chad', 'chile', 'china', 'colombia', 'comoros', 'congo', 'costa rica', 'croatia', 'cuba', 'cyprus', 'czech republic', 'denmark', 'djibouti', 'dominican republic', 'ecuador', 'egypt', 'el salvador', 'equatorial guinea', 'eritrea', 'estonia', 'ethiopia', 'fiji', 'finland', 'france', 'gabon', 'gambia', 'georgia', 'germany', 'ghana', 'greece', 'guatemala', 'guinea', 'haiti', 'honduras', 'hungary', 'iceland', 'india', 'indonesia', 'iran', 'iraq', 'ireland', 'israel', 'italy', 'jamaica', 'japan', 'jordan', 'kazakhstan', 'kenya', 'kuwait', 'kyrgyzstan', 'latvia', 'lebanon', 'lesotho', 'liberia', 'libya', 'liechtenstein', 'lithuania', 'luxembourg', 'madagascar', 'malawi', 'malaysia', 'maldives', 'mali', 'malta', 'mauritania', 'mauritius', 'mexico', 'moldova', 'monaco', 'mongolia', 'montenegro', 'morocco', 'mozambique', 'myanmar', 'namibia', 'nepal', 'netherlands', 'new zealand', 'nicaragua', 'niger', 'nigeria', 'north korea', 'north macedonia', 'norway', 'oman', 'pakistan', 'panama', 'papua new guinea', 'paraguay', 'peru', 'philippines', 'poland', 'portugal', 'qatar', 'romania', 'russia', 'rwanda', 'saudi arabia', 'senegal', 'serbia', 'singapore', 'slovakia', 'slovenia', 'somalia', 'south africa', 'south korea', 'south sudan', 'spain', 'sri lanka', 'sudan', 'sweden', 'switzerland', 'syria', 'taiwan', 'tajikistan', 'tanzania', 'thailand', 'togo', 'trinidad and tobago', 'tunisia', 'turkey', 'turkmenistan', 'uganda', 'ukraine', 'united arab emirates', 'united kingdom', 'united states', 'uruguay', 'uzbekistan', 'venezuela', 'vietnam', 'yemen', 'zambia', 'zimbabwe'],
        description: "Boost search results from a specific country. This will prioritize content from the selected country in the search results. Available only if topic is general. Country names MUST be written in lowercase, plain English, with spaces and no underscores.",
        default: ""
      },
      include_favicon: { 
        type: "boolean", 
        description: "Whether to include the favicon URL for each result",
        default: false,
      }
    },
    required: ["query"]
  }

• src/index.ts:144-243 (registration)

  Registration of the tavily-search tool in the MCP ListToolsRequestSchema handler, including name, description, and reference to inputSchema.

  {
    name: "tavily-search",
    description: "A powerful web search tool that provides comprehensive, real-time results using Tavily's AI search engine. Returns relevant web content with customizable parameters for result count, content type, and domain filtering. Ideal for gathering current information, news, and detailed web content analysis.",
    inputSchema: {
      type: "object",
      properties: {
        query: { 
          type: "string", 
          description: "Search query" 
        },
        search_depth: {
          type: "string",
          enum: ["basic","advanced"],
          description: "The depth of the search. It can be 'basic' or 'advanced'",
          default: "basic"
        },
        topic : {
          type: "string",
          enum: ["general","news"],
          description: "The category of the search. This will determine which of our agents will be used for the search",
          default: "general"
        },
        days: {
          type: "number",
          description: "The number of days back from the current date to include in the search results. This specifies the time frame of data to be retrieved. Please note that this feature is only available when using the 'news' search topic",
          default: 3
        },
        time_range: {
          type: "string",
          description: "The time range back from the current date to include in the search results. This feature is available for both 'general' and 'news' search topics",
          enum: ["day", "week", "month", "year", "d", "w", "m", "y"],
        },
        start_date: {
          type: "string",
          description: "Will return all results after the specified start date. Required to be written in the format YYYY-MM-DD.",
          default: "",
        },
        end_date: { 
          type: "string",
          description: "Will return all results before the specified end date. Required to be written in the format YYYY-MM-DD",
          default: "",
        },
        max_results: { 
          type: "number", 
          description: "The maximum number of search results to return",
          default: 10,
          minimum: 5,
          maximum: 20
        },
        include_images: { 
          type: "boolean", 
          description: "Include a list of query-related images in the response",
          default: false,
        },
        include_image_descriptions: { 
          type: "boolean", 
          description: "Include a list of query-related images and their descriptions in the response",
          default: false,
        },
        /*
        // Since the mcp server is using AI clients to generate answers form the search results, we don't need to include this feature.
        include_answer: { 
          type: ["boolean", "string"],
          enum: [true, false, "basic", "advanced"],
          description: "Include an answer to original query, generated by an LLM based on Tavily's search results. Can be boolean or string ('basic'/'advanced'). 'basic'/true answer will be quick but less detailed, 'advanced' answer will be more detailed but take longer to generate",
          default: false,
        },
        */
        include_raw_content: { 
          type: "boolean", 
          description: "Include the cleaned and parsed HTML content of each search result",
          default: false,
        },
        include_domains: {
          type: "array",
          items: { type: "string" },
          description: "A list of domains to specifically include in the search results, if the user asks to search on specific sites set this to the domain of the site",
          default: []
        },
        exclude_domains: {
          type: "array",
          items: { type: "string" },
          description: "List of domains to specifically exclude, if the user asks to exclude a domain set this to the domain of the site",
          default: []
        },
        country: {
          type: "string",
          enum: ['afghanistan', 'albania', 'algeria', 'andorra', 'angola', 'argentina', 'armenia', 'australia', 'austria', 'azerbaijan', 'bahamas', 'bahrain', 'bangladesh', 'barbados', 'belarus', 'belgium', 'belize', 'benin', 'bhutan', 'bolivia', 'bosnia and herzegovina', 'botswana', 'brazil', 'brunei', 'bulgaria', 'burkina faso', 'burundi', 'cambodia', 'cameroon', 'canada', 'cape verde', 'central african republic', 'chad', 'chile', 'china', 'colombia', 'comoros', 'congo', 'costa rica', 'croatia', 'cuba', 'cyprus', 'czech republic', 'denmark', 'djibouti', 'dominican republic', 'ecuador', 'egypt', 'el salvador', 'equatorial guinea', 'eritrea', 'estonia', 'ethiopia', 'fiji', 'finland', 'france', 'gabon', 'gambia', 'georgia', 'germany', 'ghana', 'greece', 'guatemala', 'guinea', 'haiti', 'honduras', 'hungary', 'iceland', 'india', 'indonesia', 'iran', 'iraq', 'ireland', 'israel', 'italy', 'jamaica', 'japan', 'jordan', 'kazakhstan', 'kenya', 'kuwait', 'kyrgyzstan', 'latvia', 'lebanon', 'lesotho', 'liberia', 'libya', 'liechtenstein', 'lithuania', 'luxembourg', 'madagascar', 'malawi', 'malaysia', 'maldives', 'mali', 'malta', 'mauritania', 'mauritius', 'mexico', 'moldova', 'monaco', 'mongolia', 'montenegro', 'morocco', 'mozambique', 'myanmar', 'namibia', 'nepal', 'netherlands', 'new zealand', 'nicaragua', 'niger', 'nigeria', 'north korea', 'north macedonia', 'norway', 'oman', 'pakistan', 'panama', 'papua new guinea', 'paraguay', 'peru', 'philippines', 'poland', 'portugal', 'qatar', 'romania', 'russia', 'rwanda', 'saudi arabia', 'senegal', 'serbia', 'singapore', 'slovakia', 'slovenia', 'somalia', 'south africa', 'south korea', 'south sudan', 'spain', 'sri lanka', 'sudan', 'sweden', 'switzerland', 'syria', 'taiwan', 'tajikistan', 'tanzania', 'thailand', 'togo', 'trinidad and tobago', 'tunisia', 'turkey', 'turkmenistan', 'uganda', 'ukraine', 'united arab emirates', 'united kingdom', 'united states', 'uruguay', 'uzbekistan', 'venezuela', 'vietnam', 'yemen', 'zambia', 'zimbabwe'],
          description: "Boost search results from a specific country. This will prioritize content from the selected country in the search results. Available only if topic is general. Country names MUST be written in lowercase, plain English, with spaces and no underscores.",
          default: ""
        },
        include_favicon: { 
          type: "boolean", 
          description: "Whether to include the favicon URL for each result",
          default: false,
        }
      },
      required: ["query"]
    }
  },

• src/index.ts:418-441 (handler)

  Dispatch handler in the CallToolRequestSchema that maps input arguments to the search method for tavily-search tool execution.

  case "tavily-search":
    // If country is set, ensure topic is general
    if (args.country) {
      args.topic = "general";
    }
    
    response = await this.search({
      query: args.query,
      search_depth: args.search_depth,
      topic: args.topic,
      days: args.days,
      time_range: args.time_range,
      max_results: args.max_results,
      include_images: args.include_images,
      include_image_descriptions: args.include_image_descriptions,
      include_raw_content: args.include_raw_content,
      include_domains: Array.isArray(args.include_domains) ? args.include_domains : [],
      exclude_domains: Array.isArray(args.exclude_domains) ? args.exclude_domains : [],
      country: args.country,
      include_favicon: args.include_favicon,
      start_date: args.start_date,
      end_date: args.end_date
    });
    break;

• src/index.ts:645-684 (helper)

  Helper function to format the Tavily search response into a human-readable text string used in the tool output.

  function formatResults(response: TavilyResponse): string {
    // Format API response into human-readable text
    const output: string[] = [];
  
    // Include answer if available
    if (response.answer) {
      output.push(`Answer: ${response.answer}`);
    }
  
    // Format detailed search results
    output.push('Detailed Results:');
    response.results.forEach(result => {
      output.push(`\nTitle: ${result.title}`);
      output.push(`URL: ${result.url}`);
      output.push(`Content: ${result.content}`);
      if (result.raw_content) {
        output.push(`Raw Content: ${result.raw_content}`);
      }
      if (result.favicon) {
        output.push(`Favicon: ${result.favicon}`);
      }
    });
  
      // Add images section if available
      if (response.images && response.images.length > 0) {
        output.push('\nImages:');
        response.images.forEach((image, index) => {
          if (typeof image === 'string') {
            output.push(`\n[${index + 1}] URL: ${image}`);
          } else {
            output.push(`\n[${index + 1}] URL: ${image.url}`);
            if (image.description) {
              output.push(`   Description: ${image.description}`);
            }
          }
        });
      }  
  
    return output.join('\n');
  }