engine_info

Instructions

Implementation Reference

• mcp_server/tools.py:334-359 (handler)

  The engine_info MCP tool handler function. It fetches engine info via fetch_engine_info() with a 5-minute cache (using _engine_info_cache and _engine_info_cache_ts globals). Returns JSON string with categories, engines, and category_engines.

  @mcp.tool(
      annotations=ToolAnnotations(
          readOnlyHint=True,
          destructiveHint=False,
          idempotentHint=True,
          openWorldHint=False,
      )
  )
  async def engine_info() -> str:
      """Get available search engines and categories from the SearXNG instance.
  
      Returns the list of enabled engines grouped by category.
      Use this to discover what engines and categories are available
      before calling search with specific engines or categories filters.
  
      Response is cached for 5 minutes. Does not perform any web search — use the search tool for that.
      """
      global _engine_info_cache, _engine_info_cache_ts
      now = time.monotonic()
      if _engine_info_cache is not None and now - _engine_info_cache_ts < ENGINE_INFO_CACHE_TTL:
          return json.dumps(_engine_info_cache, ensure_ascii=False)
  
      info = await fetch_engine_info()
      _engine_info_cache = info
      _engine_info_cache_ts = now
      return json.dumps(info, ensure_ascii=False)

• mcp_server/tools.py:334-341 (schema)

  The tool annotation/decorator configuration for engine_info. Uses @mcp.tool with readOnlyHint=True, destructiveHint=False, idempotentHint=True, openWorldHint=False.

  @mcp.tool(
      annotations=ToolAnnotations(
          readOnlyHint=True,
          destructiveHint=False,
          idempotentHint=True,
          openWorldHint=False,
      )
  )

• mcp_server/tools.py:334-341 (registration)

  The tool is registered via the @mcp.tool() decorator on the engine_info async function (line 334). The mcp instance is FastMCP defined on line 16-22.

  @mcp.tool(
      annotations=ToolAnnotations(
          readOnlyHint=True,
          destructiveHint=False,
          idempotentHint=True,
          openWorldHint=False,
      )
  )

• mcp_server/tools.py:65-112 (helper)

  fetch_engine_info() helper function that fetches available engines and categories from the SearXNG /config API. Handles both list and dict category formats, filters enabled engines, and returns a dict with categories, engines, and category_engines. Has a fallback with hardcoded categories on error.

  async def fetch_engine_info() -> dict:
      """Fetch available engines and categories from SearXNG config API."""
      try:
          client = await _get_client()
          resp = await client.get(
              f"{SEARXNG_BASE_URL}/config", timeout=10.0
          )
          if resp.status_code == 200:
              data = resp.json()
              raw_categories = data.get("categories", [])
              if isinstance(raw_categories, list):
                  categories = raw_categories
              elif isinstance(raw_categories, dict):
                  categories = list(raw_categories.keys())
              else:
                  categories = []
  
              engines = []
              category_engines: dict[str, list[str]] = {}
              for e in data.get("engines", []):
                  if not e.get("enabled", True):
                      continue
                  name = e["name"]
                  engines.append(name)
                  for cat in e.get("categories", []):
                      category_engines.setdefault(cat, []).append(name)
  
              return {
                  "categories": categories,
                  "engines": engines,
                  "category_engines": category_engines,
              }
      except Exception:
          pass
      # Fallback from SearXNG 2024.12 — update if upstream categories change
      return {
          "categories": [
              "general", "images", "videos", "news", "map",
              "music", "it", "science", "files", "social media",
              "web", "apps", "books", "packages", "repos",
              "software wikis", "scientific publications", "q&a",
              "shopping", "movies", "translate", "radio", "lyrics",
              "currency", "weather", "other", "dictionaries",
              "define", "icons", "cargo", "wikimedia",
          ],
          "engines": [],
          "category_engines": {},
      }

• mcp_server/tools.py:329-331 (helper)

  Global cache variables for engine_info: _engine_info_cache (dict), _engine_info_cache_ts (float), and ENGINE_INFO_CACHE_TTL=300 (5 minutes).

  _engine_info_cache: dict | None = None
  _engine_info_cache_ts: float = 0
  ENGINE_INFO_CACHE_TTL = 300