mcp-server-spreadsheet

Instructions

Implementation Reference

• src/mcp_server_spreadsheet/server.py:654-693 (handler)

  The describe_table tool handler function, which inspects the structure of a sheet in a spreadsheet.

  def describe_table(
      file: Annotated[str, Field(description="Path to the spreadsheet file")],
      sheet: Annotated[str | None, Field(description="Sheet name to describe. If omitted, describes all sheets in the workbook.")] = None,
      header_row: Annotated[int, Field(description="1-based row number containing column headers. Defaults to 1.")] = 1,
  ) -> list[dict] | dict:
      """Inspect the structure of a sheet treated as a database table.
  
      Returns column names, inferred data types (text, integer, number,
      boolean, date), total row count, and sample values from the first 3
      data rows. Use this before writing SQL queries to understand the
      available columns and their types.
  
      When sheet is omitted, returns a list of descriptions for all sheets.
      """
      wb = load_workbook(file)
      targets = [_resolve_sheet(wb, sheet)] if sheet else wb.worksheets
  
      results = []
      for ws in targets:
          headers, rows = _sheet_to_records(ws, header_row)
  
          if not headers:
              results.append({"sheet": ws.title, "columns": [], "row_count": 0, "sample": []})
              continue
  
          columns = []
          for col_idx, header in enumerate(headers):
              col_values = [row[col_idx] for row in rows]
              columns.append({"name": header, "type": _infer_describe_type(col_values)})
  
          sample = [dict(zip(headers, row)) for row in rows[:3]]
  
          results.append({
              "sheet": ws.title,
              "columns": columns,
              "row_count": len(rows),
              "sample": sample,
          })
  
      return results[0] if len(results) == 1 else results