suggest_related_searches
Expand search queries with related suggestions from DuckDuckGo's autocomplete API to discover alternative search terms and explore topics more thoroughly.
Instructions
Get search suggestions from DuckDuckGo autocomplete API.
Returns suggestions based on what people actually search for.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Original search query | |
| max_suggestions | No | Maximum number of related suggestions to return |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- mcp_duckduckgo/tools.py:216-275 (handler)The handler function that implements the core logic of the 'suggest_related_searches' tool. It fetches autocomplete suggestions using a helper function and returns formatted results. Includes input schema via Pydantic Field validators.
@mcp_server.tool() async def suggest_related_searches( query: str = Field(..., description="Original search query"), max_suggestions: int = Field( 5, ge=1, le=10, description="Maximum number of related suggestions to return", ), ctx: Context = Field(default_factory=Context), ) -> Dict[str, Any]: """ Get search suggestions from DuckDuckGo autocomplete API. Returns suggestions based on what people actually search for. """ logger.info( "Getting autocomplete suggestions for: '%s' (max %d suggestions)", query, max_suggestions, ) # Get HTTP client from context http_client = None close_client = False try: if ( hasattr(ctx, "lifespan_context") and ctx.lifespan_context and "http_client" in ctx.lifespan_context ): logger.info("Using HTTP client from lifespan context") http_client = ctx.lifespan_context["http_client"] else: logger.info("Creating new HTTP client") http_client = httpx.AsyncClient(timeout=10.0) close_client = True # Get autocomplete suggestions from DuckDuckGo suggestions = await get_autocomplete_suggestions(query, http_client) return { "original_query": query, "related_searches": suggestions[:max_suggestions], "count": len(suggestions[:max_suggestions]), } except (httpx.RequestError, httpx.HTTPError, ValueError) as e: logger.error("Failed to get autocomplete suggestions: %s", e) return { "original_query": query, "related_searches": [], "count": 0, "error": str(e), } finally: if close_client and http_client: await http_client.aclose() - mcp_duckduckgo/tools.py:18-39 (helper)Supporting utility function that performs the HTTP request to DuckDuckGo's autocomplete API to retrieve related search suggestions. Called directly by the handler.
async def get_autocomplete_suggestions( query: str, http_client: httpx.AsyncClient ) -> List[str]: """Get search suggestions from DuckDuckGo autocomplete API.""" try: url = "https://duckduckgo.com/ac/" params = {"q": query, "type": "list"} response = await http_client.get(url, params=params, timeout=10) response.raise_for_status() data = response.json() # Response format: ["query", ["suggestion1", "suggestion2", ...]] suggestions = data[1] if len(data) > 1 and isinstance(data[1], list) else [] logger.info("Found %d autocomplete suggestions", len(suggestions)) return suggestions except (httpx.RequestError, httpx.HTTPError, ValueError) as e: logger.error("Failed to get autocomplete suggestions: %s", e) return [] - mcp_duckduckgo/server.py:47-47 (registration)Invocation of register_search_tools(server), which executes the nested function definitions and @tool() decorators to register the 'suggest_related_searches' handler (and other tools) with the MCP server instance.
register_search_tools(server)