Feature/helios onboarding prompt (#71)

Rodriguespn · web-flow · commit 0ad046d37c2f · 2025-07-14T18:15:08.000+01:00
* enable terminate virtual workspace tool

* fix terminate virtual workspace tool

* adapt terminate virtual workspace if elicitation is not supported by client

* new onboarding prompt

* add onboarding prompt
diff --git a/README.md b/README.md
@@ -6,6 +6,8 @@
 
 With MCP, you can use Claude Desktop, Cursor, or any compatible MCP client to interact with SingleStore using natural language, making it easier to perform complex operations effortlessly.
 
+💡 **Pro Tip**: Not sure what the MCP server can do? Just type `/help` in your chat! The MCP server exposes its capabilities through tools that the LLM understands, so you can get a complete overview of available features or ask specific questions like "How do I work with SingleStore workspaces?" The LLM will guide you through the available features and help you accomplish your tasks.
+
 ## Requirements
 
 - Python >= v3.11.0
diff --git a/changelog/0.5.0.md b/changelog/0.5.0.md
@@ -0,0 +1,7 @@
+# [0.5.0] - xxxx-xx-xx
+
+## Added
+
+- Enabled `terminate_virtual_workspace` tool with safety confirmation ellicitation
+- New `onboarding_user` prompt to guide users through the initial helios setup process
+- New `help` prompt to provide an overview of the SingleStore MCP server capabilities, available tools, resources, and prompts
diff --git a/src/api/common.py b/src/api/common.py
@@ -216,7 +216,7 @@ def build_request_endpoint(endpoint: str, params: dict = None):
         if org_id is not None:
             params["organizationID"] = org_id
 
-        if params and type == "GET":  # Only add query params for GET requests
+        if params:
             url += "?"
             for key, value in params.items():
                 url += f"{key}={value}&"
@@ -260,10 +260,7 @@ def build_request_endpoint(endpoint: str, params: dict = None):
     if request.status_code != 200:
         raise HTTPException(request.status_code, request.text)
 
-    try:
-        return request.json()
-    except ValueError:
-        raise ValueError(f"Invalid JSON response: {request.text}")
+    return request.json()
 
 
 def __find_workspace_group(workspace_group_identifier: str):
diff --git a/src/api/prompts/prompts.py b/src/api/prompts/prompts.py
@@ -1,6 +1,107 @@
 from src.api.prompts.types import Prompt
+from mcp.server.fastmcp.prompts.base import AssistantMessage, UserMessage
 
-prompts_definitions = []
+
+def onboarding_helios_user() -> list:
+    """
+    Guide new users through SingleStore setup process:
+    1. Account setup and organization selection
+    2. Workspace creation with sample data
+    3. Basic SQL tutorial
+    """
+    return [
+        AssistantMessage("Welcome to SingleStore! Let's get you started."),
+        AssistantMessage(
+            "Step 1: Make sure you are authenticated and have access to an organization. If you haven't, please run the login command or use the authentication flow in your client."
+        ),
+        AssistantMessage(
+            "Step 2: Create a starter workspace and database. You can do this by running the following command or using the UI:"
+        ),
+        UserMessage(
+            "Let's create a starter workspace if I don't have one yet. Then, populate the database with sample data.",
+        ),
+        AssistantMessage(
+            "Step 3: Load sample data into your new database. Try running this SQL in your virtual workspace:"
+        ),
+        AssistantMessage(
+            """\
+CREATE TABLE IF NOT EXISTS sample_customers (
+    id INT NOT NULL,
+    name VARCHAR(100),
+    email VARCHAR(100),
+    country VARCHAR(50),
+    PRIMARY KEY (id)
+);
+
+INSERT INTO sample_customers VALUES
+    (1, 'John Doe', 'john@example.com', 'USA'),
+    (2, 'Jane Smith', 'jane@example.com', 'Canada'),
+    (3, 'Alice Johnson', 'alice@example.com', 'UK');
+"""
+        ),
+        AssistantMessage("Step 4: Try your first query!"),
+        UserMessage("Let's run a simple select query to see our data."),
+        AssistantMessage(
+            """Here are some ways to explore your SingleStore database:
+
+1. Performance Monitoring & Analysis:
+   - View query history and performance metrics in SingleStore Helios Portal
+   - Try EXPLAIN before queries to analyze execution plans
+
+2. Data Management:
+   - Experiment with different table types (rowstore vs. columnstore)
+   - Try bulk data loading with LOAD DATA
+   - Explore JSON and geospatial data types
+
+3. Optimization Features:
+   - Create indexes for better query performance
+   - Use window functions for analytics
+   - Try full-text search capabilities
+
+4. Development Integration:
+   - Connect using various client libraries (Python, Drizzle ORM)
+   - Explore SingleStore Notebooks for interactive analysis
+
+Which area would you like to explore first?"""
+        ),
+    ]
+
+
+def help() -> list:
+    """
+    Provides an overview of the SingleStore MCP server capabilities,
+    available tools, resources, and prompts.
+    """
+    return [
+        AssistantMessage(
+            "Welcome to the SingleStore Model Context Protocol (MCP) Server! 👋\nDo not call any tools! The user only wnat's to list them, not perform any action"
+        ),
+        AssistantMessage(
+            "Let me show you what tools , resources, and prompts are available to you."
+        ),
+        AssistantMessage(
+            "Organize the response in the following format:\n"
+            "- **Tools**: List of available tools with brief descriptions\n"
+            "- **Resources**: Links to documentation, tutorials, and guides\n"
+            "- **Prompts**: List of available prompts with their titles and descriptions"
+        ),
+        UserMessage("List all the MCP tools, resources, and prompts available to me."),
+        AssistantMessage(
+            "Need help with something specific? Just ask and I'll guide you through it!"
+        ),
+    ]
+
+
+prompts_definitions = [
+    {
+        "title": "Helios User Onboarding",
+        "func": onboarding_helios_user,
+    },
+    {
+        "title": "Help",
+        "func": help,
+    },
+]
 
 # Export the prompts using create_from_dict for consistency
 prompts = [Prompt.create_from_dict(prompt) for prompt in prompts_definitions]
diff --git a/src/api/prompts/register.py b/src/api/prompts/register.py
@@ -1,5 +1,4 @@
-from functools import wraps
-from typing import Callable, List
+from typing import List
 from mcp.server.fastmcp import FastMCP
 
 from src.api.common import filter_mcp_concepts
@@ -8,22 +7,11 @@
 from .prompts import prompts as prompts_list
 
 
-def create_prompts_wrapper(func: Callable, name: str, description: str):
-    @wraps(func)
-    async def wrapper(*args, **kwargs):
-        return func(*args, **kwargs)
-
-    wrapper.__name__ = name
-    wrapper.__doc__ = description
-    return wrapper
-
-
 def register_prompts(mcp: FastMCP) -> None:
     filtered_prompts: List[Prompt] = filter_mcp_concepts(prompts_list)
 
     for prompt in filtered_prompts:
         func = prompt.func
-        # Add context support for MCP
-        wrapper = create_prompts_wrapper(func, func.__name__, func.__doc__ or "")
-
-        mcp.prompt(name=func.__name__, description=func.__doc__ or "")(wrapper)
+        mcp.prompt(
+            name=func.__name__, description=func.__doc__ or "", title=prompt.title
+        )(func)
diff --git a/src/api/tools/tools.py b/src/api/tools/tools.py
@@ -2040,95 +2040,123 @@ async def terminate_virtual_workspace(
     workspace_id: str,
 ) -> Dict[str, Any]:
     """
-    Terminate a virtual (starter) workspace using the SingleStore SDK.
+    Permanently delete a virtual workspace in SingleStore with safety confirmations.
 
-    This tool provides a safe and reliable way to terminate virtual workspaces,
-    with proper error handling and confirmation of the termination status.
+    ⚠️  WARNING: This action CANNOT be undone. All workspace data will be permanently lost.
+    Make sure to backup important data before proceeding.
 
-    ⚠️  WARNING: This action is permanent and cannot be undone. All data in the
-    workspace will be lost. Make sure to backup any important data before terminating.
+    Safety Features:
+    - Requires explicit user confirmation (if elicitation is supported)
+    - Validates workspace existence
+    - Provides warning messages
+    - Includes error handling
 
     Args:
-        workspace_id: Unique identifier of the virtual workspace to terminate
+        ctx: Context for user interaction and logging
+        workspace_id: Workspace identifier (format: "ws-" followed by alphanumeric chars)
 
     Returns:
-        Dictionary with termination status and details including:
-        - status: "success" or "error"
-        - message: Human-readable description of the result
-        - workspace_id: ID of the terminated workspace
-        - workspace_name: Name of the terminated workspace (if available)
-        - termination_time: Timestamp when termination was initiated
-
-    Benefits over direct API calls:
-    - Automatic retry logic and error handling
-    - Proper validation of workspace existence
-    - Detailed error messages and status reporting
-    - Built-in authentication handling
+        {
+            "status": "success" | "error" | "cancelled",
+            "message": str,  # Human-readable result
+            "workspace_id": str,
+            "workspace_name": str,  # If available
+            "termination_time": str,  # ISO 8601 (if successful)
+            "error": str  # If status="error"
+        }
 
-    Example Usage:
+    Example:
     ```python
-    result = terminate_virtual_workspace(
-        ctx=ctx,
-        workspace_id="ws-abc123def456"
-    )
+    result = await terminate_virtual_workspace(ctx, "ws-abc123")
     if result["status"] == "success":
-        print(f"Workspace {result['workspace_name']} terminated successfully")
-    else:
-        print(f"Failed to terminate workspace: {result['message']}")
+        print(f"Workspace {result['workspace_name']} terminated")
     ```
+
+    Related:
+    - list_virtual_workspaces()
+    - create_starter_workspace()
     """
     # Validate workspace ID format
     validated_workspace_id = validate_workspace_id(workspace_id)
 
-    await ctx.info(f"Terminating virtual workspace with ID: {validated_workspace_id}")
-
     settings = config.get_settings()
     user_id = config.get_user_id()
 
-    # Track analytics event
-    settings.analytics_manager.track_event(
-        user_id,
-        "tool_calling",
-        {
-            "name": "terminate_virtual_workspace",
-            "workspace_id": validated_workspace_id,
-        },
-    )
-
     try:
-        # First, try to get the workspace details before termination
-        workspace_name = None
-        try:
-            starter_workspace_data = build_request(
-                "GET", f"sharedtier/virtualWorkspaces/{validated_workspace_id}"
+        starter_workspace_data = build_request(
+            "GET", f"sharedtier/virtualWorkspaces/{validated_workspace_id}"
+        )
+        workspace_name = starter_workspace_data.get("name")
+        await ctx.info(
+            f"Found virtual workspace '{workspace_name}' (ID: {validated_workspace_id})"
+        )
+
+        class TerminationConfirmation(BaseModel):
+            """Schema for collecting organization selection."""
+
+            confirm: bool = Field(
+                description="Do you really want to terminate this virtual workspace?",
+                default=False,
             )
-            workspace_name = starter_workspace_data.get("name")
+
+        # Check if elicitation is supported
+        elicit_result, error = await try_elicitation(
+            ctx=ctx,
+            message=f"⚠️ **WARNING**: You are about to terminate the virtual workspace '{workspace_name}'.\n\n"
+            "This action is permanent and cannot be undone. All data in the workspace will be lost.\n\n"
+            "Do you want to proceed with the termination?",
+            schema=TerminationConfirmation,
+        )
+
+        # Skip confirmation if elicitation is not supported
+        if error == ElicitationError.NOT_SUPPORTED:
             await ctx.info(
-                f"Found virtual workspace '{workspace_name}' (ID: {validated_workspace_id})"
-            )
-        except Exception as e:
-            # If we can't get the workspace, it might not exist or already be terminated
-            ctx.warning(f"Could not retrieve workspace details: {str(e)}")
-            raise ValueError(
-                f"Virtual workspace '{validated_workspace_id}' does not exist or has already been terminated."
+                "Proceeding with termination without confirmation since interactive confirmation is not supported."
             )
+        else:
+            # Only check confirmation if elicitation was supported
+            if not (
+                elicit_result.status == "success"
+                and elicit_result.data
+                and elicit_result.data.confirm
+            ):
+                return {
+                    "status": "cancelled",
+                    "message": "Workspace termination was cancelled by the user",
+                    "workspace_id": validated_workspace_id,
+                    "workspace_name": workspace_name,
+                }
+
+        # Track analytics event
+        settings.analytics_manager.track_event(
+            user_id,
+            "tool_calling",
+            {
+                "name": "terminate_virtual_workspace",
+                "workspace_id": validated_workspace_id,
+            },
+        )
+
+        await ctx.info(
+            f"Proceeding with termination of virtual workspace: {validated_workspace_id}"
+        )
 
         # Terminate the virtual workspace
         build_request(
             "DELETE", f"sharedtier/virtualWorkspaces/{validated_workspace_id}"
         )
 
-        termination_time = datetime.now().isoformat()
-
-        success_message = f"Virtual workspace '{workspace_name or validated_workspace_id}' terminated successfully"
+        success_message = (
+            f"Virtual workspace '{workspace_name}' terminated successfully"
+        )
         await ctx.info(success_message)
 
         return {
             "status": "success",
             "message": success_message,
             "workspace_id": validated_workspace_id,
             "workspace_name": workspace_name,
-            "termination_time": termination_time,
+            "termination_time": datetime.now().isoformat(),
         }
 
     except Exception as e:
@@ -2252,7 +2280,7 @@ async def set_organization(ctx: Context, organization_id: str) -> dict:
     {"func": complete_database_migration, "internal": True},
     # This tool is under development and not yet available for public use
     {"func": create_starter_workspace, "internal": True},
-    {"func": terminate_virtual_workspace, "internal": True},
+    {"func": terminate_virtual_workspace},
 ]
 
 # Export the tools
diff --git a/src/commands/start.py b/src/commands/start.py
@@ -2,6 +2,7 @@
 from mcp.server.fastmcp import FastMCP
 from mcp.server.auth.settings import AuthSettings, ClientRegistrationOptions
 
+from src.api.prompts.register import register_prompts
 from src.auth.callback import make_auth_callback_handler
 from src.api.tools import register_tools
 from src.auth.provider import SingleStoreOAuthProvider
@@ -65,6 +66,7 @@ def start_command(transport: str, host: str):
 
     register_tools(mcp)
     register_resources(mcp)
+    register_prompts(mcp)
 
     if settings.is_remote:
         # Register the callback handler with the captured oauth_provider
