aminghadersohi opened a new pull request, #35839:
URL: https://github.com/apache/superset/pull/35839
## SUMMARY
This PR completes the MCP service implementation by adding instance-level
metadata and AI guidance features. It introduces a comprehensive instance
information tool, system prompts for user onboarding, and resource templates
for chart configurations.
**New Features Added:**
**Tools (1):**
- **get_superset_instance_info**: Comprehensive instance statistics
including dashboards, charts, datasets, activity metrics, database breakdowns,
and popular content
**Prompts (2):**
- **superset_quickstart**: Interactive onboarding guide tailored by user
type (analyst, executive, developer) and focus area
- **create_chart_guided**: AI-powered chart creation workflow that guides
users through business context and visualization selection
**Resources (2):**
- **chart_configs**: Example chart configuration templates for common
visualization types (bar, line, pie, scatter, etc.)
- **instance_metadata**: Real-time instance metadata and statistics
accessible without tool calls
**Infrastructure Added:**
- **InstanceInfoCore class** (173 lines in mcp_core.py):
- Configurable base class for comprehensive instance reporting
- Custom metric calculators via dependency injection
- Flexible breakdown calculations for dashboards, databases, and popular
content
- Extensible design for adding new metrics without modifying core logic
- **System schemas** (85 lines added to system/schemas.py):
- `GetSupersetInstanceInfoRequest` - Request schema with optional metric
filters
- `InstanceInfo` - Complete instance information response
- `InstanceSummary` - High-level counts and totals
- `RecentActivity` - User activity metrics (last 7/30 days)
- `DashboardBreakdown` - Dashboard categorization (published vs draft)
- `DatabaseBreakdown` - Database usage statistics
- `PopularContent` - Most viewed/edited content
**Statistics:**
- **Files Changed**: 16 (16 new, 2 modified)
- **Lines Added**: ~1,461
- get_superset_instance_info.py: 268 lines
- InstanceInfoCore in mcp_core.py: 173 lines
- Prompts: 289 lines (quickstart: 94, create_chart_guided: 195)
- Resources: 469 lines (chart_configs: 362, instance_metadata: 107)
- Schemas: 85 lines (7 new schema classes)
- Placeholder __init__.py files: 126 lines (dashboard/dataset
prompts/resources)
- **All pre-commit hooks passing**
**Builds on:**
- PR #35163 (MCP service scaffold)
- PR2 (chart listing and info tools)
- PR3 (dashboard and dataset listing and info tools)
- PR4 (advanced chart tools and SQL Lab integration)
- PR5 (dashboard generation and chart placement tools)
## BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF
N/A - This is a backend API enhancement for the MCP service.
## TESTING INSTRUCTIONS
### Prerequisites
1. Ensure you have a running Superset instance with the MCP service enabled
2. Ensure you have the development environment set up (Python venv activated)
3. Have some dashboards, charts, and datasets created in your Superset
instance for meaningful statistics
### Manual Testing with MCP Client
If you have an MCP client configured (Claude Desktop, Cline, etc.), you can
test the new features:
#### 1. Test Instance Info Tool
```python
# Via MCP client: Request instance information
Use the get_superset_instance_info tool
# Expected response includes:
# - Summary counts (total dashboards, charts, datasets, databases)
# - Recent activity (user counts, chart views, edits)
# - Dashboard breakdown (published vs draft)
# - Database breakdown (usage by database)
# - Popular content (most viewed/edited items)
```
#### 2. Test Prompts
```
# Via MCP client: Access the quickstart prompt
Request the "superset_quickstart" prompt with:
user_type: "analyst"
focus_area: "sales"
# Expected: Personalized onboarding guide with:
# - Welcome message tailored to analysts
# - Sales-focused example queries
# - Step-by-step visualization creation
# - Dashboard building guidance
# Try the chart creation prompt
Request the "create_chart_guided" prompt
# Expected: Interactive chart creation guide with:
# - Business context questions
# - Available dataset suggestions
# - Chart type recommendations
# - Configuration examples
```
#### 3. Test Resources
```
# Via MCP client: Access chart configuration examples
Request the "chart_configs" resource
# Expected: Template configurations for:
# - Bar charts
# - Line charts
# - Pie charts
# - Scatter plots
# - Time series
# And more...
# Request instance metadata
Request the "instance_metadata" resource
# Expected: Current instance stats including:
# - Available databases
# - Dataset count
# - Chart type distribution
# - User activity
```
### Pre-Commit Validation
```bash
# Stage all files
git add -A
# Run pre-commit hooks on changed files
pre-commit run --files \
superset/mcp_service/system/tool/get_superset_instance_info.py \
superset/mcp_service/system/prompts/quickstart.py \
superset/mcp_service/chart/prompts/create_chart_guided.py \
superset/mcp_service/chart/resources/chart_configs.py \
superset/mcp_service/system/resources/instance_metadata.py \
superset/mcp_service/mcp_core.py \
superset/mcp_service/system/schemas.py
# Expected: All hooks pass (mypy, ruff, pylint, etc.)
```
### Verification Checklist
- [ ] Instance info tool returns valid statistics
- [ ] Quickstart prompt generates personalized guidance
- [ ] Create chart prompt provides helpful workflow
- [ ] Chart configs resource shows template examples
- [ ] Instance metadata resource shows current stats
- [ ] All schemas validate correctly
- [ ] InstanceInfoCore class allows custom metric calculators
- [ ] Pre-commit hooks pass
## ADDITIONAL INFORMATION
- [ ] Has associated issue: No
- [ ] Required feature flags: No
- [ ] Changes UI: No
- [ ] Includes DB Migration: No
- [x] Introduces new feature or API: Yes (1 tool, 2 prompts, 2 resources)
- [ ] Removes existing feature or API: No
**Completes MCP Service Implementation:**
This PR represents the final phase of the core MCP service implementation,
adding:
1. **Instance-level introspection** - AI agents can understand what data and
content is available
2. **User guidance** - Prompts help AI provide better user experiences
3. **Reference templates** - Resources provide examples for common use cases
**Files Changed Summary:**
**New Tool (1 file):**
- superset/mcp_service/system/tool/get_superset_instance_info.py (268 lines)
**New Prompts (3 files):**
- superset/mcp_service/system/prompts/__init__.py (21 lines)
- superset/mcp_service/system/prompts/quickstart.py (94 lines)
- superset/mcp_service/chart/prompts/__init__.py (21 lines)
- superset/mcp_service/chart/prompts/create_chart_guided.py (195 lines)
**New Resources (3 files):**
- superset/mcp_service/system/resources/__init__.py (21 lines)
- superset/mcp_service/system/resources/instance_metadata.py (107 lines)
- superset/mcp_service/chart/resources/__init__.py (21 lines)
- superset/mcp_service/chart/resources/chart_configs.py (362 lines)
**Placeholder Files (4 files):**
- superset/mcp_service/dashboard/prompts/__init__.py (21 lines)
- superset/mcp_service/dashboard/resources/__init__.py (21 lines)
- superset/mcp_service/dataset/prompts/__init__.py (21 lines)
- superset/mcp_service/dataset/resources/__init__.py (21 lines)
**Updated Files (2 files):**
- superset/mcp_service/mcp_core.py (+173 lines for InstanceInfoCore)
- superset/mcp_service/system/schemas.py (+85 lines, 7 new schemas)
- superset/mcp_service/system/tool/__init__.py (export new tool)
**Key Features:**
1. **get_superset_instance_info**:
- Comprehensive instance statistics
- Dashboard breakdown (published vs draft)
- Database usage metrics
- Recent activity tracking (7 and 30 days)
- Popular content identification
- Configurable via InstanceInfoCore base class
2. **superset_quickstart prompt**:
- Personalized by user type (analyst, executive, developer)
- Focused by area of interest (sales, marketing, operations, general)
- Interactive onboarding workflow
- Dataset discovery guidance
- First visualization creation
- Dashboard building basics
3. **create_chart_guided prompt**:
- Business context gathering
- Dataset recommendation
- Chart type suggestion based on data and goals
- Configuration examples
- Best practices guidance
4. **chart_configs resource**:
- Template configurations for common chart types
- Example form_data structures
- Visualization-specific options
- Quick reference for AI agents
5. **instance_metadata resource**:
- Real-time instance statistics
- Available database connections
- Dataset summaries
- User activity metrics
- No tool call required (static resource)
**Architecture Highlights:**
The **InstanceInfoCore** class uses dependency injection for metric
calculation, allowing custom implementations:
```python
# Default implementation
instance_info_core = InstanceInfoCore()
info = instance_info_core.get_instance_info()
# Custom metric calculators
custom_core = InstanceInfoCore(
dashboard_calculator=my_custom_dashboard_metrics,
database_calculator=my_custom_db_metrics
)
```
This design enables:
- Easy testing with mock calculators
- Custom metrics for different deployment scenarios
- Extension without modifying core logic
- Separation of concerns between data access and formatting
**Pattern Compliance:**
This PR continues the **MINIMAL cherry-pick pattern** established in
previous PRs:
- ✅ Copied ONLY the required tool, prompt, and resource files
- ✅ NO development utilities or extra infrastructure
- ✅ Updated exports in `__init__.py` files
- ✅ Added comprehensive schemas for type safety
- ✅ All pre-commit hooks passing
- ✅ Clean separation of concerns
**Next Steps:**
The MCP service is now feature-complete for the initial release. Future
enhancements may include:
- Additional prompts for dashboard and dataset modules
- Custom resources for database-specific examples
- Advanced instance metrics (query performance, cache hit rates)
- Multi-tenant instance information
- Prompt testing framework for validating LLM guidance quality
--
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]
