Tavily MCP Load Balancer

Instructions

Implementation Reference

• src/index.ts:792-815 (handler)

  The main handler for the 'tavily-map' tool call in the MCP stdio server. Parses arguments, invokes TavilyClient.map(), formats output with formatMapResults, and returns MCP content.
  case 'tavily-map': { const mapParams: TavilyMapParams = { url: args?.url as string, max_depth: (args?.max_depth as number) || 1, max_breadth: (args?.max_breadth as number) || 20, limit: (args?.limit as number) || 50, instructions: args?.instructions as string, select_paths: Array.isArray(args?.select_paths) ? args.select_paths : [], select_domains: Array.isArray(args?.select_domains) ? args.select_domains : [], allow_external: (args?.allow_external as boolean) || false, categories: Array.isArray(args?.categories) ? args.categories : [] }; const mapResult = await this.tavilyClient.map(mapParams); return { content: [ { type: 'text', text: formatMapResults(mapResult), }, ], }; }
• src/index.ts:557-635 (registration)

  Tool registration in listTools handler, defining name, description, and input schema for 'tavily-map'.
  { name: "tavily-map", description: "A powerful web mapping tool that creates a structured map of website URLs, allowing you to discover and analyze site structure, content organization, and navigation paths. Perfect for site audits, content discovery, and understanding website architecture.", inputSchema: { type: "object", properties: { url: { type: "string", description: "The root URL to begin the mapping" }, max_depth: { type: "integer", description: "Max depth of the mapping. Defines how far from the base URL the crawler can explore", default: 1, minimum: 1 }, max_breadth: { type: "integer", description: "Max number of links to follow per level of the tree (i.e., per page)", default: 20, minimum: 1 }, limit: { type: "integer", description: "Total number of links the crawler will process before stopping", default: 50, minimum: 1 }, instructions: { type: "string", description: "Natural language instructions for the crawler" }, select_paths: { type: "array", items: { type: "string" }, description: "Regex patterns to select only URLs with specific path patterns (e.g., /docs/.*, /api/v1.*)", default: [] }, select_domains: { type: "array", items: { type: "string" }, description: "Regex patterns to select crawling to specific domains or subdomains (e.g., ^docs\\.example\\.com$)", default: [] }, allow_external: { type: "boolean", description: "Whether to allow following links that go to external domains", default: false }, categories: { type: "array", items: { type: "string", enum: ["Careers", "Blog", "Documentation", "About", "Pricing", "Community", "Developers", "Contact", "Media"] }, description: "Filter URLs using predefined categories like documentation, blog, api, etc", default: [] }, extract_depth: { type: "string", enum: ["basic", "advanced"], description: "Advanced extraction retrieves more data, including tables and embedded content, with higher success but may increase latency", default: "basic" }, format: { type: "string", enum: ["markdown", "text"], description: "The format of the extracted web page content. markdown returns content in markdown format. text returns plain text and may increase latency.", default: "markdown" }, include_favicon: { type: "boolean", description: "Whether to include the favicon URL for each result", default: false } }, required: ["url"] } } as Tool,
• src/tavilyClient.ts:285-287 (helper)

  Core implementation in TavilyClient: sends HTTP POST request to Tavily API's /map endpoint with parameters and API key.
  async map(params: TavilyMapParams): Promise<any> { return this.makeRequest(this.baseURLs.map, params); }
• src/tavilyClient.ts:49-59 (schema)

  Type definition for input parameters of the tavily-map tool.
  export interface TavilyMapParams { url: string; max_depth?: number; max_breadth?: number; limit?: number; instructions?: string; select_paths?: string[]; select_domains?: string[]; allow_external?: boolean; categories?: string[]; }
• src/index.ts:187-217 (helper)

  Formats the raw API response into a human-readable list of mapped URLs for the tool output.
  export function formatMapResults(response: any): string { try { if (!response || typeof response !== 'object') { return 'Error: Invalid map response format'; } const output = []; output.push(`Site Map Results:`); output.push(`Base URL: ${sanitizeText(response.base_url, 500)}`); output.push('\nMapped Pages:'); if (Array.isArray(response.results)) { response.results.slice(0, 50).forEach((page: any, index: number) => { const pageUrl = typeof page === 'string' ? page : page.url || page; output.push(`\n[${index + 1}] URL: ${sanitizeText(pageUrl, 500)}`); }); } const result = output.join('\n'); // 限制总输出大小 if (result.length > 20000) { return result.substring(0, 20000) + '\n\n... [站点地图过长，已截断]'; } return result; } catch (error) { console.error('Error formatting map results:', error); return 'Error: Failed to format map results'; } }