Web Research Assistant

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

• src/searxng_mcp/server.py:771-950 (handler)

  The core handler function for the 'translate_error' tool. Parses input error using ErrorParser, constructs a search query, performs SearxNG search in 'it' category, filters/prioritizes Stack Overflow results, formats output with parsed info, search query, and top solutions with vote estimates.
  async def translate_error( error_message: Annotated[str, "The error message or stack trace to investigate"], reasoning: Annotated[str, "Why you're investigating this error (required for analytics)"], language: Annotated[str | None, "Programming language (auto-detected if not provided)"] = None, framework: Annotated[ str | None, "Framework context (e.g., 'React', 'FastAPI', 'Django')" ] = None, max_results: Annotated[int, "Number of solutions to return (1-10)"] = 5, ) -> str: """ Find solutions for error messages and stack traces from Stack Overflow and GitHub. Takes an error message or stack trace and finds relevant solutions with code examples. Automatically detects language and framework, extracts key error information, and searches for the best solutions ranked by votes and relevance. Perfect for: - Debugging production errors - Understanding cryptic error messages - Finding working code fixes - Learning from similar issues Examples: - translate_error("TypeError: Cannot read property 'map' of undefined", reasoning="Debugging React app crash") - translate_error("CORS policy: No 'Access-Control-Allow-Origin' header", reasoning="Fixing API integration", framework="FastAPI") - translate_error("error[E0382]: borrow of moved value", reasoning="Learning Rust ownership", language="rust") """ start_time = time.time() success = False error_msg = None result = "" parsed = None try: max_results = max(1, min(max_results, 10)) # Parse the error message parsed = error_parser.parse(error_message, language=language, framework=framework) # Build search query search_query = error_parser.build_search_query(parsed) # Search for solutions (request more to allow for filtering) hits = await searcher.search( search_query, category="it", max_results=max_results * 2, # Get extra results for filtering ) # Filter and prioritize results if hits: # Filter out irrelevant sources irrelevant_domains = { "hub.docker.com", "crates.io", "npmjs.com", "pypi.org", "pkg.go.dev", } filtered_hits = [ hit for hit in hits if not any(domain in hit.url.lower() for domain in irrelevant_domains) ] # Prioritize Stack Overflow results so_hits = [hit for hit in filtered_hits if "stackoverflow.com" in hit.url] other_hits = [hit for hit in filtered_hits if "stackoverflow.com" not in hit.url] # Combine: Stack Overflow first, then others hits = (so_hits + other_hits)[:max_results] if not hits: result = ( f"No solutions found for this error.\n\n" f"Parsed Error Info:\n" f"- Type: {parsed.error_type}\n" f"- Language: {parsed.language or 'Unknown'}\n" f"- Framework: {parsed.framework or 'None detected'}\n\n" f"Try:\n" f"- Providing more context with language/framework parameters\n" f"- Searching for just the error type: {parsed.error_type}\n" f"- Using web_search with broader terms" ) else: # Format results lines = [ "Error Translation Results", "═" * 70, "", "📋 Parsed Error Information:", f" Error Type: {parsed.error_type}", ] if parsed.language: lines.append(f" Language: {parsed.language.title()}") if parsed.framework: lines.append(f" Framework: {parsed.framework.title()}") if parsed.file_path: location = f"{parsed.file_path}" if parsed.line_number: location += f":{parsed.line_number}" lines.append(f" Location: {location}") lines.extend( [ "", f"🔍 Search Query: {search_query}", "", "💡 Top Solutions (Stack Overflow prioritized):", "─" * 70, "", ] ) for idx, hit in enumerate(hits, 1): # Try to extract vote count from snippet (if available) votes = "N/A" if hit.snippet: vote_match = re.search(r"(\d+)\s*votes?", hit.snippet, re.IGNORECASE) if vote_match: votes = vote_match.group(1) # Check if it's a Stack Overflow link is_so = "stackoverflow.com" in hit.url source_icon = "[SO]" if is_so else "[Web]" lines.append(f"{idx}. {source_icon} {hit.title}") if votes != "N/A": lines.append(f" Votes: {votes}") lines.append(f" {hit.url}") if hit.snippet: # Clean and truncate snippet snippet = hit.snippet.replace("\n", " ").strip() if len(snippet) > 200: snippet = snippet[:200] + "..." lines.append(f" {snippet}") lines.append("") lines.extend( [ "─" * 70, "", "💡 Tips:", "- Check accepted answers (marked with ✓) first", "- Look for solutions with high vote counts", "- Verify the solution matches your exact error", "- Use crawl_url to get full answer details", ] ) result = clamp_text("\n".join(lines), MAX_RESPONSE_CHARS) success = True except Exception as exc: # noqa: BLE001 error_msg = str(exc) result = f"Error translation failed: {exc}\n\nTry simplifying the error message or provide language/framework context." finally: # Track usage response_time = (time.time() - start_time) * 1000 tracker.track_usage( tool_name="translate_error", reasoning=reasoning, parameters={ "error_type": parsed.error_type if parsed else "unknown", "language": language or (parsed.language if parsed else None), "framework": framework or (parsed.framework if parsed else None), "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/errors.py:22-329 (helper)

  ErrorParser class provides parsing logic for error messages, including language/framework detection via regex patterns, error type extraction, location parsing, key terms extraction, and building optimized search queries for the translate_error tool.
  class ErrorParser: """Parses error messages and stack traces to extract key information.""" # Language detection patterns (order matters - most specific first) LANGUAGE_PATTERNS = { "rust": [ r"error\[E\d{4}\]:", r"cannot borrow", r"--> .+\.rs:\d+:\d+", ], "typescript": [ r"at .+\.tsx?:\d+:\d+", r"\.tsx?:", r"TS\d{4}:", ], "javascript": [ r"at .+\.jsx?:\d+:\d+", r"\.jsx?:", r"node_modules", r"Cannot read property", r"is not defined", ], "python": [ r"File \"(.+)\.py\"", r"Traceback \(most recent call last\)", r"(ImportError|AttributeError|ModuleNotFoundError)", ], "java": [ r"at .+\.java:\d+", r"Exception in thread", r"(NullPointerException|IllegalArgumentException)", ], "go": [ r"panic:", r"goroutine \d+", r".+\.go:\d+", ], } # Framework detection patterns FRAMEWORK_PATTERNS = { "react": [r"react", r"jsx", r"useState", r"useEffect"], "vue": [r"vue", r"@vue", r"composition-api"], "angular": [r"angular", r"@angular", r"ngOnInit"], "django": [r"django", r"django\."], "flask": [r"flask", r"werkzeug"], "fastapi": [r"fastapi", r"pydantic", r"starlette"], "express": [r"express", r"app\.get", r"app\.post"], "nextjs": [r"next", r"getServerSideProps", r"getStaticProps"], } # Common error patterns (checked in order - most specific first) ERROR_TYPE_PATTERNS = { "python": { "AttributeError": r"AttributeError: '(.+)' object has no attribute '(.+)'", "TypeError": r"TypeError: (.+)", "ImportError": r"(ImportError|ModuleNotFoundError): (.+)", "ValueError": r"ValueError: (.+)", "KeyError": r"KeyError: (.+)", }, "javascript": { # Web-specific errors (check first - most specific) "CORS Error": r"CORS policy|Access-Control-Allow-Origin|No.*Access-Control", "Fetch Error": r"fetch.*failed|Failed to fetch|NetworkError", "Cannot read property": r"Cannot read propert(?:y|ies) ['\"](.+?)['\"] of", "undefined is not": r"undefined is not (a function|an object)", "null is not": r"null is not (a function|an object)", # Standard errors (check after specific ones) "TypeError": r"TypeError: (.+)", "ReferenceError": r"ReferenceError: (.+)", "SyntaxError": r"SyntaxError: (.+)", "RangeError": r"RangeError: (.+)", }, "typescript": { "CORS Error": r"CORS policy|Access-Control-Allow-Origin", "Fetch Error": r"fetch.*failed|Failed to fetch", "Cannot read property": r"Cannot read propert(?:y|ies) ['\"](.+?)['\"] of", "TypeError": r"TypeError: (.+)", "ReferenceError": r"ReferenceError: (.+)", "SyntaxError": r"SyntaxError: (.+)", }, "rust": { "borrow error": r"borrow of moved value", "cannot borrow": r"cannot borrow", "lifetime error": r"lifetime (.+) may not live long enough", "type mismatch": r"expected (.+), found (.+)", "E0382": r"error\[E0382\]", "E0502": r"error\[E0502\]", "E0308": r"error\[E0308\]", }, } def parse( self, error_message: str, language: str | None = None, framework: str | None = None, ) -> ParsedError: """ Parse an error message to extract key information. Args: error_message: The error text or stack trace language: Programming language (auto-detected if None) framework: Framework name (auto-detected if None) Returns: ParsedError with extracted information """ # Detect language if not provided if not language: language = self._detect_language(error_message) # Detect framework if not provided if not framework: framework = self._detect_framework(error_message) # Extract error type error_type = self._extract_error_type(error_message, language) # Extract file path and line number file_path, line_number = self._extract_location(error_message) # Extract key terms key_terms = self._extract_key_terms(error_message, error_type) # Clean message message = self._clean_message(error_message) return ParsedError( error_type=error_type or "Unknown Error", message=message, language=language, framework=framework, file_path=file_path, line_number=line_number, key_terms=key_terms, ) def _detect_language(self, text: str) -> str | None: """Detect programming language from error message.""" scores = {} for lang, patterns in self.LANGUAGE_PATTERNS.items(): score = sum(1 for pattern in patterns if re.search(pattern, text, re.IGNORECASE)) if score > 0: scores[lang] = score if scores: return max(scores, key=scores.get) return None def _detect_framework(self, text: str) -> str | None: """Detect framework from error message.""" text_lower = text.lower() for framework, patterns in self.FRAMEWORK_PATTERNS.items(): if any(re.search(pattern, text_lower) for pattern in patterns): return framework return None def _extract_error_type(self, text: str, language: str | None) -> str | None: """Extract the error type/name.""" # Check for common web errors first (language-agnostic) web_error_patterns = { "CORS Error": r"CORS policy|Access-Control-Allow-Origin|No.*Access-Control", "Fetch Error": r"fetch.*failed|Failed to fetch|NetworkError", "Cannot read property": r"Cannot read propert(?:y|ies) ['\"](.+?)['\"] of", } for error_name, pattern in web_error_patterns.items(): if re.search(pattern, text, re.IGNORECASE): return error_name # Language-specific extraction if language is detected if language and language in self.ERROR_TYPE_PATTERNS: for error_name, pattern in self.ERROR_TYPE_PATTERNS[language].items(): if re.search(pattern, text, re.IGNORECASE): return error_name # Generic error type extraction as fallback match = re.search(r"([\w]+Error|[\w]+Exception):", text) if match: return match.group(1) return None def _extract_location(self, text: str) -> tuple[str | None, int | None]: """Extract file path and line number.""" # Python format: File "path.py", line 123 match = re.search(r'File "(.+?)", line (\d+)', text) if match: return match.group(1), int(match.group(2)) # JavaScript/TypeScript format: at path.js:123:45 match = re.search(r"at (.+?):(\d+):\d+", text) if match: return match.group(1), int(match.group(2)) # Rust format: --> path.rs:123:45 match = re.search(r"--> (.+?):(\d+):\d+", text) if match: return match.group(1), int(match.group(2)) return None, None def _extract_key_terms(self, text: str, error_type: str | None) -> list[str]: """Extract key terms for searching.""" terms = set() # Use set to avoid duplicates # Important web/tech terms to always capture important_terms = [ "CORS", "cors", "fetch", "async", "await", "Promise", "undefined", "null", "map", "filter", "reduce", "Access-Control-Allow-Origin", "XMLHttpRequest", "module", "import", "export", "require", ] # Extract important terms first text_lower = text.lower() for term in important_terms: if term.lower() in text_lower: terms.add(term) if len(terms) >= 3: # Limit important terms to 3 break # Extract quoted strings (often property names or specific values) quoted = re.findall(r"'([^']+)'|\"([^\"]+)\"", text) for match in quoted: term = match[0] or match[1] # Keep short important terms, ignore paths if term and "/" not in term and "\\" not in term: # Allow short terms for property names like "map", "id", etc. if len(term) <= 15: # Reasonable property name length if not error_type or term.lower() != error_type.lower(): terms.add(term) if len(terms) >= 5: break # Extract technical terms (CamelCase, snake_case) technical = re.findall(r"\b[A-Z][a-z]+(?:[A-Z][a-z]+)+\b|\b\w+_\w+\b", text) # Don't exclude undefined/null - they're useful search terms for term in technical: if not error_type or term != error_type: terms.add(term) if len(terms) >= 5: break return list(terms)[:5] # Return max 5 unique key terms def _clean_message(self, text: str) -> str: """Clean and extract the core error message.""" # Try to find the main error line lines = text.strip().split("\n") # Look for the error line (usually contains "Error:" or "Exception:") for line in reversed(lines): if re.search(r"(Error|Exception):", line): return line.strip() # If no error line found, return first non-empty line for line in lines: if line.strip(): return line.strip() return text.strip() def build_search_query(self, parsed: ParsedError) -> str: """Build an optimized search query from parsed error.""" parts = [] # Add language if parsed.language: parts.append(parsed.language) # Add framework if parsed.framework: parts.append(parsed.framework) # Add error type if parsed.error_type and parsed.error_type != "Unknown Error": parts.append(parsed.error_type) # Add key terms (limit to avoid overly specific queries) parts.extend(parsed.key_terms[:2]) # Build query - don't use site filter as SearXNG handles this better # with its category-based engine selection query = " ".join(parts) # Add "error" or "fix" to help guide results if query: # Only add if we have content query += " error fix" return query
• src/searxng_mcp/server.py:771-771 (registration)

  The @mcp.tool() decorator registers the translate_error function as an MCP tool.
  async def translate_error(
• src/searxng_mcp/server.py:772-778 (schema)

  Input schema defined via Annotated types in the function signature, including error_message (required str), reasoning (required str), optional language/framework strs, and max_results int (default 5). Output is str.
  error_message: Annotated[str, "The error message or stack trace to investigate"], reasoning: Annotated[str, "Why you're investigating this error (required for analytics)"], language: Annotated[str | None, "Programming language (auto-detected if not provided)"] = None, framework: Annotated[ str | None, "Framework context (e.g., 'React', 'FastAPI', 'Django')" ] = None, max_results: Annotated[int, "Number of solutions to return (1-10)"] = 5,
• src/searxng_mcp/errors.py:9-20 (helper)

  ParsedError dataclass holds the structured results from ErrorParser.parse(), used internally by the translate_error handler.
  @dataclass(slots=True) class ParsedError: """Represents a parsed error message.""" error_type: str message: str language: str | None framework: str | None file_path: str | None line_number: int | None key_terms: list[str]