get_query_suggestions

Instructions

Implementation Reference

• src/pihole_mcp/tools/queries.py:42-45 (handler)

  The async function 'get_query_suggestions' implements the tool handler. It calls client.get('/queries/suggestions') to fetch available filter values (domains, clients, upstreams, types, statuses) for the query log.

  @mcp.tool()
  async def get_query_suggestions() -> dict:
      """Get available filter values for the query log (domains, clients, upstreams, types, statuses)."""
      return await client.get("/queries/suggestions")

• src/pihole_mcp/tools/queries.py:6-47 (registration)

  The 'register' function registers tool handlers (including get_query_suggestions) with the FastMCP instance via @mcp.tool() decorator.

  def register(mcp: FastMCP, client: PiholeClient) -> int:
      @mcp.tool()
      async def get_query_log(
          length: int = 100,
          from_ts: int | None = None,
          until_ts: int | None = None,
          domain: str | None = None,
          client_ip: str | None = None,
          upstream: str | None = None,
          cursor: str | None = None,
      ) -> dict:
          """Fetch recent DNS queries with optional filters.
  
          Filters:
          - length: number of queries (default 100)
          - from_ts / until_ts: Unix timestamps
          - domain: exact or wildcard (*) domain match
          - client_ip: exact or wildcard (*) client IP match
          - upstream: one of 'cache', 'blocklist', 'permitted'
          - cursor: pagination cursor from previous response
          """
          params: dict = {"length": length}
          if from_ts is not None:
              params["from"] = from_ts
          if until_ts is not None:
              params["until"] = until_ts
          if domain:
              params["domain"] = domain
          if client_ip:
              params["client"] = client_ip
          if upstream:
              params["upstream"] = upstream
          if cursor:
              params["cursor"] = cursor
          return await client.get("/queries", params=params)
  
      @mcp.tool()
      async def get_query_suggestions() -> dict:
          """Get available filter values for the query log (domains, clients, upstreams, types, statuses)."""
          return await client.get("/queries/suggestions")
  
      return 2

• src/pihole_mcp/tools/__init__.py:14-19 (registration)

  The 'register_all' function iterates over modules including 'queries' and calls each module's register() function to register all tools with the MCP server.

  def register_all(mcp: FastMCP, client: PiholeClient) -> int:
      """Register every tool module against the FastMCP instance. Returns tool count."""
      count = 0
      for module in (stats, queries, blocking, domains, local_dns, maintenance):
          count += module.register(mcp, client)
      return count