refactor(mcp): move superset_core MCP module from mcp to api/mcp (#38394)

docs/developer_docs/extensions/mcp.md

@@ -61,7 +61,7 @@ Prompts provide interactive guidance and context to AI agents. They help agents
 The simplest way to create an MCP tool is using the `@tool` decorator:
 
 ```python
-from superset_core.mcp import tool
+from superset_core.api.mcp import tool
 
 @tool
 def hello_world() -> dict:
@@ -94,7 +94,7 @@ Here's a more comprehensive example showing best practices:
 import random
 from datetime import datetime, timezone
 from pydantic import BaseModel, Field
-from superset_core.mcp import tool
+from superset_core.api.mcp import tool
 
 class RandomNumberRequest(BaseModel):
     """Request schema for random number generation."""
@@ -253,7 +253,7 @@ The AI agent sees your tool's:
 Create interactive prompts using the `@prompt` decorator:
 
 ```python
-from superset_core.mcp import prompt
+from superset_core.api.mcp import prompt
 from fastmcp import Context
 
 @prompt("my_extension.workflow_guide")

superset-core/src/superset_core/api/mcp.py

@@ -22,7 +22,7 @@ This module provides a decorator interface to register MCP tools with the
 host application.
 
 Usage:
-    from superset_core.mcp import tool
+    from superset_core.api.mcp import tool
 
     @tool(name="my_tool", description="Custom business logic", tags=["extension"])
     def my_extension_tool(param: str) -> dict:

superset/core/mcp/core_mcp_injection.py

@@ -207,14 +207,14 @@ def create_prompt_decorator(
 def initialize_core_mcp_dependencies() -> None:
     """
     Initialize MCP dependency injection by replacing abstract functions
-    in superset_core.mcp with concrete implementations.
+    in superset_core.api.mcp with concrete implementations.
     """
     try:
-        import superset_core.mcp
+        import superset_core.api.mcp
 
         # Replace the abstract decorators with concrete implementations
-        superset_core.mcp.tool = create_tool_decorator
-        superset_core.mcp.prompt = create_prompt_decorator
+        superset_core.api.mcp.tool = create_tool_decorator
+        superset_core.api.mcp.prompt = create_prompt_decorator
 
         logger.info("MCP dependency injection initialized successfully")
 

superset/mcp_service/CLAUDE.md

@@ -80,7 +80,7 @@ superset/mcp_service/
 **Example**:
 ```python
 # superset/mcp_service/chart/tool/my_new_tool.py
-from superset_core.mcp import tool
+from superset_core.api.mcp import tool
 
 @tool
 def my_new_tool(param: str) -> dict:
@@ -110,7 +110,7 @@ from superset.mcp_service.chart.tool import (  # noqa: F401, E402
 **Example**:
 ```python
 # superset/mcp_service/chart/prompts/my_new_prompt.py
-from superset_core.mcp import prompt
+from superset_core.api.mcp import prompt
 
 @prompt("my_new_prompt")
 async def my_new_prompt_handler(ctx: Context) -> str:
@@ -180,7 +180,7 @@ The `mcp_core.py` module provides reusable patterns:
 
 **Example**:
 ```python
-from superset_core.mcp import tool
+from superset_core.api.mcp import tool
 
 from superset.mcp_service.mcp_core import ModelListCore
 from superset.daos.dashboard import DashboardDAO
@@ -205,7 +205,7 @@ def list_dashboards(filters: List[DashboardFilter], page: int = 1) -> DashboardL
 - Audit logging of tool access
 
 ```python
-from superset_core.mcp import tool
+from superset_core.api.mcp import tool
 
 @tool  # REQUIRED - secure=True by default
 def my_tool() -> dict:
@@ -572,14 +572,14 @@ def my_function(param: Optional[str] = None) -> Optional[int]:
 **Solution**: Use `@tool` without parentheses unless passing arguments.
 ```python
 # GOOD
-from superset_core.mcp import tool
+from superset_core.api.mcp import tool
 
 @tool
 def my_tool():
     pass
 
 # BAD
-from superset_core.mcp import tool
+from superset_core.api.mcp import tool
 
 @tool
 def my_tool():
@@ -588,10 +588,10 @@ def my_tool():
 
 ### 10. ❌ Circular Imports
 **Problem**: Importing too many things from `app.py` can create circular dependencies.
-**Solution**: Use the unified `@tool` decorator from `superset_core.mcp`:
+**Solution**: Use the unified `@tool` decorator from `superset_core.api.mcp`:
 ```python
 # GOOD - New pattern
-from superset_core.mcp import tool
+from superset_core.api.mcp import tool
 
 @tool
 def my_tool():

superset/mcp_service/app.py

@@ -306,7 +306,7 @@ def create_mcp_app(
 mcp = create_mcp_app()
 
 # Initialize MCP dependency injection BEFORE importing tools/prompts
-# This replaces the abstract @tool and @prompt decorators in superset_core.mcp
+# This replaces the abstract @tool and @prompt decorators in superset_core.api.mcp
 # with concrete implementations that can register with the mcp instance
 from superset.core.mcp.core_mcp_injection import (  # noqa: E402
     initialize_core_mcp_dependencies,

superset/mcp_service/chart/prompts/create_chart_guided.py

@@ -19,7 +19,7 @@
 Chart prompts for visualization guidance
 """
 
-from superset_core.mcp import prompt
+from superset_core.api.mcp import prompt
 
 
 @prompt("create_chart_guided")

superset/mcp_service/chart/tool/generate_chart.py

@@ -23,7 +23,7 @@ import time
 from urllib.parse import parse_qs, urlparse
 
 from fastmcp import Context
-from superset_core.mcp import tool
+from superset_core.api.mcp import tool
 
 from superset.commands.exceptions import CommandException
 from superset.extensions import event_logger

superset/mcp_service/chart/tool/get_chart_data.py

@@ -25,7 +25,7 @@ from typing import Any, Dict, List, TYPE_CHECKING
 
 from fastmcp import Context
 from flask import current_app
-from superset_core.mcp import tool
+from superset_core.api.mcp import tool
 
 if TYPE_CHECKING:
     from superset.models.slice import Slice

superset/mcp_service/chart/tool/get_chart_info.py

@@ -23,7 +23,7 @@ import logging
 
 from fastmcp import Context
 from sqlalchemy.orm import subqueryload
-from superset_core.mcp import tool
+from superset_core.api.mcp import tool
 
 from superset.commands.exceptions import CommandException
 from superset.commands.explore.form_data.parameters import CommandParameters

superset/mcp_service/chart/tool/get_chart_preview.py

@@ -23,7 +23,7 @@ import logging
 from typing import Any, Dict, List, Protocol
 
 from fastmcp import Context
-from superset_core.mcp import tool
+from superset_core.api.mcp import tool
 
 from superset.commands.exceptions import CommandException
 from superset.exceptions import SupersetException

superset/mcp_service/chart/tool/list_charts.py

@@ -23,7 +23,7 @@ import logging
 from typing import cast, TYPE_CHECKING
 
 from fastmcp import Context
-from superset_core.mcp import tool
+from superset_core.api.mcp import tool
 
 if TYPE_CHECKING:
     from superset.models.slice import Slice

superset/mcp_service/chart/tool/update_chart.py

@@ -23,7 +23,7 @@ import logging
 import time
 
 from fastmcp import Context
-from superset_core.mcp import tool
+from superset_core.api.mcp import tool
 
 from superset.extensions import event_logger
 from superset.mcp_service.chart.chart_utils import (

superset/mcp_service/chart/tool/update_chart_preview.py

@@ -24,7 +24,7 @@ import time
 from typing import Any, Dict
 
 from fastmcp import Context
-from superset_core.mcp import tool
+from superset_core.api.mcp import tool
 
 from superset.extensions import event_logger
 from superset.mcp_service.chart.chart_utils import (

superset/mcp_service/dashboard/tool/add_chart_to_existing_dashboard.py

@@ -25,7 +25,7 @@ import logging
 from typing import Any, Dict
 
 from fastmcp import Context
-from superset_core.mcp import tool
+from superset_core.api.mcp import tool
 
 from superset.extensions import event_logger
 from superset.mcp_service.dashboard.constants import (

superset/mcp_service/dashboard/tool/generate_dashboard.py

@@ -25,7 +25,7 @@ import logging
 from typing import Any, Dict, List
 
 from fastmcp import Context
-from superset_core.mcp import tool
+from superset_core.api.mcp import tool
 
 from superset.extensions import event_logger
 from superset.mcp_service.dashboard.constants import (

superset/mcp_service/dashboard/tool/get_dashboard_info.py

@@ -27,7 +27,7 @@ from datetime import datetime, timezone
 
 from fastmcp import Context
 from sqlalchemy.orm import subqueryload
-from superset_core.mcp import tool
+from superset_core.api.mcp import tool
 
 from superset.dashboards.permalink.exceptions import DashboardPermalinkGetFailedError
 from superset.dashboards.permalink.types import DashboardPermalinkValue

superset/mcp_service/dashboard/tool/list_dashboards.py

@@ -26,7 +26,7 @@ import logging
 from typing import TYPE_CHECKING
 
 from fastmcp import Context
-from superset_core.mcp import tool
+from superset_core.api.mcp import tool
 
 if TYPE_CHECKING:
     from superset.models.dashboard import Dashboard

superset/mcp_service/dataset/tool/get_dataset_info.py

@@ -27,7 +27,7 @@ from datetime import datetime, timezone
 
 from fastmcp import Context
 from sqlalchemy.orm import joinedload, subqueryload
-from superset_core.mcp import tool
+from superset_core.api.mcp import tool
 
 from superset.extensions import event_logger
 from superset.mcp_service.dataset.schemas import (

superset/mcp_service/dataset/tool/list_datasets.py

@@ -26,7 +26,7 @@ import logging
 from typing import TYPE_CHECKING
 
 from fastmcp import Context
-from superset_core.mcp import tool
+from superset_core.api.mcp import tool
 
 if TYPE_CHECKING:
     from superset.connectors.sqla.models import SqlaTable

superset/mcp_service/explore/tool/generate_explore_link.py

@@ -26,7 +26,7 @@ from typing import Any, Dict
 from urllib.parse import parse_qs, urlparse
 
 from fastmcp import Context
-from superset_core.mcp import tool
+from superset_core.api.mcp import tool
 
 from superset.extensions import event_logger
 from superset.mcp_service.chart.chart_utils import (

superset/mcp_service/sql_lab/tool/execute_sql.py

@@ -28,8 +28,8 @@ import logging
 from typing import Any
 
 from fastmcp import Context
+from superset_core.api.mcp import tool
 from superset_core.api.types import CacheOptions, QueryOptions, QueryResult, QueryStatus
-from superset_core.mcp import tool
 
 from superset.errors import ErrorLevel, SupersetError, SupersetErrorType
 from superset.exceptions import SupersetErrorException, SupersetSecurityException

superset/mcp_service/sql_lab/tool/open_sql_lab_with_context.py

@@ -25,7 +25,7 @@ import logging
 from urllib.parse import urlencode
 
 from fastmcp import Context
-from superset_core.mcp import tool
+from superset_core.api.mcp import tool
 
 from superset.extensions import event_logger
 from superset.mcp_service.sql_lab.schemas import (

superset/mcp_service/system/prompts/quickstart.py

@@ -20,7 +20,7 @@ System prompts for general guidance
 """
 
 from flask import current_app
-from superset_core.mcp import prompt
+from superset_core.api.mcp import prompt
 
 
 def _get_app_name() -> str:

superset/mcp_service/system/tool/get_instance_info.py

@@ -23,7 +23,7 @@ InstanceInfoCore for flexible, extensible metrics calculation.
 import logging
 
 from fastmcp import Context
-from superset_core.mcp import tool
+from superset_core.api.mcp import tool
 
 from superset.extensions import event_logger
 from superset.mcp_service.mcp_core import InstanceInfoCore

superset/mcp_service/system/tool/get_schema.py

@@ -27,7 +27,7 @@ import logging
 from typing import Callable, Literal
 
 from fastmcp import Context
-from superset_core.mcp import tool
+from superset_core.api.mcp import tool
 
 from superset.extensions import event_logger
 from superset.mcp_service.common.schema_discovery import (

superset/mcp_service/system/tool/health_check.py

@@ -22,7 +22,7 @@ import logging
 import platform
 
 from flask import current_app
-from superset_core.mcp import tool
+from superset_core.api.mcp import tool
 
 from superset.extensions import event_logger
 from superset.mcp_service.system.schemas import HealthCheckResponse