engine_info

Instructions

Implementation Reference

• mcp_server/tools.py:331-356 (handler)

  The actual MCP tool handler function for engine_info. It is decorated with @mcp.tool(), uses a cache (5 min TTL), and calls fetch_engine_info() to get engines/categories from SearXNG config API.

  @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:65-112 (helper)

  Helper that fetches engine/category info from the SearXNG /config API. Falls back to a hardcoded list of categories if the API call fails.

  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:331-356 (schema)

  The engine_info tool has no input parameters and returns a JSON string. Tool annotations mark it as read-only, non-destructive, and idempotent.

  @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:331-338 (registration)

  The @mcp.tool() decorator registers engine_info as an MCP tool on the FastMCP instance (line 16: mcp = FastMCP(...)).

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

• mcp_server/tools.py:326-328 (helper)

  Module-level cache variables for the engine_info tool. The cache TTL is 300 seconds (5 minutes).

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