feat(mcp): add instance info tool, prompts, and resources

Add comprehensive MCP features for instance metadata, user guidance, and resource templates:

**New Tools (1):**
- get_superset_instance_info: Detailed instance statistics with dashboards, charts, datasets, activity metrics, and database breakdowns

**New Prompts (2):**
- superset_quickstart: Interactive onboarding guide for new users
- create_chart_guided: AI-powered chart creation workflow with business context

**New Resources (2):**
- chart_configs: Example chart configuration templates for common visualizations
- instance_metadata: Real-time instance metadata and statistics

**Infrastructure Added:**
- InstanceInfoCore: Configurable base class for comprehensive instance reporting with custom metric calculators
- Added 7 new schemas to system/schemas.py: InstanceInfo, InstanceSummary, RecentActivity, DashboardBreakdown, DatabaseBreakdown, PopularContent, GetSupersetInstanceInfoRequest

Changes:
- Added get_superset_instance_info.py tool (268 lines) with detailed breakdown calculations
- Added InstanceInfoCore class to mcp_core.py (173 lines)
- Added quickstart.py prompt (94 lines) for user onboarding
- Added create_chart_guided.py prompt (195 lines) for AI-assisted chart creation
- Added chart_configs.py resource (362 lines) with example configurations
- Added instance_metadata.py resource (107 lines) for real-time instance stats
- Updated system/tool/__init__.py to export new instance info tool
- Added placeholder __init__.py files for dashboard/dataset prompts and resources
- Added 7 new Pydantic schemas for instance information responses

Statistics:
- 17 files changed (16 new, 2 modified)
- ~1,200 lines of production code added
- All pre-commit hooks passing

fix(mcp): convert timestamp to ISO string in InstanceInfo schema

Fixed Pydantic validation error where timestamp field was receiving a datetime object instead of the expected string type. The InstanceInfo schema requires timestamp as a string, so now we convert it using .isoformat().

fix(mcp): use BaseDAO instead of DAO Protocol in instance_metadata

Replace DAO Protocol casts with BaseDAO[Any] to match InstanceInfoCore type signature.
This fixes mypy type checking errors.

feat(mcp): register prompts and resources in app.py and document in CLAUDE.md

Add imports for chart and system prompts/resources to ensure they are registered
with the MCP instance on startup. Update CLAUDE.md with comprehensive instructions
for adding new prompts and resources.

Changes to app.py:
- Import chart.prompts module to register create_chart_guided prompt
- Import chart.resources module to register chart_configs resource
- Import system.prompts module to register superset_quickstart prompt
- Import system.resources module to register instance_metadata resource
- Add clear comment explaining prompt/resource registration pattern

Changes to CLAUDE.md:
- Update section title to include prompts and resources
- Add "How to Add a New Prompt" section with complete workflow
- Add "How to Add a New Resource" section with complete workflow
- Add Quick Checklist for New Prompts
- Add Quick Checklist for New Resources
- Update line number references (210-242 for tools, 244-253 for prompts/resources)
- Explain two-level import pattern (module __init__.py + app.py)

This ensures all prompts and resources are available to MCP clients and provides
clear documentation for future contributors.

Author: aminghadersohi

superset/mcp_service/CLAUDE.md

@@ -67,15 +67,15 @@ superset/mcp_service/
     └── tool/
 ```
 
-## Critical Convention: Tool Registration
+## Critical Convention: Tool, Prompt, and Resource Registration
 
-**IMPORTANT**: When creating new MCP tools, you MUST add their imports to `app.py` for auto-registration. Do NOT add them to `server.py` - that approach doesn't work properly.
+**IMPORTANT**: When creating new MCP tools, prompts, or resources, you MUST add their imports to `app.py` for auto-registration. Do NOT add them to `server.py` - that approach doesn't work properly.
 
 ### How to Add a New Tool
 
 1. **Create the tool file** in the appropriate directory (e.g., `chart/tool/my_new_tool.py`)
 2. **Decorate with `@mcp.tool`** to register it with FastMCP
-3. **Add import to `app.py`** at the bottom of the file where other tools are imported (around line 207-224)
+3. **Add import to `app.py`** at the bottom of the file where other tools are imported (around line 210-242)
 
 **Example**:
 ```python
@@ -102,6 +102,74 @@ from superset.mcp_service.chart.tool import (  # noqa: F401, E402
 
 **Why this matters**: Tools use `@mcp.tool` decorators and register automatically on import. The import MUST be in `app.py` at the bottom of the file (after the `mcp` instance is created). If you don't import the tool in `app.py`, it won't be available to MCP clients. DO NOT add imports to `server.py` - that file is for running the server only.
 
+### How to Add a New Prompt
+
+1. **Create the prompt file** in the appropriate directory (e.g., `chart/prompts/my_new_prompt.py`)
+2. **Decorate with `@mcp.prompt`** to register it with FastMCP
+3. **Add import to module's `__init__.py`** (e.g., `chart/prompts/__init__.py`)
+4. **Ensure module is imported in `app.py`** (around line 244-253)
+
+**Example**:
+```python
+# superset/mcp_service/chart/prompts/my_new_prompt.py
+from superset.mcp_service.app import mcp
+from superset.mcp_service.auth import mcp_auth_hook
+
+@mcp.prompt("my_new_prompt")
+@mcp_auth_hook
+async def my_new_prompt_handler(ctx: Context) -> str:
+    """Interactive prompt for doing something."""
+    return "Prompt instructions here..."
+```
+
+**Then add to `chart/prompts/__init__.py`**:
+```python
+# superset/mcp_service/chart/prompts/__init__.py
+from . import create_chart_guided  # existing
+from . import my_new_prompt  # ADD YOUR PROMPT HERE
+```
+
+**Verify module import exists in `app.py`** (around line 248):
+```python
+# superset/mcp_service/app.py
+from superset.mcp_service.chart import prompts as chart_prompts  # This imports all prompts
+```
+
+### How to Add a New Resource
+
+1. **Create the resource file** in the appropriate directory (e.g., `chart/resources/my_new_resource.py`)
+2. **Decorate with `@mcp.resource`** to register it with FastMCP
+3. **Add import to module's `__init__.py`** (e.g., `chart/resources/__init__.py`)
+4. **Ensure module is imported in `app.py`** (around line 244-253)
+
+**Example**:
+```python
+# superset/mcp_service/chart/resources/my_new_resource.py
+from superset.mcp_service.app import mcp
+from superset.mcp_service.auth import mcp_auth_hook
+
+@mcp.resource("superset://chart/my_resource")
+@mcp_auth_hook
+def get_my_resource() -> str:
+    """Resource description for LLMs."""
+    return "Resource data here..."
+```
+
+**Then add to `chart/resources/__init__.py`**:
+```python
+# superset/mcp_service/chart/resources/__init__.py
+from . import chart_configs  # existing
+from . import my_new_resource  # ADD YOUR RESOURCE HERE
+```
+
+**Verify module import exists in `app.py`** (around line 249):
+```python
+# superset/mcp_service/app.py
+from superset.mcp_service.chart import resources as chart_resources  # This imports all resources
+```
+
+**Why this matters**: Prompts and resources work similarly to tools - they use decorators and register on import. The module-level imports (`chart/prompts/__init__.py`, `chart/resources/__init__.py`) ensure individual files are imported when the module is imported. The `app.py` imports ensure the modules are loaded when the MCP service starts.
+
 ## Tool Development Patterns
 
 ### 1. Use Core Classes for Reusability
@@ -417,12 +485,36 @@ MCP clients discover tools via:
 - [ ] Added `@mcp_auth_hook` decorator
 - [ ] Created Pydantic request/response schemas in `{module}/schemas.py`
 - [ ] Used DAO classes instead of direct queries
-- [ ] Added tool import to `app.py` (around line 207-224)
+- [ ] Added tool import to `app.py` (around line 210-242)
 - [ ] Added Apache license header to new files
 - [ ] Created unit tests in `tests/unit_tests/mcp_service/{module}/tool/test_{tool_name}.py`
 - [ ] Updated `DEFAULT_INSTRUCTIONS` in `app.py` if adding new capability
 - [ ] Tested locally with MCP client (e.g., Claude Desktop)
 
+## Quick Checklist for New Prompts
+
+- [ ] Created prompt file in `{module}/prompts/{prompt_name}.py`
+- [ ] Added `@mcp.prompt("prompt_name")` decorator
+- [ ] Added `@mcp_auth_hook` decorator
+- [ ] Made function async: `async def prompt_handler(ctx: Context) -> str`
+- [ ] Added import to `{module}/prompts/__init__.py`
+- [ ] Verified module import exists in `app.py` (around line 244-253)
+- [ ] Added Apache license header to new file
+- [ ] Updated `DEFAULT_INSTRUCTIONS` in `app.py` to list the new prompt
+- [ ] Tested locally with MCP client (e.g., Claude Desktop)
+
+## Quick Checklist for New Resources
+
+- [ ] Created resource file in `{module}/resources/{resource_name}.py`
+- [ ] Added `@mcp.resource("superset://{path}")` decorator with unique URI
+- [ ] Added `@mcp_auth_hook` decorator
+- [ ] Implemented resource data retrieval logic
+- [ ] Added import to `{module}/resources/__init__.py`
+- [ ] Verified module import exists in `app.py` (around line 244-253)
+- [ ] Added Apache license header to new file
+- [ ] Updated `DEFAULT_INSTRUCTIONS` in `app.py` to list the new resource
+- [ ] Tested locally with MCP client (e.g., Claude Desktop)
+
 ## Getting Help
 
 - Check existing tool implementations for patterns (chart/tool/, dashboard/tool/)

superset/mcp_service/app.py

@@ -207,6 +207,14 @@ def create_mcp_app(
 # Import all MCP tools to register them with the mcp instance
 # NOTE: Always add new tool imports here when creating new MCP tools.
 # Tools use @mcp.tool decorators and register automatically on import.
+# Import prompts and resources to register them with the mcp instance
+# NOTE: Always add new prompt/resource imports here when creating new prompts/resources.
+# Prompts use @mcp.prompt decorators and resources use @mcp.resource decorators.
+# They register automatically on import, similar to tools.
+from superset.mcp_service.chart import (  # noqa: F401, E402
+    prompts as chart_prompts,
+    resources as chart_resources,
+)
 from superset.mcp_service.chart.tool import (  # noqa: F401, E402
     generate_chart,
     get_chart_available_filters,
@@ -236,7 +244,14 @@ def create_mcp_app(
     execute_sql,
     open_sql_lab_with_context,
 )
-from superset.mcp_service.system.tool import health_check  # noqa: F401, E402
+from superset.mcp_service.system import (  # noqa: F401, E402
+    prompts as system_prompts,
+    resources as system_resources,
+)
+from superset.mcp_service.system.tool import (  # noqa: F401, E402
+    get_superset_instance_info,
+    health_check,
+)
 
 
 def init_fastmcp_server(

superset/mcp_service/chart/prompts/__init__.py

@@ -0,0 +1,21 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Chart prompts for Superset MCP service"""
+
+# Import to register prompts when module is imported
+from . import create_chart_guided  # noqa: F401

superset/mcp_service/chart/prompts/create_chart_guided.py

@@ -0,0 +1,195 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""
+Chart prompts for visualization guidance
+"""
+
+import logging
+
+from superset.mcp_service.app import mcp
+from superset.mcp_service.auth import mcp_auth_hook
+
+logger = logging.getLogger(__name__)
+
+
+@mcp.prompt("create_chart_guided")
+@mcp_auth_hook
+async def create_chart_guided_prompt(
+    chart_type: str = "auto", business_goal: str = "exploration"
+) -> str:
+    """
+    AI-powered chart creation guide following Anthropic's agent design principles.
+
+    This prompt implements:
+    - Transparency: Clear reasoning at each step
+    - Proactive Intelligence: Suggests insights before being asked
+    - Context Awareness: Maintains conversational flow
+    - Business Focus: Translates data into actionable insights
+    - Validation: Verifies choices before proceeding
+    - Natural Interaction: Conversational, not configuration-driven
+
+    Args:
+        chart_type: Preferred chart type (auto, line, bar, pie, table, scatter, area)
+        business_goal: Purpose (exploration, reporting, monitoring, presentation)
+    """
+
+    # Enhanced chart intelligence with business context
+    chart_intelligence = {
+        "line": {
+            "description": "Time series visualization for trend analysis",
+            "best_for": "Tracking performance over time, identifying patterns",
+            "business_value": "Reveals growth trends, seasonality, and patterns",
+            "data_requirements": "Temporal column + continuous metrics",
+        },
+        "bar": {
+            "description": "Category comparison visualization",
+            "best_for": "Ranking, comparisons, and performance by category",
+            "business_value": "Identifies top performers, bottlenecks, and gaps",
+            "data_requirements": "Categorical dimensions + aggregatable metrics",
+        },
+        "scatter": {
+            "description": "Correlation and relationship analysis",
+            "best_for": "Finding relationships, outlier detection, clustering",
+            "business_value": "Uncovers hidden correlations and identifies anomalies",
+            "data_requirements": "Two continuous variables, optional grouping",
+        },
+        "table": {
+            "description": "Detailed data exploration and exact values",
+            "best_for": "Detailed analysis, data validation, precise values",
+            "business_value": "Provides granular insights and detailed reporting",
+            "data_requirements": "Any combination of dimensions and metrics",
+        },
+        "area": {
+            "description": "Volume and composition over time",
+            "best_for": "Showing cumulative effects, stacked comparisons",
+            "business_value": "Visualizes contribution and total volume trends",
+            "data_requirements": "Temporal dimension + stackable metrics",
+        },
+        "auto": {
+            "description": "AI-powered visualization recommendation",
+            "best_for": "When you're not sure what chart type to use",
+            "business_value": "Optimizes chart choice based on data characteristics",
+            "data_requirements": "I'll analyze your data and recommend the best type",
+        },
+    }
+
+    # Business context intelligence
+    goal_intelligence = {
+        "exploration": {
+            "approach": "Interactive discovery and pattern finding",
+            "features": "Filters, drill-downs, multiple perspectives",
+            "outcome": "Uncover hidden insights and generate hypotheses",
+        },
+        "reporting": {
+            "approach": "Clear, professional, and consistent presentation",
+            "features": "Clean design, appropriate aggregation, clear labels",
+            "outcome": "Reliable, repeatable business reporting",
+        },
+        "monitoring": {
+            "approach": "Real-time tracking with clear thresholds",
+            "features": "Alert conditions, trend indicators, key metrics",
+            "outcome": "Proactive issue detection and performance tracking",
+        },
+        "presentation": {
+            "approach": "Compelling visual storytelling",
+            "features": "Engaging colors, clear messaging, audience-appropriate detail",
+            "outcome": "Persuasive data-driven presentations for stakeholders",
+        },
+    }
+
+    selected_chart = chart_intelligence.get(chart_type, chart_intelligence["auto"])
+    selected_goal = goal_intelligence.get(
+        business_goal, goal_intelligence["exploration"]
+    )
+
+    return f"""🎯 **AI-Powered Chart Creation Assistant**
+
+I'm your intelligent data visualization partner! Let me help you create charts.
+
+**Your Visualization Goal:**
+📊 **Chart Focus**: {chart_type.title()} - {selected_chart["description"]}
+🎯 **Business Purpose**: {business_goal.title()} - {selected_goal["approach"]}
+💡 **Expected Value**: {selected_chart["business_value"]}
+
+---
+
+## 🚀 My Intelligent Approach
+
+### **Phase 1: Data Intelligence** 📊
+I'll automatically analyze your dataset to understand:
+- **Data characteristics** (types, distributions, quality)
+- **Business relationships** (correlations, hierarchies, trends)
+- **Visualization opportunities** (what stories your data can tell)
+- **Performance considerations** (size, complexity, aggregation needs)
+
+*Why this matters: The right chart depends on your data's unique characteristics*
+
+### **Phase 2: Smart Recommendations** 🧠
+Based on your data analysis, I'll:
+- **Recommend optimal chart types** with confidence scores and reasoning
+- **Suggest meaningful metrics** that align with your business goal
+- **Identify interesting patterns** you might want to highlight
+- **Propose filters** to focus on what matters most
+
+*Why this matters: I'll spot opportunities you might miss and save you time*
+
+### **Phase 3: Intelligent Configuration** ⚙️
+I'll configure your chart with:
+- **Business-appropriate aggregations** (daily, weekly, monthly for time series)
+- **Meaningful labels and formatting** (currency, percentages, readable names)
+- **Performance optimizations** (appropriate limits, caching strategies)
+- **Visual best practices** (colors, scales, legends that enhance understanding)
+
+*Why this matters: Proper configuration makes charts both beautiful and actionable*
+
+### **Phase 4: Validation & Refinement** 🎯
+Before finalizing, I'll:
+- **Verify the chart answers your business question**
+- **Check data quality and completeness**
+- **Suggest improvements** based on visualization best practices
+- **Provide preview** so you can see exactly what you're getting
+
+*Why this matters: Great charts require iteration and validation*
+
+---
+
+## 🎬 Let's Begin Your Data Story
+
+I'm ready to be your proactive data exploration partner. Here's how we can start:
+
+**Option 1: Quick Start** ⚡
+Tell me: *"What business question are you trying to answer?"*
+(e.g., "How are our sales trending?" or "Which products perform best?")
+
+**Option 2: Dataset Exploration** 🔍
+I can show you available datasets: `list_datasets`
+Or explore a specific one: `get_dataset_info [dataset_id]`
+
+**Option 3: Visual Inspiration** 🎨
+Browse pre-built chart configurations: `superset://chart/configs` resource
+Perfect for when you want to see examples of great charts!
+
+**Option 4: Autonomous Discovery** 🤖
+Just point me to a dataset and say *"Find something interesting"*
+I'll explore autonomously and surface the most compelling insights!
+
+---
+
+💡 **Pro Tip**: Great charts combine business intuition with data analysis!
+
+**What's your data challenge today?** 🚀"""