aminghadersohi commented on code in PR #33976: URL: https://github.com/apache/superset/pull/33976#discussion_r2210380055
########## 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: done -- 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]
