aminghadersohi commented on code in PR #33976: URL: https://github.com/apache/superset/pull/33976#discussion_r2220100293
########## 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/`). +2. **Define Schemas** + - Use Pydantic models for all input and output. + - Add `description` to every field for LLM/OpenAPI friendliness. + - Place shared schemas in `pydantic_schemas/`. +3. **Implement the Tool** + - Use `log_tool_call` from `tools/base.py` for logging. + - Use `MCPDAOWrapper` for DAO access and security. + - Follow the style and conventions of existing tools. +4. **Register the Tool** + - Add your tool to `tools/__init__.py` in the `MCP_TOOLS` dict and `__all__` list. Review Comment: using decorator now. the issue i found was to do with importing superset modules and running outside of ap context, which is now fixed by putting the imports inside the functions and not in the file, so we can use the decorators safely. -- 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: notifications-unsubscr...@superset.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org --------------------------------------------------------------------- To unsubscribe, e-mail: notifications-unsubscr...@superset.apache.org For additional commands, e-mail: notifications-h...@superset.apache.org
