feat(mcp): add unified get_schema tool for schema discovery (#36458)

Co-authored-by: Claude Opus 4.5 <[email protected]>

Author: aminghadersohi

superset/mcp_service/CLAUDE.md

@@ -176,7 +176,7 @@ The `mcp_core.py` module provides reusable patterns:
 
 - **`ModelListCore`**: For listing resources (dashboards, charts, datasets)
 - **`ModelGetInfoCore`**: For getting resource details by ID/UUID
-- **`ModelGetAvailableFiltersCore`**: For retrieving filterable columns
+- **`ModelGetSchemaCore`**: For retrieving comprehensive schema metadata (columns, filters, sortable columns)
 
 **Example**:
 ```python
@@ -502,8 +502,8 @@ def my_function(param: Optional[str] = None) -> Optional[int]:
 **Solution**: Use DAO classes (ChartDAO, DashboardDAO, etc.).
 
 ### 7. ❌ Not Using Core Classes
-**Problem**: Duplicating list/get_info/filter logic across tools.
-**Solution**: Use ModelListCore, ModelGetInfoCore, ModelGetAvailableFiltersCore.
+**Problem**: Duplicating list/get_info/schema logic across tools.
+**Solution**: Use ModelListCore, ModelGetInfoCore, ModelGetSchemaCore.
 
 ### 8. ❌ Missing Apache License Headers
 **Problem**: CI fails on license check.

superset/mcp_service/app.py

@@ -51,21 +51,18 @@ def get_default_instructions(branding: str = "Apache Superset") -> str:
 Dashboard Management:
 - list_dashboards: List dashboards with advanced filters (1-based pagination)
 - get_dashboard_info: Get detailed dashboard information by ID
-- get_dashboard_available_filters: List available dashboard filter fields/operators
 - generate_dashboard: Automatically create a dashboard from datasets with AI
 - add_chart_to_existing_dashboard: Add a chart to an existing dashboard
 
 Dataset Management:
 - list_datasets: List datasets with advanced filters (1-based pagination)
 - get_dataset_info: Get detailed dataset information by ID
-- get_dataset_available_filters: List available dataset filter fields/operators
 
 Chart Management:
 - list_charts: List charts with advanced filters (1-based pagination)
 - get_chart_info: Get detailed chart information by ID
 - get_chart_preview: Get a visual preview of a chart with image URL
 - get_chart_data: Get underlying chart data in text-friendly format
-- get_chart_available_filters: List available chart filter fields/operators
 - generate_chart: Create a new chart with AI assistance
 - update_chart: Update existing chart configuration
 - update_chart_preview: Update chart and get preview in one operation
@@ -77,6 +74,9 @@ def get_default_instructions(branding: str = "Apache Superset") -> str:
 Explore & Analysis:
 - generate_explore_link: Create pre-configured explore URL with dataset/metrics/filters
 
+Schema Discovery:
+- get_schema: Get schema metadata for chart/dataset/dashboard (columns, filters)
+
 System Information:
 - get_instance_info: Get instance-wide statistics and metadata
 - health_check: Simple health check tool (takes NO parameters, call without arguments)
@@ -125,7 +125,8 @@ def get_default_instructions(branding: str = "Apache Superset") -> str:
 
 General usage tips:
 - All listing tools use 1-based pagination (first page is 1)
-- Use 'filters' parameter for advanced queries (see *_available_filters tools)
+- Use get_schema to discover filterable columns, sortable columns, and default columns
+- Use 'filters' parameter for advanced queries with filter columns from get_schema
 - IDs can be integer or UUID format where supported
 - All tools return structured, Pydantic-typed responses
 - Chart previews are served as PNG images via custom screenshot endpoints
@@ -289,7 +290,6 @@ def create_mcp_app(
 )
 from superset.mcp_service.chart.tool import (  # noqa: F401, E402
     generate_chart,
-    get_chart_available_filters,
     get_chart_data,
     get_chart_info,
     get_chart_preview,
@@ -300,12 +300,10 @@ def create_mcp_app(
 from superset.mcp_service.dashboard.tool import (  # noqa: F401, E402
     add_chart_to_existing_dashboard,
     generate_dashboard,
-    get_dashboard_available_filters,
     get_dashboard_info,
     list_dashboards,
 )
 from superset.mcp_service.dataset.tool import (  # noqa: F401, E402
-    get_dataset_available_filters,
     get_dataset_info,
     list_datasets,
 )
@@ -322,6 +320,7 @@ def create_mcp_app(
 )
 from superset.mcp_service.system.tool import (  # noqa: F401, E402
     get_instance_info,
+    get_schema,
     health_check,
 )
 

superset/mcp_service/chart/schemas.py

@@ -131,25 +131,6 @@ def _filter_fields_by_context(self, serializer: Any, info: Any) -> Dict[str, Any
         return data
 
 
-class GetChartAvailableFiltersRequest(BaseModel):
-    """
-    Request schema for get_chart_available_filters tool.
-
-    Currently has no parameters but provides consistent API for future extensibility.
-    """
-
-    model_config = ConfigDict(
-        extra="forbid",
-        str_strip_whitespace=True,
-    )
-
-
-class ChartAvailableFiltersResponse(BaseModel):
-    column_operators: Dict[str, Any] = Field(
-        ..., description="Available filter operators and metadata for each column"
-    )
-
-
 class ChartError(BaseModel):
     error: str = Field(..., description="Error message")
     error_type: str = Field(..., description="Type of error")
@@ -288,13 +269,13 @@ class ChartFilter(ColumnOperator):
         "datasource_name",
     ] = Field(
         ...,
-        description="Column to filter on. See get_chart_available_filters for "
-        "allowed values.",
+        description="Column to filter on. Use get_schema(model_type='chart') for "
+        "available filter columns.",
     )
     opr: ColumnOperatorEnum = Field(
         ...,
-        description="Operator to use. See get_chart_available_filters for "
-        "allowed values.",
+        description="Operator to use. Use get_schema(model_type='chart') for "
+        "available operators.",
     )
     value: str | int | float | bool | List[str | int | float | bool] = Field(
         ..., description="Value to filter by (type depends on col and opr)"
@@ -310,8 +291,22 @@ class ChartList(BaseModel):
     total_pages: int
     has_previous: bool
     has_next: bool
-    columns_requested: List[str] | None = None
-    columns_loaded: List[str] | None = None
+    columns_requested: List[str] = Field(
+        default_factory=list,
+        description="Requested columns for the response",
+    )
+    columns_loaded: List[str] = Field(
+        default_factory=list,
+        description="Columns that were actually loaded for each chart",
+    )
+    columns_available: List[str] = Field(
+        default_factory=list,
+        description="All columns available for selection via select_columns parameter",
+    )
+    sortable_columns: List[str] = Field(
+        default_factory=list,
+        description="Columns that can be used with order_column parameter",
+    )
     filters_applied: List[ChartFilter] = Field(
         default_factory=list,
         description="List of advanced filter dicts applied to the query.",
@@ -749,18 +744,7 @@ class ListChartsRequest(MetadataCacheControl):
     select_columns: Annotated[
         List[str],
         Field(
-            default_factory=lambda: [
-                "id",
-                "slice_name",
-                "viz_type",
-                "datasource_name",
-                "description",
-                "changed_by_name",
-                "created_by_name",
-                "changed_on",
-                "created_on",
-                "uuid",
-            ],
+            default_factory=list,
             description="List of columns to select. Defaults to common columns if not "
             "specified.",
         ),

superset/mcp_service/chart/tool/__init__.py

@@ -16,7 +16,6 @@
 # under the License.
 
 from .generate_chart import generate_chart
-from .get_chart_available_filters import get_chart_available_filters
 from .get_chart_data import get_chart_data
 from .get_chart_info import get_chart_info
 from .get_chart_preview import get_chart_preview
@@ -27,7 +26,6 @@
 __all__ = [
     "list_charts",
     "get_chart_info",
-    "get_chart_available_filters",
     "generate_chart",
     "update_chart",
     "update_chart_preview",

superset/mcp_service/chart/tool/get_chart_available_filters.py

@@ -41,17 +41,12 @@
 
 logger = logging.getLogger(__name__)
 
+# Minimal defaults for reduced token usage - users can request more via select_columns
 DEFAULT_CHART_COLUMNS = [
     "id",
     "slice_name",
     "viz_type",
     "uuid",
-    "datasource_name",
-    "description",
-    "changed_by_name",
-    "created_by_name",
-    "changed_on",
-    "created_on",
 ]
 
 SORTABLE_CHART_COLUMNS = [
@@ -93,6 +88,14 @@ async def list_charts(request: ListChartsRequest, ctx: Context) -> ChartList:
     )
 
     from superset.daos.chart import ChartDAO
+    from superset.mcp_service.common.schema_discovery import (
+        CHART_SORTABLE_COLUMNS,
+        get_all_column_names,
+        get_chart_columns,
+    )
+
+    # Get all column names dynamically from the model
+    all_columns = get_all_column_names(get_chart_columns())
 
     def _serialize_chart(
         obj: "Slice | None", cols: list[str] | None
@@ -112,6 +115,8 @@ def _serialize_chart(
         ],
         list_field_name="charts",
         output_list_schema=ChartList,
+        all_columns=all_columns,
+        sortable_columns=CHART_SORTABLE_COLUMNS,
         logger=logger,
     )
 
@@ -132,20 +137,17 @@ def _serialize_chart(
             % (count, total_pages)
         )
 
-        # Apply field filtering via serialization context if select_columns specified
-        # This triggers ChartInfo._filter_fields_by_context for each chart
-        if request.select_columns:
-            await ctx.debug(
-                "Applying field filtering via serialization context: select_columns=%s"
-                % (request.select_columns,)
-            )
-            # Return dict with context - FastMCP will serialize it
-            return result.model_dump(
-                mode="json", context={"select_columns": request.select_columns}
-            )
-
-        # No filtering - return full result as dict
-        return result.model_dump(mode="json")
+        # Apply field filtering via serialization context
+        # Use columns_requested from result (already resolved by ModelListCore)
+        columns_to_filter = result.columns_requested
+        await ctx.debug(
+            "Applying field filtering via serialization context: select_columns=%s"
+            % (columns_to_filter,)
+        )
+        filtered = result.model_dump(
+            mode="json", context={"select_columns": columns_to_filter}
+        )
+        return ChartList.model_validate(filtered)
     except Exception as e:
         await ctx.error("Failed to list charts: %s" % (str(e),))
         raise