autocomplete

Instructions

Implementation Reference

• mcp_server/tools.py:302-326 (handler)

  The actual implementation of the autocomplete tool handler. It uses @mcp.tool() decorator, takes a 'query' parameter with Pydantic Field description, makes an HTTP GET request to SearXNG's /autocompleter endpoint, and returns the JSON response. Returns an error dict on non-200 status.

  async def autocomplete(
      query: Annotated[str, Field(
          description="Partial query string to get suggestions for. Best results with 1-2 keywords (e.g., 'python async'). Single characters are too broad; full sentences return nothing.",
      )],
  ) -> str:
      """Get search query suggestions from SearXNG.
  
      Returns a list of autocomplete suggestions for the given partial query.
      Use this to discover relevant search terms before performing a full search.
  
      Best results come from 1-2 meaningful keywords (e.g., "python async").
      Single characters return overly broad suggestions; full sentences return none.
  
      Makes an external API call to the configured autocomplete backend (e.g., Bing, Google).
      Not suitable for full web search (use search tool) or engine discovery (use engine_info tool).
      """
      client = await _get_client()
      resp = await client.get(
          f"{SEARXNG_BASE_URL}/autocompleter",
          params={"q": query},
          timeout=10.0,
      )
      if resp.status_code != 200:
          return json.dumps({"error": f"Autocomplete failed with status {resp.status_code}"})
      return json.dumps(resp.json(), ensure_ascii=False)

• mcp_server/tools.py:294-301 (registration)

  The @mcp.tool() decorator that registers the autocomplete function as an MCP tool with annotations (readOnlyHint=True, destructiveHint=False, idempotentHint=True, openWorldHint=True).

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

• mcp_server/tools.py:303-306 (schema)

  Input parameter definition for autocomplete: 'query' is an Annotated[str, Field(...)] describing that it expects a partial query string with best results from 1-2 keywords.

      query: Annotated[str, Field(
          description="Partial query string to get suggestions for. Best results with 1-2 keywords (e.g., 'python async'). Single characters are too broad; full sentences return nothing.",
      )],
  ) -> str:

• tests/test_tools.py:24-50 (helper)

  Test fixture mocking the autocomplete response as a list of strings (['python tutorial', 'python download', 'python documentation']).

  @pytest.fixture
  def mock_search_response():
      return {
          "results": [
              {
                  "title": "Example Result",
                  "url": "https://example.com",
                  "content": "This is a test result.",
                  "engines": ["google", "bing"],
                  "score": 5.0,
                  "category": "general",
                  "parsed_url": ["https", "example.com"],
                  "positions": [1],
                  "template": "default.html",
              }
          ],
          "answers": ["42"],
          "corrections": [],
          "suggestions": ["example query"],
          "infoboxes": [],
          "unresponsive_engines": [],
          "number_of_results": 1,
      }
  
  
  @pytest.fixture
  def mock_autocomplete_response():