tavily-map
Generate structured website maps to analyze site architecture, navigation paths, and content organization. Ideal for site audits, content discovery, and understanding web structure with customizable depth and breadth settings.
Instructions
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| allow_external | No | Whether to allow following links that go to external domains | |
| categories | No | Filter URLs using predefined categories like documentation, blog, api, etc | |
| instructions | Yes | Natural language instructions for the crawler | |
| limit | No | Total number of links the crawler will process before stopping | |
| max_breadth | No | Max number of links to follow per level of the tree (i.e., per page) | |
| max_depth | No | Max depth of the mapping. Defines how far from the base URL the crawler can explore | |
| select_domains | No | Regex patterns to select crawling to specific domains or subdomains (e.g., ^docs\.example\.com$) | |
| select_paths | No | Regex patterns to select only URLs with specific path patterns (e.g., /docs/.*, /api/v1.*) | |
| url | Yes | Root URL to begin the mapping |
Implementation Reference
- src/tavily_mcp_sse/server.py:283-352 (handler)The core handler function for the 'tavily-map' tool, decorated with @mcp_server.tool(name='tavily-map'). It constructs parameters from inputs, sends a POST request to Tavily's map API endpoint, handles authentication/rate limit errors, and validates/returns the response using TavilyMapResponse schema.
@mcp_server.tool(name='tavily-map') async def map( url: Annotated[str, Field( description="""Root URL to begin the mapping""" )], instructions: Annotated[str, Field( description="""Natural language instructions for the crawler""" )], max_depth: Annotated[int, Field( default=1, ge=1, description="""Max depth of the mapping. Defines how far from the base URL the crawler can explore""" )], max_breadth: Annotated[int, Field( default=20, ge=1, description="""Max number of links to follow per level of the tree (i.e., per page)""" )], limit: Annotated[int, Field( default=50, ge=1, description="""Total number of links the crawler will process before stopping""" )], select_paths: Annotated[list[str], Field( default_factory=list, description="""Regex patterns to select only URLs with specific path patterns (e.g., /docs/.*, /api/v1.*)""" )], select_domains: Annotated[list[str], Field( default_factory=list, description="""Regex patterns to select crawling to specific domains or subdomains (e.g., ^docs\\.example\\.com$)""" )], allow_external: Annotated[bool, Field( default=False, description="""Whether to allow following links that go to external domains""" )], categories: Annotated[list[CrawlCategoriesLiteral], Field( default_factory=list, description="""Filter URLs using predefined categories like documentation, blog, api, etc""" )], ) -> dict[str, Any]: """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.""" endpoint = base_urls['map'] search_params = { "url": url, "instructions": instructions, "max_depth": max_depth, "max_breadth": max_breadth, "limit": limit, "select_paths": select_paths, "select_domains": select_domains, "allow_external": allow_external, "categories": categories, "api_key": TAVILY_API_KEY, } try: async with httpx.AsyncClient(headers=headers) as client: response = await client.post(endpoint, json=search_params) if not response.is_success: if response.status_code == 401: raise ValueError("Invalid API Key") elif response.status_code == 429: raise ValueError("Usage limit exceeded") _ = response.raise_for_status() except BaseException as e: raise e response_dict: dict[str, Any] = response.json() return TavilyMapResponse.model_validate(response_dict).model_dump() - src/tavily_mcp_sse/schemas.py:51-55 (schema)Pydantic model (TavilyMapResponse) defining the expected response structure from the Tavily map API, used for validation in the tool handler.
class TavilyMapResponse(BaseModel): base_url: str results: list[str] response_time: float - src/tavily_mcp_sse/server.py:283-283 (registration)The @mcp_server.tool decorator registers the 'map' function as the 'tavily-map' tool with the MCP server.
@mcp_server.tool(name='tavily-map')