feat(mcp): add typed Pydantic response schemas to generate_explore_link tool

superset/mcp_service/explore/schemas.py

@@ -0,0 +1,93 @@
+# 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.
+
+"""
+Pydantic schemas for explore-related MCP tool inputs and outputs.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class GenerateExploreLinkResponse(BaseModel):
+    """
+    Output schema for the generate_explore_link tool.
+
+    On success, url is a fully-qualified Superset Explore URL the user can
+    open immediately.  form_data_key can be used to reconstruct or share the
+    same configuration.  On failure, url is empty and error contains a
+    human-readable description of what went wrong.
+    """
+
+    url: str = Field(
+        ...,
+        description=(
+            "Explore URL — open in a browser to view the interactive chart. "
+            "Empty string on failure."
+        ),
+    )
+    form_data: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Raw Superset form_data dict that was encoded into the URL.",
+    )
+    form_data_key: str | None = Field(
+        None,
+        description=(
+            "Short cache key that represents this form_data configuration. "
+            "Can be passed to the Explore UI as ?form_data_key=<key>."
+        ),
+    )
+    error: str | None = Field(
+        None,
+        description="Human-readable error message when generation fails, else null.",
+    )
+    success: bool = Field(
+        True,
+        description="True when a valid URL was produced, False on any error.",
+    )
+
+
+class ExploreLinkError(BaseModel):
+    """
+    Structured error returned when explore link generation fails.
+
+    error_type distinguishes actionable failure modes so callers can
+    respond appropriately without parsing the free-text error message.
+    """
+
+    error: str = Field(..., description="Human-readable description of the failure.")
+    error_type: Literal[
+        "dataset_not_found",
+        "generation_failed",
+        "permission_denied",
+    ] = Field(
+        ...,
+        description=(
+            "Machine-readable failure category. "
+            "'dataset_not_found' — dataset_id does not exist; use list_datasets. "
+            "'generation_failed' — URL could not be constructed from the config. "
+            "'permission_denied' — current user lacks access to the dataset."
+        ),
+    )
+    dataset_id: int | str | None = Field(
+        None,
+        description="The dataset_id from the original request, for correlation.",
+    )
+    success: bool = Field(False)

superset/mcp_service/explore/tool/generate_explore_link.py

@@ -22,8 +22,6 @@
 chart configuration.
 """
 
-from typing import Any, Dict
-
 from fastmcp import Context
 from superset_core.mcp.decorators import tool, ToolAnnotations
 
@@ -33,9 +31,8 @@
     generate_explore_link as generate_url,
     map_config_to_form_data,
 )
-from superset.mcp_service.chart.schemas import (
-    GenerateExploreLinkRequest,
-)
+from superset.mcp_service.chart.schemas import GenerateExploreLinkRequest
+from superset.mcp_service.explore.schemas import GenerateExploreLinkResponse
 
 
 @tool(
@@ -49,7 +46,7 @@
 )
 async def generate_explore_link(
     request: GenerateExploreLinkRequest, ctx: Context
-) -> Dict[str, Any]:
+) -> GenerateExploreLinkResponse:
     """Generate explore URL for interactive visualization.
 
     PREFERRED TOOL for most visualization requests.
@@ -121,15 +118,16 @@ async def generate_explore_link(
                 await ctx.warning(
                     "Dataset not found: dataset_id=%s" % (request.dataset_id,)
                 )
-                return {
-                    "url": "",
-                    "form_data": {},
-                    "form_data_key": None,
-                    "error": (
+                return GenerateExploreLinkResponse(
+                    url="",
+                    form_data={},
+                    form_data_key=None,
+                    error=(
                         f"Dataset not found: {request.dataset_id}. "
                         "Use list_datasets to find valid dataset IDs."
                     ),
-                }
+                    success=False,
+                )
 
         await ctx.report_progress(2, 4, "Converting configuration to form data")
         with event_logger.log_context(action="mcp.generate_explore_link.form_data"):
@@ -184,12 +182,13 @@ async def generate_explore_link(
             % (len(explore_url or ""), request.dataset_id, form_data_key)
         )
 
-        return {
-            "url": explore_url,
-            "form_data": form_data,
-            "form_data_key": form_data_key,
-            "error": None,
-        }
+        return GenerateExploreLinkResponse(
+            url=explore_url,
+            form_data=form_data,
+            form_data_key=form_data_key,
+            error=None,
+            success=True,
+        )
 
     except Exception as e:
         await ctx.error(
@@ -201,9 +200,10 @@ async def generate_explore_link(
                 str(e),
             )
         )
-        return {
-            "url": "",
-            "form_data": {},
-            "form_data_key": None,
-            "error": f"Failed to generate explore link: {str(e)}",
-        }
+        return GenerateExploreLinkResponse(
+            url="",
+            form_data={},
+            form_data_key=None,
+            error=f"Failed to generate explore link: {str(e)}",
+            success=False,
+        )