tavily-map

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