tavily-mcp

Instructions

Implementation Reference

• src/index.ts:513-528 (handler)

  Core handler function that implements the tavily-map tool by making a POST request to the Tavily API's map endpoint with user parameters and handling errors.
  async map(params: any): Promise<TavilyMapResponse> { try { const response = await this.axiosInstance.post(this.baseURLs.map, { ...params, api_key: API_KEY }); 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:285-346 (registration)

  Registration of the tavily-map tool in the ListToolsRequestSchema handler, defining its name, description, and input schema for validation.
  { 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: [] } }, required: ["url"] } },
• src/index.ts:401-418 (handler)

  Dispatch case in the CallToolRequestSchema handler that invokes the tavily-map implementation with arguments and formats the response.
  case "tavily-map": const mapResponse = await this.map({ url: args.url, max_depth: args.max_depth, max_breadth: args.max_breadth, limit: args.limit, instructions: args.instructions, 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, categories: Array.isArray(args.categories) ? args.categories : [] }); return { content: [{ type: "text", text: formatMapResults(mapResponse) }] };
• src/index.ts:590-602 (helper)

  Supporting helper function that formats the TavilyMapResponse into a readable text output for the tool response.
  function formatMapResults(response: TavilyMapResponse): string { const output: string[] = []; output.push(`Site Map Results:`); output.push(`Base URL: ${response.base_url}`); output.push('\nMapped Pages:'); response.results.forEach((page, index) => { output.push(`\n[${index + 1}] URL: ${page}`); }); return output.join('\n'); }
• src/index.ts:49-53 (schema)

  TypeScript interface defining the expected response schema from the Tavily map API.
  interface TavilyMapResponse { base_url: string; results: string[]; response_time: number; }