You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@superset.apache.org by "aminghadersohi (via GitHub)" <gi...@apache.org> on 2025/10/25 00:17:42 UTC

[PR] feat(mcp): PR2 - Add chart listing and info tools with core infrastructure [superset]

aminghadersohi opened a new pull request, #35835:
URL: https://github.com/apache/superset/pull/35835

   ### SUMMARY
   
   This PR adds the first two MCP tools for chart access along with reusable core infrastructure for building additional MCP tools.
   
   **Built on top of:** PR #1 (feat/mcp_service_pr1_scaffold) - MCP service scaffold
   
   **What's Included:**
   
   ## New MCP Tools
   
   **list_charts** - Paginated chart listing
   - Filter by: slice_name, viz_type, datasource_name
   - Search across chart fields
   - Sort by: id, slice_name, viz_type, changed_on, created_on
   - 1-based pagination (page, page_size parameters)
   - Returns: ChartList with chart metadata
   
   **get_chart_info** - Retrieve chart details
   - Lookup by integer ID or UUID string
   - Returns: Complete chart metadata (name, viz_type, params, owners, etc.)
   - Consistent error responses with ChartError schema
   
   ## Core Infrastructure (297 lines)
   
   **mcp_core.py** - Reusable base classes for MCP tools:
   - **BaseCore**: Flask app context management
   - **ModelListCore**: Generic paginated listing with filtering/search/sorting
     - Type-safe with `Generic[L]` for proper type inference
     - Handles pagination, filters, search, ordering
     - Works with any Superset DAO (ChartDAO, DashboardDAO, etc.)
   - **ModelGetInfoCore**: Generic single-item retrieval by ID/UUID
     - Automatic ID vs UUID detection
     - Consistent error handling
   
   **auth.py** (98 lines) - Minimal authentication:
   - `@mcp_auth_hook` decorator for tool authentication
   - Admin user fallback for development
   - `has_dataset_access()` for dataset permission checking
   - Flask `g.user` context integration
   
   **middleware.py** (74 lines) - Basic error handling:
   - Request/response logging
   - Error response formatting
   - Flask context integration
   
   **utils/** (29 lines) - Shared utilities:
   - `_is_uuid()` helper for ID validation
   
   ## Schemas (Pydantic)
   
   **chart/schemas.py** (283 lines):
   - `ChartInfo`: Detailed chart metadata model
   - `ChartList`: Paginated list response with PaginationInfo
   - `ChartError`: Consistent error responses
   - `ChartFilter`: Filter specification (col, opr, value)
   - `ListChartsRequest`, `GetChartInfoRequest`: Tool request models
   - `ColumnRef`, `TableChartConfig`, `XYChartConfig`: For future chart creation tools
   
   **system/schemas.py** (expanded from 40 to 87 lines):
   - `UserInfo`: User metadata (id, username, first_name, last_name, roles)
   - `TagInfo`: Tag information
   - `PaginationInfo`: Pagination metadata (count, page, page_size, total_count)
   - `RoleInfo`: Role metadata (for future use)
   
   **common/cache_schemas.py** (143 lines):
   - `CacheControl`: Unified cache behavior configuration
   - Flags: use_cache, force_refresh, cache_timeout, refresh_metadata
   - Consistent caching interface for all tools
   
   ## Testing (408 lines)
   
   **test_list_charts.py** (172 lines):
   - Schema validation tests for ChartInfo, ChartList, ChartFilter
   - Request/response model validation
   - Filter specification tests
   
   **test_mcp_core.py** (204 lines):
   - ModelListCore tests: pagination, filtering, search, ordering
   - ModelGetInfoCore tests: ID lookup, UUID lookup, not found cases
   - Error handling tests
   
   **Apache license headers** on all __init__.py files
   
   ## Integration
   
   **app.py** (4 line change):
   ```python
   import superset.mcp_service.chart.tool  # noqa: F401, E402
   ```
   
   This single import registers both tools via their `@mcp.tool` decorators.
   
   ## Architecture & Patterns
   
   This PR establishes the pattern for all future MCP tools:
   
   1. **Create tool** using `@mcp.tool` decorator
   2. **Use core classes**: ModelListCore for listing, ModelGetInfoCore for retrieval
   3. **Define schemas**: Pydantic models for type-safe requests/responses
   4. **Add tests**: Unit tests for schemas and tool logic
   5. **Register**: Import tool module in app.py
   
   **Type safety:**
   - Modern Python 3.10+ type hints (`T | None` instead of `Optional[T]`)
   - Generic types for proper inference (`ModelListCore[ChartList]`)
   - All code is mypy compliant
   
   **Reusability:**
   - Core classes work with any Superset entity (charts, dashboards, datasets, etc.)
   - Just provide the DAO class and schema - the rest is handled automatically
   - Same pattern used for upcoming dashboard and dataset tools
   
   ### BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF
   
   N/A - Backend MCP service infrastructure only, no UI changes.
   
   **Example tool usage via Claude Desktop:**
   
   ```
   User: "List the most recently updated bar charts"
   Claude calls: list_charts({
     "filters": [{"col": "viz_type", "opr": "eq", "value": "bar"}],
     "order_column": "changed_on",
     "order_direction": "desc"
   })
   
   User: "Show me details for chart ID 123"
   Claude calls: get_chart_info({"identifier": 123})
   ```
   
   ### TESTING INSTRUCTIONS
   
   **Prerequisites:**
   - Superset running with PR #1 (MCP scaffold) merged
   - Python 3.10 or 3.11
   - fastmcp installed (`pip install -e .[development]`)
   
   **Setup:**
   
   ```bash
   # 1. Ensure database is initialized
   export FLASK_APP=superset
   superset db upgrade
   superset init
   
   # 2. Create admin user (if not already done)
   superset fab create-admin \
     --username admin \
     --firstname Admin \
     --lastname Admin \
     --email admin@localhost \
     --password admin
   
   # 3. Load example data (for testing)
   superset load-examples
   ```
   
   **Run Tests:**
   
   ```bash
   # Run all MCP service unit tests
   pytest tests/unit_tests/mcp_service/ -v
   
   # Should see:
   # - test_list_charts.py: 16 schema tests passing
   # - test_mcp_core.py: 11 core infrastructure tests passing
   # Total: 27 tests passing
   ```
   
   **Test with MCP Server:**
   
   ```bash
   # Terminal 1: Start Superset
   superset run -p 9001
   
   # Terminal 2: Start MCP service
   superset mcp run --port 5008 --debug
   
   # Terminal 3: Test with curl
   curl http://localhost:5008/health
   
   # Expected: {"status": "ok", "timestamp": "...", ...}
   ```
   
   **Test Tools via Claude Desktop:**
   
   Configure Claude Desktop with:
   ```json
   {
     "mcpServers": {
       "superset": {
         "command": "superset",
         "args": ["mcp", "run", "--port", "5008"]
       }
     }
   }
   ```
   
   Then test queries:
   - "List all charts" β†’ Should call list_charts tool
   - "Show me chart 1" β†’ Should call get_chart_info tool
   - "List bar charts" β†’ Should call list_charts with viz_type filter
   
   **Verify Error Handling:**
   
   ```python
   # Test in Python shell with Flask app context
   from superset.mcp_service.chart.tool import list_charts, get_chart_info
   
   # Test pagination
   result = list_charts(page=1, page_size=10)
   assert result.pagination.page == 1
   
   # Test filtering
   result = list_charts(filters=[{"col": "viz_type", "opr": "eq", "value": "bar"}])
   assert all(c.viz_type == "bar" for c in result.charts)
   
   # Test not found
   result = get_chart_info(identifier=99999)
   assert result.error is not None
   ```
   
   ### ADDITIONAL INFORMATION
   
   - [ ] Has associated issue:
   - [ ] Required feature flags: None
   - [ ] Changes UI: No
   - [ ] Includes DB Migration: No
   - [x] Introduces new feature or API: Yes - MCP chart tools and core infrastructure
   - [ ] Removes existing feature or API: No
   
   **Stats:**
   - 18 files changed
   - 1,649 insertions, 5 deletions
   - 408 lines of tests (27 test cases)
   - 100% mypy compliant
   - All pre-commit hooks passing
   
   **Future PRs will add:**
   - Dashboard tools (list_dashboards, get_dashboard_info, etc.)
   - Dataset tools (list_datasets, get_dataset_info, etc.)
   - Chart creation tools (generate_chart, update_chart, etc.)
   - SQL Lab integration tools
   - Advanced authentication (JWT, OAuth)
   - Field-level permissions and audit logging
   
   **Notes:**
   - Builds cleanly on PR #1 (MCP scaffold)
   - Minimal changes to existing code (only app.py import)
   - No database migrations
   - No UI changes
   - Optional dependency (fastmcp in development requirements only)
   


-- 
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-unsubscribe@superset.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org

Re: [PR] feat(mcp): PR2 - Add chart listing and info tools with core infrastructure [superset]

Posted by "sadpandajoe (via GitHub)" <gi...@apache.org>.
sadpandajoe merged PR #35835:
URL: https://github.com/apache/superset/pull/35835


-- 
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-unsubscribe@superset.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org

Re: [PR] feat(mcp): PR2 - Add chart listing and info tools with core infrastructure [superset]

Posted by "bito-code-review[bot] (via GitHub)" <gi...@apache.org>.
bito-code-review[bot] commented on PR #35835:
URL: https://github.com/apache/superset/pull/35835#issuecomment-3445365756

   <details open>
     <summary><strong>Interaction Diagram by <a href="https://bito.ai#sequence_diagram">Bito</a></strong></summary>
   
   ```mermaid
   sequenceDiagram
   participant CLI as Superset CLI<br/>🟩 Added | ●●● High
   participant MCPCmd as mcp.py<br/>🟩 Added | ●●● High
   participant Server as server.py<br/>🟩 Added | ●●● High
   participant AppFactory as app.py<br/>🟩 Added | ●●● High
   participant FastMCP as FastMCP Instance<br/>🟩 Added | ●●● High
   participant ToolRegistry as Tool Registry<br/>🟩 Added | ●●● High
   participant ChartTool as Chart Tools<br/>🟩 Added | ●●● High
   participant Superset as Superset DAOs
   Note over CLI, MCPCmd: User runs: superset mcp run --port 5008
   CLI->>MCPCmd: Execute mcp.run(host, port, debug)
   MCPCmd->>Server: run_server(host, port, debug)
   Server->>AppFactory: init_fastmcp_server()
   AppFactory->>FastMCP: create_mcp_app() returns FastMCP instance
   AppFactory->>ToolRegistry: Import & register tools (chart, system)
   ToolRegistry->>ChartTool: Decorate with @mcp.tool
   Note over FastMCP, ChartTool: Tools auto-registered via decorator
   FastMCP->>Server: FastMCP instance configured
   Server->>FastMCP: mcp.run(transport=streamable-http)
   FastMCP-->>Superset: Ready to accept MCP requests
   FastMCP-->>Server: HTTP server listening on host:port
   ```
   Critical path: Superset CLI -&gt; mcp.py -&gt; server.py -&gt; app.py -&gt; FastMCP Instance -&gt; Tool Registry -&gt; Chart Tools -&gt; Superset DAOs
   
   
   > **Note:** The diff adds a complete MCP (Model Context Protocol) service to Superset, enabling AI agents to interact with dashboards and charts. The flow starts from the CLI, initializes FastMCP with tool registration, and exposes HTTP endpoints for agent communication.
   
   </details>


-- 
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-unsubscribe@superset.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org

Re: [PR] feat(mcp): PR2 - Add chart listing and info tools with core infrastructure [superset]

Posted by "codecov[bot] (via GitHub)" <gi...@apache.org>.
codecov[bot] commented on PR #35835:
URL: https://github.com/apache/superset/pull/35835#issuecomment-3445365404

   ## [Codecov](https://app.codecov.io/gh/apache/superset/pull/35835?dropdown=coverage&src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) Report
   :x: Patch coverage is `0%` with `198 lines` in your changes missing coverage. Please review.
   :white_check_mark: Project coverage is 50.09%. Comparing base ([`76d897e`](https://app.codecov.io/gh/apache/superset/commit/76d897eaa2f9e137102bc194c2e3109c29d0348f?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache)) to head ([`043c78e`](https://app.codecov.io/gh/apache/superset/commit/043c78efaf80c362ea000c5beaef901f40bd714a?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache)).
   :warning: Report is 2790 commits behind head on master.
   
   | [Files with missing lines](https://app.codecov.io/gh/apache/superset/pull/35835?dropdown=coverage&src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | Patch % | Lines |
   |---|---|---|
   | [superset/mcp\_service/mcp\_core.py](https://app.codecov.io/gh/apache/superset/pull/35835?src=pr&el=tree&filepath=superset%2Fmcp_service%2Fmcp_core.py&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache#diff-c3VwZXJzZXQvbWNwX3NlcnZpY2UvbWNwX2NvcmUucHk=) | 0.00% | [110 Missing :warning: ](https://app.codecov.io/gh/apache/superset/pull/35835?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) |
   | [superset/mcp\_service/system/schemas.py](https://app.codecov.io/gh/apache/superset/pull/35835?src=pr&el=tree&filepath=superset%2Fmcp_service%2Fsystem%2Fschemas.py&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache#diff-c3VwZXJzZXQvbWNwX3NlcnZpY2Uvc3lzdGVtL3NjaGVtYXMucHk=) | 0.00% | [26 Missing :warning: ](https://app.codecov.io/gh/apache/superset/pull/35835?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) |
   | [superset/mcp\_service/auth.py](https://app.codecov.io/gh/apache/superset/pull/35835?src=pr&el=tree&filepath=superset%2Fmcp_service%2Fauth.py&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache#diff-c3VwZXJzZXQvbWNwX3NlcnZpY2UvYXV0aC5weQ==) | 0.00% | [22 Missing :warning: ](https://app.codecov.io/gh/apache/superset/pull/35835?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) |
   | [superset/mcp\_service/common/cache\_schemas.py](https://app.codecov.io/gh/apache/superset/pull/35835?src=pr&el=tree&filepath=superset%2Fmcp_service%2Fcommon%2Fcache_schemas.py&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache#diff-c3VwZXJzZXQvbWNwX3NlcnZpY2UvY29tbW9uL2NhY2hlX3NjaGVtYXMucHk=) | 0.00% | [16 Missing :warning: ](https://app.codecov.io/gh/apache/superset/pull/35835?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) |
   | [superset/mcp\_service/middleware.py](https://app.codecov.io/gh/apache/superset/pull/35835?src=pr&el=tree&filepath=superset%2Fmcp_service%2Fmiddleware.py&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache#diff-c3VwZXJzZXQvbWNwX3NlcnZpY2UvbWlkZGxld2FyZS5weQ==) | 0.00% | [15 Missing :warning: ](https://app.codecov.io/gh/apache/superset/pull/35835?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) |
   | [superset/mcp\_service/utils/\_\_init\_\_.py](https://app.codecov.io/gh/apache/superset/pull/35835?src=pr&el=tree&filepath=superset%2Fmcp_service%2Futils%2F__init__.py&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache#diff-c3VwZXJzZXQvbWNwX3NlcnZpY2UvdXRpbHMvX19pbml0X18ucHk=) | 0.00% | [8 Missing :warning: ](https://app.codecov.io/gh/apache/superset/pull/35835?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) |
   | [superset/mcp\_service/app.py](https://app.codecov.io/gh/apache/superset/pull/35835?src=pr&el=tree&filepath=superset%2Fmcp_service%2Fapp.py&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache#diff-c3VwZXJzZXQvbWNwX3NlcnZpY2UvYXBwLnB5) | 0.00% | [1 Missing :warning: ](https://app.codecov.io/gh/apache/superset/pull/35835?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) |
   
   <details><summary>Additional details and impacted files</summary>
   
   
   
   ```diff
   @@             Coverage Diff             @@
   ##           master   #35835       +/-   ##
   ===========================================
   - Coverage   60.48%   50.09%   -10.39%     
   ===========================================
     Files        1931      605     -1326     
     Lines       76236    44206    -32030     
     Branches     8568     4782     -3786     
   ===========================================
   - Hits        46114    22147    -23967     
   + Misses      28017    21435     -6582     
   + Partials     2105      624     -1481     
   ```
   
   | [Flag](https://app.codecov.io/gh/apache/superset/pull/35835/flags?src=pr&el=flags&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | Coverage Ξ” | |
   |---|---|---|
   | [hive](https://app.codecov.io/gh/apache/superset/pull/35835/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | `45.70% <0.00%> (-3.46%)` | :arrow_down: |
   | [javascript](https://app.codecov.io/gh/apache/superset/pull/35835/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | `?` | |
   | [presto](https://app.codecov.io/gh/apache/superset/pull/35835/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | `49.35% <0.00%> (-4.45%)` | :arrow_down: |
   | [python](https://app.codecov.io/gh/apache/superset/pull/35835/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | `50.09% <0.00%> (-13.42%)` | :arrow_down: |
   | [unit](https://app.codecov.io/gh/apache/superset/pull/35835/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | `100.00% <ΓΈ> (+42.36%)` | :arrow_up: |
   
   Flags with carried forward coverage won't be shown. [Click here](https://docs.codecov.io/docs/carryforward-flags?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache#carryforward-flags-in-the-pull-request-comment) to find out more.
   </details>
   
   [:umbrella: View full report in Codecov by Sentry](https://app.codecov.io/gh/apache/superset/pull/35835?dropdown=coverage&src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache).   
   :loudspeaker: Have feedback on the report? [Share it here](https://about.codecov.io/codecov-pr-comment-feedback/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache).
   <details><summary> :rocket: New features to boost your workflow: </summary>
   
   - :snowflake: [Test Analytics](https://docs.codecov.com/docs/test-analytics): Detect flaky tests, report on failures, and find test suite problems.
   - :package: [JS Bundle Analysis](https://docs.codecov.com/docs/javascript-bundle-analysis): Save yourself from yourself by tracking and limiting bundle sizes in JS merges.
   </details>


-- 
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-unsubscribe@superset.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org

Re: [PR] feat(mcp): PR2 - Add chart listing and info tools with core infrastructure [superset]

Posted by "korbit-ai[bot] (via GitHub)" <gi...@apache.org>.
korbit-ai[bot] commented on PR #35835:
URL: https://github.com/apache/superset/pull/35835#issuecomment-3445302125

   Korbit doesn't automatically review large (3000+ lines changed) pull requests such as this one. If you want me to review anyway, use `/korbit-review`.
   
   
   [](be43293f-a4c1-433b-a50d-c26154fd4205)


-- 
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-unsubscribe@superset.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org

Re: [PR] feat(mcp): PR2 - Add chart listing and info tools with core infrastructure [superset]

Posted by "bito-code-review[bot] (via GitHub)" <gi...@apache.org>.
bito-code-review[bot] commented on PR #35835:
URL: https://github.com/apache/superset/pull/35835#issuecomment-3445302198

   AI Code Review is in progress (usually takes 3 to 15 minutes unless it's a very large PR).


-- 
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-unsubscribe@superset.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org