Tavily MCP Server

Instructions

Implementation Reference

• src/index.ts:512-527 (handler)

  Core implementation of the 'tavily-map' tool handler. Posts parameters to the Tavily map API endpoint ('https://api.tavily.com/map'), handles authentication and rate limit errors, and returns the API response containing the site map.

  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:287-343 (schema)

  Input schema for the 'tavily-map' tool, defining parameters such as url (required), max_depth, max_breadth, limit, instructions, filtering options, and categories.

  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:284-345 (registration)

  Registration of the 'tavily-map' tool in the ListToolsRequestSchema handler, providing name, description, and input schema.

  {
    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:400-417 (handler)

  Dispatch handler case for 'tavily-map' in the CallToolRequestSchema. Parses arguments, calls the map method, formats the result, and returns the tool 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:589-601 (helper)

  Helper function to format the Tavily map API response into a human-readable string listing the base URL and mapped page URLs.

  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');
  }