Web Research Assistant

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

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

  The @mcp.tool()-decorated handler function implementing the 'search_examples' tool logic. Enhances query based on content_type ('code', 'articles', 'both'), searches using SearxSearcher in 'it' category, formats results with source labels (GitHub, Stack Overflow, Article), detects limited diversity, and tracks usage.
  @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-255 (schema)

  Input schema defined via type hints and Annotated metadata in the function signature, including parameters for query, reasoning, content_type, time_range, and 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, ) -> str:
• src/searxng_mcp/search.py:26-79 (helper)

  SearxSearcher class providing the underlying search functionality used by search_examples tool (search method lines 34-79).
  class SearxSearcher: """Minimal async client for the local SearXNG instance.""" def __init__(self, base_url: str = SEARX_BASE_URL, timeout: float = HTTP_TIMEOUT) -> None: self.base_url = base_url self.timeout = timeout self._headers = {"User-Agent": USER_AGENT, "Accept": "application/json"} 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