list_grids

Instructions

Implementation Reference

• main.py:86-120 (handler)

  The handler function for the 'list_grids' tool. It calls the BitScale API GET /grids endpoint with optional search, page, and limit parameters, then returns JSON-formatted results.

  @mcp.tool()
  def list_grids(
      search: str = "",
      page: int = 1,
      limit: int = 20,
  ) -> str:
      """
      List all Grids in the workspace with their column definitions.
  
      Grids are spreadsheet-like tables in BitScale that hold data rows and
      enrichment/formula columns. Use this to discover available grids before
      running them.
  
      Args:
          search: Optional keyword to filter grids by name (case-insensitive
                  substring match). Example: "leads" to find lead-related grids.
          page:   Page number for pagination (1-based, default: 1).
          limit:  Results per page (default: 20, max: 100).
  
      Returns: paginated list of grids, each with id, name, description,
      row_count, column_count, created_at, updated_at, and columns array.
      The columns array contains only runnable columns (type: enrichment,
      formula, or merge) with their id (column UUID), name, type, and
      dependencies.
  
      Use the grid id from the results to call get_grid_details or run_grid.
      Note: the column UUIDs here are used for output_columns in run_grid.
      The input labels for run_grid are separate human-readable keys derived
      from the grid's API data source configuration.
      """
      params: dict = {"page": page, "limit": limit}
      if search:
          params["search"] = search
      data = _get("/grids", params=params)
      return json.dumps(data, indent=2)

• main.py:86-86 (registration)

  Registration of the list_grids function as an MCP tool using the @mcp.tool() decorator from FastMCP.

  @mcp.tool()

• main.py:87-91 (schema)

  Input schema/type definitions for list_grids: search (str), page (int, default 1), limit (int, default 20), returns str.

  def list_grids(
      search: str = "",
      page: int = 1,
      limit: int = 20,
  ) -> str:

• main.py:47-53 (helper)

  Helper function _get() used by list_grids to perform the authenticated GET request to the BitScale API.

  def _get(path: str, params: dict | None = None, timeout: int = 30) -> dict:
      """Perform an authenticated GET request against the BitScale API."""
      url = f"{BITSCALE_API_BASE}{path}"
      with httpx.Client(timeout=timeout) as client:
          response = client.get(url, headers=_headers(), params=params)
      response.raise_for_status()
      return response.json()

• main.py:34-44 (helper)

  Helper function _headers() that provides auth headers used by _get() which list_grids calls.

  def _headers() -> dict:
      """Return the auth headers required by the BitScale API."""
      if not API_KEY:
          raise RuntimeError(
              "BITSCALE_API_KEY environment variable is not set. "
              "Set it before starting the server."
          )
      return {
          "X-API-KEY": API_KEY,
          "Content-Type": "application/json",
      }