geido commented on code in PR #33976: URL: https://github.com/apache/superset/pull/33976#discussion_r2195073367
########## superset/mcp_service/README_SCHEMAS.md: ########## @@ -0,0 +1,477 @@ +# Superset MCP Service: Tool Schemas Reference + +This document provides a reference for the input and output parameters of all MCP tools in the Superset MCP service. Each section lists the tool name, its input parameters (with type), and its output schema. + +## Dashboards + +### list_dashboards + +**Inputs:** +- `filters`: `Optional[List[DashboardFilter]]` — List of filter objects +- `columns`: `Optional[List[str]]` — Columns to include in the response +- `keys`: `Optional[List[str]]` — Keys to include in the response +- `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 +- `select_columns`: `Optional[List[str]]` — Columns to select (overrides columns/keys) +- `search`: `Optional[str]` — Free-text search string + +**Returns:** `DashboardListResponse` +- `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`: `Dict[str, Any]` +- `pagination`: `PaginationInfo` +- `timestamp`: `datetime` + +### list_dashboards_simple + +**Inputs:** +- `filters`: `Optional[DashboardSimpleFilters]` — Simple filter object +- `order_column`: `Optional[str]` — Column to order results by +- `order_direction`: `Literal['asc', 'desc']` — Order direction +- `page`: `int` — Page number (1-based) +- `page_size`: `int` — Number of items per page +- `search`: `Optional[str]` — Free-text search string + +**Returns:** `DashboardListResponse` (see above) + +### get_dashboard_info + +**Inputs:** +- `dashboard_id`: `int` — Dashboard ID Review Comment: LLMs are known to have some issues with handling IDs. Would using the slug instead of an ID be more LLM-friendly? ########## superset/mcp_service/README_ARCHITECTURE.md: ########## @@ -0,0 +1,140 @@ +# Superset MCP Service Architecture + +**⚠️ The Superset MCP service is under active development and not yet complete. Functionality, APIs, and tool coverage are evolving rapidly. See [SIP-171](https://github.com/apache/superset/issues/33870) for the roadmap and proposal.** + +The Superset MCP service exposes high-level tools for dashboards, charts, and datasets via the FastMCP protocol. All read/list/count operations use Superset DAOs, wrapped by `MCPDAOWrapper` to enforce security and user context. Mutations (create/update/delete) will use Superset command objects in future versions. + +## Flow Overview + +```mermaid +graph TD + subgraph FastMCP Service + A[LLM/Agent or Client] + B[FastMCP Tool Call] + C[MCPDAOWrapper] + D1[DashboardDAO] + D2[ChartDAO] + D3[DatasetDAO] + E[Superset DB] + F[Superset Command - planned for mutations] + end + + A --> B + B --> C + C -- list/count/info --> D1 + C -- list/count/info --> D2 + C -- list/count/info --> D3 + D1 --> E + D2 --> E + D3 --> E + B -. "create/update/delete (planned)" .-> F + F -.uses.-> C + F --> D1 + F --> D2 + F --> D3 + F --> E +``` + +## Modular Tool Structure + +All tools are organized by domain for clarity and maintainability: + +- `superset/mcp_service/tools/dashboard/` +- `superset/mcp_service/tools/dataset/` +- `superset/mcp_service/tools/chart/` +- `superset/mcp_service/tools/system/` + +Each tool is a standalone Python module. Shared utilities live in `tools/base.py`. + +## Pydantic Model/Data Flow + +```mermaid +graph TD + subgraph Tool Layer + T[FastMCP Tool] + PI[Pydantic Input Model] + PO[Pydantic Output Model] + end + subgraph Service Layer + W[MCPDAOWrapper] + DAO[DAO -DashboardDAO, ChartDAO, DatasetDAO] + end + subgraph Data Layer + DB[Superset DB] + SA[SQLAlchemy Models] + end + + T -- input schema --> PI + PI -- validated params --> W + W -- calls --> DAO + DAO -- queries --> DB + DB -- returns --> SA + SA -- returned by --> W + W -- SQLAlchemy models --> T + T -- builds --> PO + PO -- response schema --> T +``` + +- **Pydantic Input Model**: Defines and validates tool input parameters. +- **MCPDAOWrapper**: Calls the DAO and returns SQLAlchemy models. +- **FastMCP Tool**: Converts SQLAlchemy models to the Pydantic output model for the response. +- **Pydantic Output Model**: Defines the structured response returned by each tool. +- All tool contracts are strongly typed, ensuring robust agent and client integration for dashboards, charts, and datasets. + +## How to Add a New Tool + +1. **Choose the Right Domain** + - Place your tool in the appropriate subfolder under `tools/` (e.g., `tools/chart/`). Review Comment: What are the considerations about splitting into tools / resources / prompts. I guess if the need should arise to have that separation of concerns, then a structure like the following might help? `chart/tools` `chart/resources` `chart/prompts` ########## superset/mcp_service/README_SCHEMAS.md: ########## @@ -0,0 +1,477 @@ +# Superset MCP Service: Tool Schemas Reference + +This document provides a reference for the input and output parameters of all MCP tools in the Superset MCP service. Each section lists the tool name, its input parameters (with type), and its output schema. + +## Dashboards + +### list_dashboards + +**Inputs:** +- `filters`: `Optional[List[DashboardFilter]]` — List of filter objects +- `columns`: `Optional[List[str]]` — Columns to include in the response Review Comment: Is the LLM good at choosing what columns will be required? Would returning a set fixed of columns that cover most relevant use cases be a better option here? -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
