tavily-search

Instructions

Implementation Reference

• src/index.ts:317-346 (handler)

  Primary handler function for the 'tavily-search' tool in the stdio MCP server. Prepares search parameters from tool arguments, calls TavilyClient.search(), formats the result, and returns MCP-standard content response.

  private async handleSearch(args: any) {
    const searchParams: TavilySearchParams = {
      query: args?.query as string,
      search_depth: (args?.search_depth as 'basic' | 'advanced') || 'basic',
      topic: (args?.topic as 'general' | 'news') || 'general',
      days: (args?.days as number) || 3,
      time_range: args?.time_range as 'day' | 'week' | 'month' | 'year' | 'd' | 'w' | 'm' | 'y',
      start_date: args?.start_date as string,
      end_date: args?.end_date as string,
      max_results: (args?.max_results as number) || 10,
      include_images: (args?.include_images as boolean) || false,
      include_image_descriptions: (args?.include_image_descriptions as boolean) || false,
      include_raw_content: (args?.include_raw_content as boolean) || false,
      include_domains: Array.isArray(args?.include_domains) ? args.include_domains : [],
      exclude_domains: Array.isArray(args?.exclude_domains) ? args.exclude_domains : [],
      country: args?.country as string,
      include_favicon: (args?.include_favicon as boolean) || false
    };
  
    const result = await this.tavilyClient.search(searchParams);
  
    return {
      content: [
        {
          type: 'text',
          text: formatResults(result),
        },
      ],
    };
  }

• src/index.ts:350-435 (schema)

  JSON Schema defining the input parameters and validation for the 'tavily-search' tool.

  const searchToolSchema = {
    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"]
      },
      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
      },
      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: []
      },
      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: ""
      },
      country: {
        type: "string",
        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:442-446 (registration)

  Registration of the 'tavily-search' tool in the ListTools response within the stdio MCP server.

  {
    name: "tavily-search",
    description: searchToolDescription,
    inputSchema: searchToolSchema
  } as Tool,

• src/tavilyClient.ts:267-275 (handler)

  Core implementation of the search functionality in TavilyClient: automatically detects news queries, constructs parameters, and invokes the generic API request maker for Tavily's search endpoint.

  async search(params: TavilySearchParams): Promise<TavilyResponse> {
    // Add automatic topic detection for news
    const searchParams = {
      ...params,
      topic: params.query.toLowerCase().includes('news') ? 'news' : params.topic
    };
    
    return this.makeRequest(this.baseURLs.search, searchParams);
  }

• src/index.ts:96-144 (helper)

  Helper function that formats, sanitizes, and structures the raw Tavily search API response into a human-readable text output for the MCP tool response.

  export function formatResults(response: any): string {
    const safeResponse = validateAndSanitizeResponse(response);
  
    if (safeResponse.error) {
      return `Error: ${safeResponse.error}`;
    }
  
    const output = [];
  
    if (safeResponse.answer) {
      output.push(`Answer: ${safeResponse.answer}`);
    }
  
    output.push('Detailed Results:');
    safeResponse.results.forEach((result: any, index: number) => {
      output.push(`\n[${index + 1}] Title: ${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.score) {
        output.push(`Relevance Score: ${result.score}`);
      }
    });
  
    if (safeResponse.images && safeResponse.images.length > 0) {
      output.push('\nImages:');
      safeResponse.images.forEach((image: any, index: number) => {
        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}`);
          }
        }
      });
    }
  
    const result = output.join('\n');
  
    // 最终检查结果大小
    if (result.length > 50000) {
      return result.substring(0, 50000) + '\n\n... [响应内容过长，已截断]';
    }
  
    return result;
  }