search

Instructions

Implementation Reference

• src/sse-server.ts:315-404 (registration)

  Registration of the 'search' tool in the tools/list MCP response, including name, description, and full input schema definition.

  {
    name: '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
        },
        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',
          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/sse-server.ts:624-658 (handler)

  Handler logic in handleToolCall for the 'search' tool (shared with 'tavily-search'), prepares parameters, calls TavilyClient.search(), formats result with formatResults, and returns MCP content block.

  case 'tavily-search':
  case 'search':
    const query = args?.query ? String(args.query).substring(0, 100) : 'undefined';
    logWithTimestamp('INFO', `Executing search with query: ${query}`);
  
    const searchParams = {
      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);
    logWithTimestamp('INFO', `Search completed successfully, response size: ${JSON.stringify(result).length} bytes`);
  
    return {
      content: [
        {
          type: 'text',
          text: formatResults(result),
        },
      ],
    };

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

  Core handler/executor in TavilyClient.search(): constructs final params with topic auto-detection and calls makeRequest to POST to Tavily's search API 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/tavilyClient.ts:5-21 (schema)

  TypeScript interface defining the input parameters for the search tool, matching the JSON schema.

  export interface TavilySearchParams {
    query: string;
    search_depth?: 'basic' | 'advanced';
    topic?: 'general' | 'news';
    days?: number;
    time_range?: 'day' | 'week' | 'month' | 'year' | 'd' | 'w' | 'm' | 'y';
    start_date?: string;
    end_date?: string;
    max_results?: number;
    include_images?: boolean;
    include_image_descriptions?: boolean;
    include_raw_content?: boolean;
    include_domains?: string[];
    exclude_domains?: string[];
    country?: string;
    include_favicon?: boolean;
  }

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

  Helper function formatResults that sanitizes, truncates, and formats the raw Tavily search response into a 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;
  }