superset2/superset/mcp_service/README_SCHEMAS.md

Superset MCP Service: Tool Schemas Reference

This document provides a reference for the input and output schemas of all MCP tools in the Superset MCP service. All schemas are Pydantic v2 models with field descriptions for LLM/OpenAPI compatibility. All tool input and output is strongly typed and validated.

Dashboards

list_dashboards

Inputs:

• filters: Optional[List[DashboardFilter]] — List of filter objects
• search: Optional[str] — Free-text search string
• select_columns: Optional[List[str]] — Columns to select (overrides columns/keys)
• order_column: Optional[str] — Column to order results by
• order_direction: Optional[Literal['asc', 'desc']] — Order direction
• page: int — Page number (1-based)
• page_size: int — Number of items per page

Returns: DashboardList

• dashboards: List[DashboardListItem]
• count: int
• total_count: int
• page: int
• page_size: int
• total_pages: int
• has_previous: bool
• has_next: bool
• columns_requested: List[str]
• columns_loaded: List[str]
• filters_applied: List[Any]
• pagination: PaginationInfo
• timestamp: datetime

get_dashboard_info

Inputs:

• dashboard_id: int — Dashboard ID

Returns: DashboardInfo or DashboardError

get_dashboard_available_filters

Returns: DashboardAvailableFilters

• column_operators: Dict[str, Any] — Available filter operators and metadata for each column

Datasets

list_datasets

Inputs:

• filters: Optional[List[DatasetFilter]] — List of filter objects
• search: Optional[str] — Free-text search string
• select_columns: Optional[List[str]] — Columns to select (overrides columns/keys)
• order_column: Optional[str] — Column to order results by
• order_direction: Optional[Literal['asc', 'desc']] — Order direction
• page: int — Page number (1-based)
• page_size: int — Number of items per page

Returns: DatasetList

• datasets: List[DatasetListItem] (each includes columns and metrics)
• count: int
• total_count: int
• page: int
• page_size: int
• total_pages: int
• has_previous: bool
• has_next: bool
• columns_requested: List[str]
• columns_loaded: List[str]
• filters_applied: List[Any]
• pagination: PaginationInfo
• timestamp: datetime

get_dataset_info

Inputs:

• dataset_id: int — Dataset ID

Returns: DatasetInfo or DatasetError (now includes columns and metrics)

DatasetInfo fields (new):

• columns: List[TableColumnInfo] — List of columns with name, type, verbose name, etc.
• metrics: List[SqlMetricInfo] — List of metrics with name, expression, verbose name, etc.

TableColumnInfo

• column_name: str — Column name
• verbose_name: Optional[str] — Verbose name
• type: Optional[str] — Column type
• is_dttm: Optional[bool] — Is datetime column
• groupby: Optional[bool] — Is groupable
• filterable: Optional[bool] — Is filterable
• description: Optional[str] — Column description

SqlMetricInfo

• metric_name: str — Metric name
• verbose_name: Optional[str] — Verbose name
• expression: Optional[str] — SQL expression
• description: Optional[str] — Metric description

Note: All dataset list/info responses now include full column and metric metadata for each dataset.

get_dataset_available_filters

Returns: DatasetAvailableFilters

• column_operators: Dict[str, Any] — Available filter operators and metadata for each column

Charts

list_charts

Inputs:

• filters: Optional[List[ChartFilter]] — List of filter objects
• search: Optional[str] — Free-text search string
• select_columns: Optional[List[str]] — Columns to select (overrides columns/keys)
• order_column: Optional[str] — Column to order results by
• order_direction: Optional[Literal['asc', 'desc']] — Order direction
• page: int — Page number (1-based)
• page_size: int — Number of items per page

Returns: ChartList

• charts: List[ChartListItem]
• count: int
• total_count: int
• page: int
• page_size: int
• total_pages: int
• has_previous: bool
• has_next: bool
• columns_requested: List[str]
• columns_loaded: List[str]
• filters_applied: List[Any]
• pagination: PaginationInfo
• timestamp: datetime

get_chart_info

Inputs:

• chart_id: int — Chart ID

Returns: ChartInfo or ChartError

get_chart_available_filters

Returns: ChartAvailableFiltersResponse

• column_operators: Dict[str, Any] — Available filter operators and metadata for each column

create_chart

Inputs:

• slice_name: str — Chart name
• viz_type: str — Visualization type (e.g., echarts_timeseries_line, echarts_timeseries_bar, echarts_area, table)
• datasource_id: int — Dataset ID
• datasource_type: str — Datasource type (usually 'table')
• x_axis: str — Column name or SQL for x-axis (ECharts timeseries)
• metrics: List[str] — List of metric names to display
• groupby: Optional[List[str]] — Columns to group by (series)
• filters: Optional[List[Dict[str, Any]]] — List of filter objects
• row_limit: Optional[int] — Row limit
• stack: Optional[bool] — Stack series (ECharts option)
• area: Optional[bool] — Show area under line/bar (ECharts option)
• smooth: Optional[bool] — Smooth lines (ECharts option)
• show_value: Optional[bool] — Show values on chart (ECharts option)
• color_scheme: Optional[str] — Color scheme (ECharts option)
• legend_type: Optional[str] — Legend type (ECharts option)
• legend_orientation: Optional[str] — Legend orientation (ECharts option)
• tooltip_sorting: Optional[str] — Tooltip sorting (ECharts option)
• y_axis_format: Optional[str] — Y axis format (ECharts option)
• y_axis_bounds: Optional[List[float]] — Y axis bounds (ECharts option)
• x_axis_time_format: Optional[str] — X axis time format (ECharts option)
• rich_tooltip: Optional[bool] — Enable rich tooltip (ECharts option)
• extra_options: Optional[Dict[str, Any]] — Additional ECharts options not yet modeled (future-proof)

Model Relationships

flowchart TD
    subgraph Schema Types
        A["DashboardListItem"]
        B["DatasetListItem"]
        C["ChartListItem"]
        D["UserInfo"]
        E["TagInfo"]
        F["RoleInfo"]
    end
    A -- owners --> D
    A -- tags --> E
    A -- roles --> F
    B -- owners --> D
    B -- tags --> E
    C -- owners --> D
    C -- tags --> E

ModelListTool and Schema Consistency

All list tools use the ModelListTool abstraction, which enforces:

• Consistent parameter order and types
• Strongly-typed Pydantic input/output models
• LLM/OpenAPI-friendly field names