@josephyan/qingflow-app-builder-mcp 0.2.0-beta.7 → 0.2.0-beta.71

package/src/qingflow_mcp/tools/app_tools.py

@@ -9,7 +9,7 @@ from ..backend_client import BackendRequestContext
 from ..config import DEFAULT_PROFILE
 from ..errors import QingflowApiError, raise_tool_error
 from ..json_types import JSONObject
-from ..list_type_labels import get_app_publish_status_label
+from ..list_type_labels import SYSTEM_VIEW_DEFINITIONS, get_app_publish_status_label
 from .base import ToolBase
 
 
@@ -23,6 +23,10 @@ class AppTools(ToolBase):
         def app_search(profile: str = DEFAULT_PROFILE, keyword: str = "", page_num: int = 1, page_size: int = 50) -> JSONObject:
             return self.app_search(profile=profile, keyword=keyword, page_num=page_num, page_size=page_size)
 
+        @mcp.tool()
+        def app_get(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
+            return self.app_get(profile=profile, app_key=app_key)
+
         @mcp.tool()
         def app_get_base(profile: str = DEFAULT_PROFILE, app_key: str = "", include_raw: bool = False) -> JSONObject:
             return self.app_get_base(profile=profile, app_key=app_key, include_raw=include_raw)
@@ -76,14 +80,20 @@ class AppTools(ToolBase):
             return self.app_publish(profile=profile, app_key=app_key, payload=payload or {})
 
     def app_list(self, *, profile: str, ship_auth: bool = False) -> JSONObject:
-        """Get all apps with full hierarchy from tag/apps endpoint."""
+        """List current-user visible apps in the selected workspace."""
         def runner(session_profile, context):
             result = self.backend.request("GET", context, "/tag/apps")
-            return {
+            items, source_shape = self._extract_visible_apps(result)
+            response = {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
-                "items": result,
+                "items": items,
+                "count": len(items),
+                "source_shape": source_shape,
             }
+            if ship_auth:
+                response["raw"] = result
+            return response
 
         return self._run(profile, runner)
 
@@ -98,19 +108,20 @@ class AppTools(ToolBase):
             
             result = self.backend.request("GET", context, "/app/item", params=params)
             
-            # Extract app list from the response
             apps = []
             if isinstance(result, dict):
                 items = result.get("list", [])
                 for item in items:
                     if isinstance(item, dict):
-                        apps.append({
-                            "app_key": item.get("appKey"),
-                            "title": item.get("title") or item.get("formTitle"),
-                            "form_id": item.get("formId"),
-                            "tag_id": item.get("tagId"),
-                            "group_id": item.get("groupId"),
-                        })
+                        normalized = self._normalize_visible_app(
+                            item,
+                            package_tag_id=_coerce_positive_int(item.get("tagId")),
+                            package_name=str(item.get("tagName") or "").strip() or None,
+                            group_id=_coerce_positive_int(item.get("groupId")),
+                            group_name=str(item.get("groupName") or "").strip() or None,
+                        )
+                        if normalized is not None:
+                            apps.append(normalized)
             
             return {
                 "profile": profile,
@@ -119,11 +130,76 @@ class AppTools(ToolBase):
                 "page_num": page_num,
                 "page_size": page_size,
                 "total": result.get("total") if isinstance(result, dict) else len(apps),
+                "items": apps,
                 "apps": apps,
             }
 
         return self._run(profile, runner)
 
+    def app_get(self, *, profile: str, app_key: str) -> JSONObject:
+        self._require_app_key(app_key)
+
+        def runner(session_profile, context):
+            warnings: list[JSONObject] = []
+            app_name = app_key
+            base_info: JSONObject | None = None
+
+            try:
+                base_info = self.backend.request("GET", context, f"/app/{app_key}/baseInfo")
+                if isinstance(base_info, dict):
+                    app_name = (
+                        str(base_info.get("formTitle") or base_info.get("title") or base_info.get("appName") or app_key).strip()
+                        or app_key
+                    )
+            except QingflowApiError as exc:
+                if exc.backend_code not in {40002, 40027}:
+                    raise
+                warnings.append(
+                    {
+                        "code": "APP_BASE_INFO_UNAVAILABLE",
+                        "message": f"app_get could not load base info for {app_key}; using app_key as app_name.",
+                    }
+                )
+
+            try:
+                can_create = self._probe_create_access(context, app_key)
+            except QingflowApiError as exc:
+                can_create = False
+                warnings.append(
+                    {
+                        "code": "APP_CREATE_PROBE_UNVERIFIED",
+                        "message": (
+                            f"app_get could not fully verify create access for {app_key}: "
+                            f"{exc.message or 'probe failed'}"
+                        ),
+                    }
+                )
+            accessible_views, system_view_warnings = self._resolve_accessible_system_views(context, app_key)
+            warnings.extend(system_view_warnings)
+            accessible_views.extend(self._resolve_accessible_custom_views(context, app_key))
+            import_capability, import_warnings = _derive_import_capability(base_info)
+            warnings.extend(import_warnings)
+            editability, editability_warnings = _derive_editability(base_info)
+            warnings.extend(editability_warnings)
+
+            return {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "ok": True,
+                "request_route": {"base_url": context.base_url, "qf_version": context.qf_version},
+                "warnings": warnings,
+                "data": {
+                    "app_key": app_key,
+                    "app_name": app_name,
+                    "can_create": can_create,
+                    "import_capability": import_capability,
+                    "editability": editability,
+                    "accessible_views": accessible_views,
+                },
+            }
+
+        return self._run(profile, runner)
+
     def app_get_base(self, *, profile: str, app_key: str, include_raw: bool = False) -> JSONObject:
         self._require_app_key(app_key)
 
@@ -208,6 +284,42 @@ class AppTools(ToolBase):
 
         return self._run(profile, runner)
 
+    def app_get_apply_base_info(self, *, profile: str, app_key: str, list_type: int) -> JSONObject:
+        self._require_app_key(app_key)
+        if not isinstance(list_type, int) or isinstance(list_type, bool) or list_type <= 0:
+            raise_tool_error(QingflowApiError.config_error("list_type must be a positive integer"))
+
+        def runner(session_profile, context):
+            result = self.backend.request("GET", context, f"/app/{app_key}/apply/baseInfo", params={"type": list_type})
+            return {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "app_key": app_key,
+                "list_type": list_type,
+                "result": result,
+            }
+
+        return self._run(profile, runner)
+
+    def app_update_apply_config(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        self._require_app_key(app_key)
+        body = self._require_dict(payload)
+
+        def runner(session_profile, context):
+            result = self.backend.request("POST", context, f"/app/{app_key}/apply/config", json_body=body)
+            return self._attach_human_review_notice(
+                {
+                    "profile": profile,
+                    "ws_id": session_profile.selected_ws_id,
+                    "app_key": app_key,
+                    "result": result,
+                },
+                operation="update",
+                target="app apply list configuration",
+            )
+
+        return self._run(profile, runner)
+
     def app_update_form_schema(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
         self._require_app_key(app_key)
         body = self._require_dict(payload)
@@ -305,6 +417,83 @@ class AppTools(ToolBase):
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
 
+    def _probe_create_access(self, context: BackendRequestContext, app_key: str) -> bool:
+        try:
+            self.backend.request(
+                "GET",
+                context,
+                f"/app/{app_key}/form",
+                params={"type": 2, "beingApply": True},
+            )
+            return True
+        except QingflowApiError as exc:
+            if exc.backend_code in {40002, 40027}:
+                return False
+            raise
+
+    def _probe_list_type_access(self, context: BackendRequestContext, app_key: str, list_type: int) -> bool:
+        try:
+            self.backend.request(
+                "POST",
+                context,
+                f"/app/{app_key}/apply/filter",
+                json_body={"type": list_type, "pageNum": 1, "pageSize": 1},
+            )
+            return True
+        except QingflowApiError as exc:
+            if exc.backend_code in {40002, 40027}:
+                return False
+            raise
+
+    def _resolve_accessible_system_views(self, context: BackendRequestContext, app_key: str) -> tuple[list[JSONObject], list[JSONObject]]:
+        items: list[JSONObject] = []
+        warnings: list[JSONObject] = []
+        for view_id, list_type, name in SYSTEM_VIEW_DEFINITIONS:
+            try:
+                can_access = self._probe_list_type_access(context, app_key, list_type)
+            except QingflowApiError as exc:
+                warnings.append(
+                    {
+                        "code": "SYSTEM_VIEW_PROBE_UNVERIFIED",
+                        "message": (
+                            f"app_get skipped system view '{name}' because access probing failed: "
+                            f"{exc.message or 'probe failed'}"
+                        ),
+                        "view_id": view_id,
+                        "list_type": list_type,
+                    }
+                )
+                continue
+            if not can_access:
+                continue
+            items.append({"view_id": view_id, "name": name, "kind": "system", "analysis_supported": True})
+        return items, warnings
+
+    def _resolve_accessible_custom_views(self, context: BackendRequestContext, app_key: str) -> list[JSONObject]:
+        try:
+            payload = self.backend.request("GET", context, f"/app/{app_key}/view/viewList")
+        except QingflowApiError as exc:
+            if exc.backend_code in {40002, 40027}:
+                return []
+            raise
+
+        items: list[JSONObject] = []
+        for item in _normalize_view_list(payload):
+            view_key = str(item.get("viewKey") or "").strip()
+            if not view_key:
+                continue
+            normalized: JSONObject = {
+                "view_id": f"custom:{view_key}",
+                "name": str(item.get("viewName") or view_key).strip() or view_key,
+                "kind": "custom",
+            }
+            view_type = str(item.get("viewType") or item.get("viewgraphType") or "").strip()
+            if view_type:
+                normalized["view_type"] = view_type
+            normalized["analysis_supported"] = _analysis_supported_for_view_type(view_type or None)
+            items.append(normalized)
+        return items
+
     def _compact_base_info(self, result: dict[str, Any]) -> JSONObject:
         publish_status = result.get("appPublishStatus")
         auth = result.get("auth") if isinstance(result.get("auth"), dict) else {}
@@ -424,6 +613,88 @@ class AppTools(ToolBase):
         }
         return {key: value for key, value in compact.items() if value is not None}
 
+    def _extract_visible_apps(self, result: Any) -> tuple[list[JSONObject], str]:
+        apps: list[JSONObject] = []
+        seen: set[str] = set()
+
+        def walk(
+            node: Any,
+            *,
+            package_tag_id: int | None = None,
+            package_name: str | None = None,
+            group_id: int | None = None,
+            group_name: str | None = None,
+        ) -> None:
+            if isinstance(node, list):
+                for item in node:
+                    walk(
+                        item,
+                        package_tag_id=package_tag_id,
+                        package_name=package_name,
+                        group_id=group_id,
+                        group_name=group_name,
+                    )
+                return
+            if not isinstance(node, dict):
+                return
+
+            next_package_tag_id = _coerce_positive_int(node.get("tagId")) or package_tag_id
+            next_package_name = str(node.get("tagName") or "").strip() or package_name
+            next_group_id = _coerce_positive_int(node.get("groupId")) or group_id
+            next_group_name = str(node.get("groupName") or node.get("groupTitle") or "").strip() or group_name
+
+            normalized = self._normalize_visible_app(
+                node,
+                package_tag_id=next_package_tag_id,
+                package_name=next_package_name,
+                group_id=next_group_id,
+                group_name=next_group_name,
+            )
+            if normalized is not None:
+                app_key = str(normalized.get("app_key") or "").strip()
+                if app_key and app_key not in seen:
+                    seen.add(app_key)
+                    apps.append(normalized)
+
+            for value in node.values():
+                if isinstance(value, (list, dict)):
+                    walk(
+                        value,
+                        package_tag_id=next_package_tag_id,
+                        package_name=next_package_name,
+                        group_id=next_group_id,
+                        group_name=next_group_name,
+                    )
+
+        walk(result)
+        return apps, type(result).__name__
+
+    def _normalize_visible_app(
+        self,
+        item: dict[str, Any],
+        *,
+        package_tag_id: int | None,
+        package_name: str | None,
+        group_id: int | None,
+        group_name: str | None,
+    ) -> JSONObject | None:
+        app_key = str(item.get("appKey") or item.get("app_key") or "").strip()
+        if not app_key:
+            return None
+        title = str(item.get("title") or item.get("formTitle") or item.get("appName") or item.get("name") or app_key).strip() or app_key
+        tag_ids = item.get("tagIds") if isinstance(item.get("tagIds"), list) else []
+        compact = {
+            "app_key": app_key,
+            "title": title,
+            "form_id": item.get("formId"),
+            "tag_id": package_tag_id,
+            "package_name": package_name,
+            "group_id": group_id,
+            "group_name": group_name,
+            "tag_ids": [value for value in (_coerce_positive_int(tag_id) for tag_id in tag_ids) if value is not None],
+        }
+        return {key: value for key, value in compact.items() if value not in (None, [], "", {})}
+
     def _count_auth_members(self, auth_payload: Any, member_key: str) -> int:
         if not isinstance(auth_payload, dict):
             return 0
@@ -470,3 +741,139 @@ def _normalize_form_type(value: int | str) -> int:
     if text in FORM_TYPE_ALIASES:
         return FORM_TYPE_ALIASES[text]
     raise_tool_error(QingflowApiError.config_error("form_type must be a positive integer or one of: default, form, schema, new, draft, edit"))
+
+
+def _normalize_view_list(payload: Any) -> list[JSONObject]:
+    if not isinstance(payload, list):
+        return []
+    flattened: list[JSONObject] = []
+    for group in payload:
+        if not isinstance(group, dict):
+            continue
+        view_list = group.get("viewList")
+        if not isinstance(view_list, list):
+            continue
+        for item in view_list:
+            if isinstance(item, dict) and item.get("viewKey"):
+                flattened.append(item)
+    return flattened
+
+
+def _analysis_supported_for_view_type(view_type: str | None) -> bool:
+    normalized = str(view_type or "").strip().lower()
+    if not normalized:
+        return True
+    return normalized not in {"boardview", "ganttview"}
+
+
+def _derive_import_capability(base_info: Any) -> tuple[JSONObject, list[JSONObject]]:
+    warnings: list[JSONObject] = []
+    if not isinstance(base_info, dict):
+        warnings.append(
+            {
+                "code": "IMPORT_CAPABILITY_UNAVAILABLE",
+                "message": "app_get could not determine import capability because baseInfo was unavailable.",
+            }
+        )
+        return _unknown_import_capability(), warnings
+
+    has_data_import_status = "dataImportStatus" in base_info
+    has_data_manage_status = "dataManageStatus" in base_info
+    applicant_import_enabled = _coerce_optional_bool(base_info.get("dataImportStatus")) if has_data_import_status else None
+    data_manage_status = _coerce_optional_bool(base_info.get("dataManageStatus")) if has_data_manage_status else None
+
+    if applicant_import_enabled is True:
+        return {
+            "can_import": True,
+            "auth_source": "apply_auth",
+            "applicant_import_enabled": True,
+            "data_manage_status": data_manage_status,
+            "runtime_checks_required": ["user_disabled", "function_demoted"],
+            "confidence": "preflight",
+        }, warnings
+
+    if data_manage_status is True:
+        return {
+            "can_import": True,
+            "auth_source": "data_manage_auth",
+            "applicant_import_enabled": applicant_import_enabled,
+            "data_manage_status": True,
+            "runtime_checks_required": ["user_disabled", "function_demoted"],
+            "confidence": "preflight",
+        }, warnings
+
+    if applicant_import_enabled is False and data_manage_status is False:
+        return {
+            "can_import": False,
+            "auth_source": "none",
+            "applicant_import_enabled": False,
+            "data_manage_status": False,
+            "runtime_checks_required": [],
+            "confidence": "preflight",
+        }, warnings
+
+    warnings.append(
+        {
+            "code": "IMPORT_CAPABILITY_UNAVAILABLE",
+            "message": "app_get could not fully determine import capability because baseInfo did not include a complete import permission summary.",
+        }
+    )
+    return _unknown_import_capability(
+        applicant_import_enabled=applicant_import_enabled,
+        data_manage_status=data_manage_status,
+    ), warnings
+
+
+def _unknown_import_capability(
+    *,
+    applicant_import_enabled: bool | None = None,
+    data_manage_status: bool | None = None,
+) -> JSONObject:
+    return {
+        "can_import": None,
+        "auth_source": "unknown",
+        "applicant_import_enabled": applicant_import_enabled,
+        "data_manage_status": data_manage_status,
+        "runtime_checks_required": [],
+        "confidence": "unknown",
+    }
+
+
+def _derive_editability(base_info: Any) -> tuple[JSONObject, list[JSONObject]]:
+    warnings: list[JSONObject] = []
+    if not isinstance(base_info, dict):
+        warnings.append(
+            {
+                "code": "APP_EDITABILITY_UNAVAILABLE",
+                "message": "app_get could not determine editability because baseInfo was unavailable.",
+            }
+        )
+        return {
+            "can_edit_form": None,
+            "can_edit_flow": None,
+            "can_edit_views": None,
+            "can_edit_charts": None,
+        }, warnings
+
+    edit_item_status = _coerce_optional_bool(base_info.get("editItemStatus"))
+    data_manage_status = _coerce_optional_bool(base_info.get("dataManageStatus"))
+    return {
+        "can_edit_form": edit_item_status,
+        "can_edit_flow": edit_item_status,
+        "can_edit_views": data_manage_status,
+        "can_edit_charts": data_manage_status,
+    }, warnings
+
+
+def _coerce_positive_int(value: Any) -> int | None:
+    try:
+        number = int(value)
+    except (TypeError, ValueError):
+        return None
+    return number if number > 0 else None
+
+
+def _coerce_optional_bool(value: Any) -> bool | None:
+    if isinstance(value, bool):
+        return value
+    return None