Web Research Assistant

Instructions

Implementation Reference

• src/searxng_mcp/server.py:239-381 (handler)

  Implementation of the 'search_examples' MCP tool handler. Searches for code examples, tutorials, and articles using an optimized SearXNG search with content-type specific query enhancements. Formats results with source indicators and diagnostics for limited diversity.
  @mcp.tool() async def search_examples( query: Annotated[ str, "What you're looking for (e.g., 'Python async await examples', 'React hooks tutorial', 'Rust error handling patterns')", ], reasoning: Annotated[str, "Why you're searching for examples (required for analytics)"], content_type: Annotated[ Literal["code", "articles", "both"], "Type of content to find: 'code' for code examples, 'articles' for tutorials/blogs, 'both' for mixed results", ] = "both", time_range: Annotated[ Literal["day", "week", "month", "year", "all"], "How recent the content should be (use 'all' for best results, filter down if too many results)", ] = "all", max_results: Annotated[int, "How many results to return (1-10)"] = DEFAULT_MAX_RESULTS, ) -> str: """ Search for code examples, tutorials, and technical articles. Optimized for finding practical examples and learning resources. Can optionally filter by time range for the most recent content. Perfect for learning new APIs, finding usage patterns, or discovering how others solve specific technical problems. Content Types: - 'code': GitHub repos, code snippets, gists, Stack Overflow code examples - 'articles': Blog posts, tutorials, documentation, technical articles - 'both': Mix of code and written content (default) Time Ranges: - 'all': Search all available content (default, recommended for best results) - 'year', 'month', 'week', 'day': Filter to recent content only Examples: - search_examples("FastAPI dependency injection examples", content_type="code") - search_examples("React hooks tutorial", content_type="articles", time_range="year") - search_examples("Rust lifetime examples", content_type="both") """ start_time = time.time() success = False error_msg = None result = "" try: max_results = max(1, min(max_results, 10)) # Build optimized search query based on content type enhanced_query = query if content_type == "code": # Prioritize code-heavy sources enhanced_query = f"{query} (site:github.com OR site:stackoverflow.com OR site:gist.github.com OR example OR snippet)" elif content_type == "articles": # Prioritize articles and tutorials enhanced_query = ( f"{query} (tutorial OR guide OR article OR blog OR how to OR documentation)" ) else: # both enhanced_query = f"{query} (example OR tutorial OR guide)" # Use 'it' category for better tech content hits = await searcher.search( enhanced_query, category="it", # IT/tech category for better results max_results=max_results, time_range=time_range if time_range != "all" else None, ) if not hits: result = ( f"No examples found for '{query}' in the {time_range if time_range != 'all' else 'all time'} range.\n\n" "Try:\n" "- Broader search terms\n" "- Different time range\n" "- Removing version numbers or very specific constraints\n\n" "Note: Results depend on your SearXNG instance configuration. If you're only seeing MDN docs,\n" "your SearXNG may need additional search engines enabled (GitHub, Stack Overflow, dev.to, etc.)." ) else: # Format results with additional context lines = [ f"Code Examples & Articles for: {query}", f"Time Range: {time_range.title() if time_range != 'all' else 'All time'} | Content Type: {content_type.title()}", "─" * 50, "", ] for idx, hit in enumerate(hits, 1): # Add source indicator source = "" if "github.com" in hit.url: source = "[GitHub] " elif "stackoverflow.com" in hit.url: source = "[Stack Overflow] " elif "medium.com" in hit.url or "dev.to" in hit.url: source = "[Article] " snippet = f"\n {hit.snippet}" if hit.snippet else "" lines.append(f"{idx}. {source}{hit.title}") lines.append(f" {hit.url}{snippet}") lines.append("") result_text = "\n".join(lines) # Add note if results seem limited (all from same domain) domains = set() for hit in hits: if "://" in hit.url: domain = hit.url.split("://")[1].split("/")[0] domains.add(domain) if len(domains) == 1 and len(hits) > 2: result_text += ( "\n\n──────────────────────────────────────────────────\n" "ℹ️ Note: All results are from the same source. Your SearXNG instance may need\n" " additional search engines configured (GitHub, Stack Overflow, dev.to, Medium)\n" " to get diverse code examples and tutorials." ) result = clamp_text(result_text, MAX_RESPONSE_CHARS) success = True except Exception as exc: # noqa: BLE001 error_msg = str(exc) result = f"Search failed for '{query}': {exc}" finally: # Track usage response_time = (time.time() - start_time) * 1000 tracker.track_usage( tool_name="search_examples", reasoning=reasoning, parameters={ "query": query, "content_type": content_type, "time_range": time_range, "max_results": max_results, }, response_time_ms=response_time, success=success, error_message=error_msg, response_size=len(result.encode("utf-8")), ) return result
• src/searxng_mcp/server.py:239-381 (registration)

  The @mcp.tool() decorator registers the search_examples function as an MCP tool.
  @mcp.tool() async def search_examples( query: Annotated[ str, "What you're looking for (e.g., 'Python async await examples', 'React hooks tutorial', 'Rust error handling patterns')", ], reasoning: Annotated[str, "Why you're searching for examples (required for analytics)"], content_type: Annotated[ Literal["code", "articles", "both"], "Type of content to find: 'code' for code examples, 'articles' for tutorials/blogs, 'both' for mixed results", ] = "both", time_range: Annotated[ Literal["day", "week", "month", "year", "all"], "How recent the content should be (use 'all' for best results, filter down if too many results)", ] = "all", max_results: Annotated[int, "How many results to return (1-10)"] = DEFAULT_MAX_RESULTS, ) -> str: """ Search for code examples, tutorials, and technical articles. Optimized for finding practical examples and learning resources. Can optionally filter by time range for the most recent content. Perfect for learning new APIs, finding usage patterns, or discovering how others solve specific technical problems. Content Types: - 'code': GitHub repos, code snippets, gists, Stack Overflow code examples - 'articles': Blog posts, tutorials, documentation, technical articles - 'both': Mix of code and written content (default) Time Ranges: - 'all': Search all available content (default, recommended for best results) - 'year', 'month', 'week', 'day': Filter to recent content only Examples: - search_examples("FastAPI dependency injection examples", content_type="code") - search_examples("React hooks tutorial", content_type="articles", time_range="year") - search_examples("Rust lifetime examples", content_type="both") """ start_time = time.time() success = False error_msg = None result = "" try: max_results = max(1, min(max_results, 10)) # Build optimized search query based on content type enhanced_query = query if content_type == "code": # Prioritize code-heavy sources enhanced_query = f"{query} (site:github.com OR site:stackoverflow.com OR site:gist.github.com OR example OR snippet)" elif content_type == "articles": # Prioritize articles and tutorials enhanced_query = ( f"{query} (tutorial OR guide OR article OR blog OR how to OR documentation)" ) else: # both enhanced_query = f"{query} (example OR tutorial OR guide)" # Use 'it' category for better tech content hits = await searcher.search( enhanced_query, category="it", # IT/tech category for better results max_results=max_results, time_range=time_range if time_range != "all" else None, ) if not hits: result = ( f"No examples found for '{query}' in the {time_range if time_range != 'all' else 'all time'} range.\n\n" "Try:\n" "- Broader search terms\n" "- Different time range\n" "- Removing version numbers or very specific constraints\n\n" "Note: Results depend on your SearXNG instance configuration. If you're only seeing MDN docs,\n" "your SearXNG may need additional search engines enabled (GitHub, Stack Overflow, dev.to, etc.)." ) else: # Format results with additional context lines = [ f"Code Examples & Articles for: {query}", f"Time Range: {time_range.title() if time_range != 'all' else 'All time'} | Content Type: {content_type.title()}", "─" * 50, "", ] for idx, hit in enumerate(hits, 1): # Add source indicator source = "" if "github.com" in hit.url: source = "[GitHub] " elif "stackoverflow.com" in hit.url: source = "[Stack Overflow] " elif "medium.com" in hit.url or "dev.to" in hit.url: source = "[Article] " snippet = f"\n {hit.snippet}" if hit.snippet else "" lines.append(f"{idx}. {source}{hit.title}") lines.append(f" {hit.url}{snippet}") lines.append("") result_text = "\n".join(lines) # Add note if results seem limited (all from same domain) domains = set() for hit in hits: if "://" in hit.url: domain = hit.url.split("://")[1].split("/")[0] domains.add(domain) if len(domains) == 1 and len(hits) > 2: result_text += ( "\n\n──────────────────────────────────────────────────\n" "ℹ️ Note: All results are from the same source. Your SearXNG instance may need\n" " additional search engines configured (GitHub, Stack Overflow, dev.to, Medium)\n" " to get diverse code examples and tutorials." ) result = clamp_text(result_text, MAX_RESPONSE_CHARS) success = True except Exception as exc: # noqa: BLE001 error_msg = str(exc) result = f"Search failed for '{query}': {exc}" finally: # Track usage response_time = (time.time() - start_time) * 1000 tracker.track_usage( tool_name="search_examples", reasoning=reasoning, parameters={ "query": query, "content_type": content_type, "time_range": time_range, "max_results": max_results, }, response_time_ms=response_time, success=success, error_message=error_msg, response_size=len(result.encode("utf-8")), ) return result
• src/searxng_mcp/server.py:241-254 (schema)

  Input schema defined via Annotated types for the tool parameters: query, reasoning, content_type, time_range, max_results.
  query: Annotated[ str, "What you're looking for (e.g., 'Python async await examples', 'React hooks tutorial', 'Rust error handling patterns')", ], reasoning: Annotated[str, "Why you're searching for examples (required for analytics)"], content_type: Annotated[ Literal["code", "articles", "both"], "Type of content to find: 'code' for code examples, 'articles' for tutorials/blogs, 'both' for mixed results", ] = "both", time_range: Annotated[ Literal["day", "week", "month", "year", "all"], "How recent the content should be (use 'all' for best results, filter down if too many results)", ] = "all", max_results: Annotated[int, "How many results to return (1-10)"] = DEFAULT_MAX_RESULTS,
• src/searxng_mcp/search.py:34-79 (helper)

  SearxSearcher.search method called by search_examples tool to perform the actual SearXNG search.
  async def search( self, query: str, *, category: str = DEFAULT_CATEGORY, max_results: int = DEFAULT_MAX_RESULTS, time_range: str | None = None, ) -> list[SearchHit]: """Return up to *max_results* hits for *query* within *category*. Args: query: Search query string category: SearXNG category (general, it, etc.) max_results: Maximum number of results to return time_range: Optional time filter (day, week, month, year) """ limit = max(1, min(max_results, MAX_SEARCH_RESULTS)) params = { "q": query, "categories": category, "format": "json", "pageno": 1, } # Add time range filter if specified if time_range: params["time_range"] = time_range async with httpx.AsyncClient(timeout=self.timeout, headers=self._headers) as client: response = await client.get(self.base_url, params=params) response.raise_for_status() payload = response.json() hits: list[SearchHit] = [] for item in payload.get("results", [])[:limit]: title = ( item.get("title") or item.get("pretty_url") or item.get("url") or "Untitled" ).strip() url = item.get("url") or "" snippet = (item.get("content") or item.get("snippet") or "").strip() snippet = clamp_text(snippet, MAX_SNIPPET_CHARS, suffix="…") if snippet else "" hits.append(SearchHit(title=title, url=url, snippet=snippet)) return hits