More hints provided

Author: 3dgiordano

config/perfecto.py

@@ -15,6 +15,14 @@
 HELP_BASE_CONTENT_URL = "https://help.perfecto.io/perfecto-help/content/"
 
 
+def get_cloud_app_url(cloud_name: str) -> str:
+    return f"https://{cloud_name}.app.perfectomobile.com"
+
+
+def get_ai_scriptless_lab_url(cloud_name: str) -> str:
+    return f"{get_cloud_app_url(cloud_name)}/lab/scriptless-mobile/"
+
+
 def get_tenant_management_api_url(cloud_name: str) -> str:
     return f"https://{cloud_name}.app.perfectomobile.com/tenant-management-webapp/rest/v1/tenant-management/tenants/current"
 

formatters/user.py

@@ -1,19 +1,24 @@
 from typing import List, Any, Optional
 
+from config.perfecto import get_cloud_app_url
 from models.user import User
 
 
 def format_users(users: dict[str, Any], params: Optional[dict] = None) -> List[User]:
     first_name = users.get('firstName') or ''
     last_name = users.get('lastName') or ''
     display_name = f"{first_name} {last_name}".strip() or users.get("username", "Unknown")
-    
+    cloud_name = (params or {}).get("cloud_name") or ""
+    cloud_url = get_cloud_app_url(cloud_name) if cloud_name else ""
+
     formatted_users = [
         User(
             username=users.get("username") or "unknown",
             display_name=display_name,
             first_name=first_name,
             last_name=last_name,
+            cloud_name=cloud_name,
+            cloud_url=cloud_url,
         )
     ]
     return formatted_users

models/user.py

@@ -5,4 +5,6 @@ class User(BaseModel):
     username: str = Field(description="The unique identifier for the user")
     display_name: str = Field(description="Display name of the user")
     first_name: str = Field(description="First name of the user")
-    last_name: str = Field(description="Last name of the user")
+    last_name: str = Field(description="Last name of the user")
+    cloud_name: str = Field(description="Perfecto cloud name from MCP configuration (PERFECTO_CLOUD_NAME)")
+    cloud_url: str = Field(description="Perfecto cloud portal URL (https://{cloud_name}.app.perfectomobile.com)")

tools/ai_scriptless_manager.py

@@ -42,6 +42,7 @@
     set_element_enabled,
     split_item_key,
     test_file_name,
+    format_test_ui_location,
     update_element_arguments,
 )
 from tools.utils import api_request
@@ -62,6 +63,24 @@ def _append_step_path_refresh_notes(result: BaseResult) -> BaseResult:
     return result
 
 
+def _append_ui_access_info(
+        result: BaseResult,
+        cloud_name: str,
+        test_id: Optional[str] = None,
+) -> BaseResult:
+    if result.error:
+        return result
+    lab_url = perfecto.get_ai_scriptless_lab_url(cloud_name)
+    lines = [f"AI Scriptless UI (no per-test deep link): [{lab_url}]({lab_url})"]
+    if test_id:
+        lines.append(
+            "If you need to open it in the UI: Tests → Open or Manage tests, then navigate to "
+            f"{format_test_ui_location(test_id)}"
+        )
+    result.append_info(lines)
+    return result
+
+
 class AiScriptlessManager(Manager):
     def __init__(self, token: Optional[PerfectoToken], ctx: Context):
         super().__init__(token, ctx)
@@ -88,12 +107,13 @@ async def list_tests(self, args: dict[str, Any]) -> BaseResult:
             has_more=page_size - len(tests_result.result) <= 0,
         )
 
-        return BaseResult(
+        result = BaseResult(
             result=page_result,
             error=tests_result.error,
             warning=tests_result.warning,
             info=tests_result.info,
         )
+        return _append_ui_access_info(result, self.token.cloud_name)
 
     @token_verify
     async def list_filter_values(self, filter_names: list[str]) -> BaseResult:
@@ -217,9 +237,10 @@ async def view_test_structure(self, test_id: str) -> BaseResult:
             return BaseResult(error="test_id is required (itemKey from list_tests)")
         script_url = perfecto.get_ai_scriptless_api_url(self.token.cloud_name)
         script_url = script_url + f"/script?itemKey={quote(test_id, safe='')}"
-        return await api_request(self.token, "GET", endpoint=script_url,
+        result = await api_request(self.token, "GET", endpoint=script_url,
                                  result_formatter=format_test_structure,
                                  result_formatter_params={"item_key": test_id})
+        return _append_ui_access_info(result, self.token.cloud_name, test_id)
 
     @token_verify
     async def add_command(
@@ -321,7 +342,8 @@ async def create_test(self, name: str, folder: str = "My Folder", visibility: st
             return BaseResult(error="name is required")
         item_key = build_item_key(visibility, folder, name)
         script = new_empty_script()
-        return await persist_script(self.token, item_key, script)
+        result = await persist_script(self.token, item_key, script)
+        return _append_ui_access_info(result, self.token.cloud_name, item_key)
 
     @token_verify
     async def save_test_as(
@@ -342,9 +364,10 @@ async def save_test_as(
                 return payload_result
             script = payload_result.result.get("script", {})
         item_key = build_item_key(visibility, folder, name)
-        return _append_step_path_refresh_notes(
+        result = _append_step_path_refresh_notes(
             await persist_script(self.token, item_key, script, snapshot_comment=comment)
         )
+        return _append_ui_access_info(result, self.token.cloud_name, item_key)
 
     async def _add_structure(
             self,
@@ -759,6 +782,10 @@ def register(mcp, token: Optional[PerfectoToken]):
         test_id (str): Test itemKey from list_tests.
         name (str): Variable name to delete.
 Hints:
+- LICENSE: AI Scriptless actions require a Perfecto AI license on your cloud (administrator opt-in via feature toggle). Without it, AI commands and related MCP operations will not work. Desktop web test authoring additionally requires the Desktop Web license.
+- COVERAGE: DataTables, Scheduler (scheduled jobs), Embedded tests, and other advanced UI capabilities (folder management, rename test, restore snapshot, download as Appium, AI Assistant, Object Spy, per-step error policy, etc.) are not yet supported by this MCP tool. 
+- HELP: For product behavior and workarounds, use the perfecto_help tool: Filter by category_id='perfecto', subcategory_id_list=['ide'].
+- UI_ACCESS: No per-test URL exists. Only UI entry: cloud_url/lab/scriptless-mobile/ (cloud_url from perfecto_user read_user). For debugging or unsupported MCP tasks, link the lab URL and tell the user to open the test via Tests → Open or Manage tests using the folder tree and test name from list_tests (itemKey is MCP-only; the UI shows folders and names, not itemKey). Never invent other scriptless URLs.
 - When authoring or editing test steps, call list_commands first and follow the command selection policy in the info field.
 - step_path is a dot-separated positional path without spaces (0-based indices; b0=Then branch, b1=Else). Example: root step 3 is "3"; first step inside Then of condition at 5 is "5.b0.0". Perfecto does not persist paths; they change when steps are inserted, moved, or deleted. Always call view_test_structure before the next structure edit; do not reuse step_path from a previous mutation response.
 - Use parent_path on add_command with the step_path of a LogicalStep, Loop, or Branch from view_test_structure.

tools/ai_scriptless_script.py

@@ -36,6 +36,24 @@ def test_file_name(item_key: str) -> str:
     return path.rsplit("/", 1)[-1]
 
 
+VISIBILITY_UI_ROOT = {
+    "PRIVATE": "My Tests",
+    "PUBLIC": "Public Tests",
+    "GROUP": "Group Tests",
+}
+
+
+def format_test_ui_location(item_key: str) -> str:
+    """Map itemKey to folder/test labels shown in the AI Scriptless Open Test UI."""
+    visibility, path = split_item_key(item_key)
+    root = VISIBILITY_UI_ROOT.get(visibility, visibility)
+    file_name = test_file_name(item_key).removesuffix(".xml")
+    folder = path.rsplit("/", 1)[0] if "/" in path else ""
+    if folder:
+        return f'"{root}" → folder "{folder}" → test "{file_name}"'
+    return f'"{root}" → test "{file_name}"'
+
+
 def build_snapshot_search_body(test_id: str) -> dict[str, Any]:
     visibility, artifact_id = split_item_key(test_id)
     return {

tools/user_manager.py

@@ -6,7 +6,7 @@
 from pydantic import Field
 
 from config import perfecto
-from config.perfecto import TOOLS_PREFIX, SUPPORT_MESSAGE
+from config.perfecto import TOOLS_PREFIX, SUPPORT_MESSAGE, get_cloud_app_url
 from config.token import PerfectoToken, token_verify
 from formatters.user import format_users
 from models.manager import Manager
@@ -22,7 +22,17 @@ def __init__(self, token: Optional[PerfectoToken], ctx: Context):
     async def read_user(self) -> BaseResult:
         user_url = perfecto.get_user_management_api_url(self.token.cloud_name)
         user_url = user_url + "/current"
-        return await api_request(self.token, "GET", endpoint=user_url, result_formatter=format_users)
+        cloud_url = get_cloud_app_url(self.token.cloud_name)
+        result = await api_request(
+            self.token,
+            "GET",
+            endpoint=user_url,
+            result_formatter=format_users,
+            result_formatter_params={"cloud_name": self.token.cloud_name},
+        )
+        if not result.error:
+            result.append_info([f"Connected Perfecto cloud: [{cloud_url}]({cloud_url})"])
+        return result
 
 
 def register(mcp, token: Optional[PerfectoToken]):
@@ -31,7 +41,9 @@ def register(mcp, token: Optional[PerfectoToken]):
         description="""
 Operations on user information.
 Actions:
-- read_user: Read a current user information from Perfecto.
+- read_user: Read the current user and connected Perfecto cloud environment (cloud_name, cloud_url from PERFECTO_CLOUD_NAME).
+Hints:
+- Always render cloud_url as a markdown link when presenting the environment to the user.
 """
     )
     async def user(