@qingflow-tech/qingflow-app-builder-mcp 1.0.10 → 1.0.12

package/src/qingflow_mcp/tools/app_tools.py

@@ -7,9 +7,10 @@ from mcp.server.fastmcp import FastMCP
 
 from ..backend_client import BackendRequestContext
 from ..config import DEFAULT_PROFILE
-from ..errors import QingflowApiError, raise_tool_error
+from ..errors import QingflowApiError, backend_code_int, is_auth_like_error, raise_tool_error
 from ..json_types import JSONObject
 from ..list_type_labels import SYSTEM_VIEW_DEFINITIONS, get_app_publish_status_label
+from ..solution.compiler.icon_utils import workspace_icon_config
 from .base import ToolBase, tool_cn_name
 
 
@@ -18,7 +19,7 @@ class AppTools(ToolBase):
 
     类型：应用元数据与配置工具。
     主要职责：
-    1. 查询应用列表、搜索应用、读取应用详情；
+    1. 查询应用列表、读取应用详情；
     2. 读取与更新应用基础配置、表单结构与发布状态；
     3. 提供应用创建、删除、发布等管理能力。
     """
@@ -26,12 +27,8 @@ class AppTools(ToolBase):
     def register(self, mcp: FastMCP) -> None:
         """注册当前工具到 MCP 服务。"""
         @mcp.tool()
-        def app_list(profile: str = DEFAULT_PROFILE, ship_auth: bool = False) -> JSONObject:
-            return self.app_list(profile=profile, ship_auth=ship_auth)
-
-        @mcp.tool()
-        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)
+        def app_list(profile: str = DEFAULT_PROFILE, query: str = "", keyword: str = "", ship_auth: bool = False) -> JSONObject:
+            return self.app_list(profile=profile, query=query, keyword=keyword, ship_auth=ship_auth)
 
         @mcp.tool()
         def app_get(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
@@ -90,24 +87,65 @@ class AppTools(ToolBase):
             return self.app_publish(profile=profile, app_key=app_key, payload=payload or {})
 
     @tool_cn_name("应用列表")
-    def app_list(self, *, profile: str, ship_auth: bool = False) -> JSONObject:
+    def app_list(self, *, profile: str, query: str = "", keyword: str = "", ship_auth: bool = False) -> JSONObject:
         """List current-user visible apps in the selected workspace."""
         def runner(session_profile, context):
             result = self.backend.request("GET", context, "/tag/apps")
             items, source_shape = self._extract_visible_apps(result)
+            normalized_query, warnings = _normalize_app_list_query(query=query, keyword=keyword)
+            unfiltered_count = len(items)
+            if normalized_query:
+                items = self._filter_visible_apps(items, normalized_query)
             response = {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
                 "items": items,
                 "count": len(items),
                 "source_shape": source_shape,
+                "query": normalized_query,
+                "matched_count": len(items),
+                "unfiltered_count": unfiltered_count,
+                "filter_mode": "local_visible_apps",
             }
+            if warnings:
+                response["warnings"] = warnings
             if ship_auth:
                 response["raw"] = result
             return response
 
         return self._run(profile, runner)
 
+    def _filter_visible_apps(self, items: list[JSONObject], query: str) -> list[JSONObject]:
+        """Filter current-user visible apps locally without calling admin search APIs."""
+        needle = query.casefold()
+        matched: list[JSONObject] = []
+        for item in items:
+            haystacks = (
+                item.get("app_key"),
+                item.get("app_name"),
+                item.get("title"),
+                item.get("package_name"),
+                item.get("tag_name"),
+                item.get("group_name"),
+            )
+            if any(needle in str(value).casefold() for value in haystacks if value not in (None, "")):
+                matched.append(item)
+        return matched
+
+    def _resolve_visible_app(self, context: BackendRequestContext, app_key: str) -> JSONObject | None:
+        """Resolve app display metadata from the current user's visible app tree."""
+        try:
+            result = self.backend.request("GET", context, "/tag/apps")
+        except QingflowApiError as exc:
+            if not _is_optional_app_metadata_error(exc):
+                raise
+            return None
+        items, _source_shape = self._extract_visible_apps(result)
+        for item in items:
+            if str(item.get("app_key") or "").strip() == app_key:
+                return item
+        return None
+
     @tool_cn_name("应用搜索")
     def app_search(self, *, profile: str, keyword: str = "", page_num: int = 1, page_size: int = 50) -> JSONObject:
         """Search apps by keyword in name/title using backend search API.
@@ -117,9 +155,50 @@ class AppTools(ToolBase):
             params: JSONObject = {"pageNum": page_num, "pageSize": page_size}
             if keyword:
                 params["queryKey"] = keyword
-            
-            result = self.backend.request("GET", context, "/app/item", params=params)
-            
+
+            warnings: list[JSONObject] = []
+            source = "app_item_search"
+            try:
+                result = self.backend.request("GET", context, "/app/item", params=params)
+            except QingflowApiError as exc:
+                if is_auth_like_error(exc):
+                    raise
+                if not _is_optional_app_metadata_error(exc):
+                    raise
+                visible_payload = self.backend.request("GET", context, "/tag/apps")
+                all_apps, source_shape = self._extract_visible_apps(visible_payload)
+                matched_apps = self._filter_visible_apps(all_apps, keyword) if keyword else all_apps
+                page_start = max(page_num - 1, 0) * page_size
+                page_end = page_start + page_size
+                apps = matched_apps[page_start:page_end]
+                warnings.append(
+                    {
+                        "code": "APP_SEARCH_FALLBACK_VISIBLE_APPS",
+                        "message": (
+                            "app_search used the current user's visible app tree because the global app search "
+                            "endpoint is unavailable in this permission context."
+                        ),
+                        "backend_code": exc.backend_code,
+                        "http_status": exc.http_status,
+                        "request_id": exc.request_id,
+                    }
+                )
+                return {
+                    "profile": profile,
+                    "ws_id": session_profile.selected_ws_id,
+                    "keyword": keyword,
+                    "page_num": page_num,
+                    "page_size": page_size,
+                    "total": len(matched_apps),
+                    "items": apps,
+                    "apps": apps,
+                    "source": "visible_apps_fallback",
+                    "source_shape": source_shape,
+                    "unfiltered_count": len(all_apps),
+                    "matched_count": len(matched_apps),
+                    "warnings": warnings,
+                }
+
             apps = []
             if isinstance(result, dict):
                 items = result.get("list", [])
@@ -144,6 +223,7 @@ class AppTools(ToolBase):
                 "total": result.get("total") if isinstance(result, dict) else len(apps),
                 "items": apps,
                 "apps": apps,
+                "source": source,
             }
 
         return self._run(profile, runner)
@@ -157,6 +237,8 @@ class AppTools(ToolBase):
             warnings: list[JSONObject] = []
             app_name = app_key
             base_info: JSONObject | None = None
+            app_icon = None
+            visible_app: JSONObject | None = None
 
             try:
                 base_info = self.backend.request("GET", context, f"/app/{app_key}/baseInfo")
@@ -165,32 +247,33 @@ class AppTools(ToolBase):
                         str(base_info.get("formTitle") or base_info.get("title") or base_info.get("appName") or app_key).strip()
                         or app_key
                     )
+                    app_icon = str(base_info.get("appIcon") or "").strip() or None
             except QingflowApiError as exc:
-                if exc.backend_code not in {40002, 40027}:
+                if not _is_optional_app_metadata_error(exc):
                     raise
+                visible_app = self._resolve_visible_app(context, app_key)
+                if visible_app is not None:
+                    app_name = str(visible_app.get("app_name") or visible_app.get("title") or app_key).strip() or app_key
+                    app_icon = str(visible_app.get("app_icon") or "").strip() or None
                 warnings.append(
-                    {
+                    _with_api_error_fields(
+                        {
                         "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'}"
+                            f"app_get could not load base info for {app_key}; "
+                            "using the current user's visible app tree when available."
                         ),
-                    }
+                        },
+                        exc,
+                    )
                 )
+
+            can_create = self._probe_create_access(context, app_key)
             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))
+            custom_views, custom_view_warnings = self._resolve_accessible_custom_views(context, app_key)
+            warnings.extend(custom_view_warnings)
+            accessible_views.extend(custom_views)
             import_capability, import_warnings = _derive_import_capability(base_info)
             warnings.extend(import_warnings)
             return {
@@ -202,6 +285,9 @@ class AppTools(ToolBase):
                 "data": {
                     "app_key": app_key,
                     "app_name": app_name,
+                    "app_icon": app_icon,
+                    "icon_config": workspace_icon_config(app_icon),
+                    **({"visible_app": visible_app} if base_info is None and visible_app is not None else {}),
                     "can_create": can_create,
                     "import_capability": import_capability,
                     "accessible_views": accessible_views,
@@ -216,7 +302,30 @@ class AppTools(ToolBase):
         self._require_app_key(app_key)
 
         def runner(session_profile, context):
-            result = self.backend.request("GET", context, f"/app/{app_key}/baseInfo")
+            warnings: list[JSONObject] = []
+            verification: JSONObject = {"base_info_verified": True, "fallback_visible_app_used": False}
+            try:
+                result = self.backend.request("GET", context, f"/app/{app_key}/baseInfo")
+            except QingflowApiError as exc:
+                if not _is_optional_app_metadata_error(exc):
+                    raise
+                visible_app = self._resolve_visible_app(context, app_key)
+                if visible_app is None:
+                    raise
+                result = self._base_info_from_visible_app(app_key, visible_app)
+                warnings.append(
+                    _with_api_error_fields(
+                        {
+                        "code": "APP_BASE_INFO_UNAVAILABLE",
+                        "message": (
+                            f"app_get_base could not load base info for {app_key}; "
+                            "using the current user's visible app tree."
+                        ),
+                        },
+                        exc,
+                    )
+                )
+                verification = {"base_info_verified": False, "fallback_visible_app_used": True}
             publish_status = result.get("appPublishStatus") if isinstance(result, dict) else None
             compact = self._compact_base_info(result if isinstance(result, dict) else {})
             response = {
@@ -227,7 +336,10 @@ class AppTools(ToolBase):
                 "app_publish_status": publish_status,
                 "app_publish_status_label": get_app_publish_status_label(publish_status if isinstance(publish_status, int) else None),
                 "compact": not include_raw,
+                "verification": verification,
             }
+            if warnings:
+                response["warnings"] = warnings
             if include_raw:
                 response["summary"] = compact
             return response
@@ -461,7 +573,9 @@ class AppTools(ToolBase):
             )
             return True
         except QingflowApiError as exc:
-            if exc.backend_code in {40002, 40027}:
+            if is_auth_like_error(exc):
+                raise
+            if backend_code_int(exc) in {40002, 40027, 404} or exc.http_status == 404:
                 return False
             raise
 
@@ -476,7 +590,9 @@ class AppTools(ToolBase):
             )
             return True
         except QingflowApiError as exc:
-            if exc.backend_code in {40002, 40027}:
+            if is_auth_like_error(exc):
+                raise
+            if backend_code_int(exc) in {40002, 40027, 404} or exc.http_status == 404:
                 return False
             raise
 
@@ -488,40 +604,42 @@ class AppTools(ToolBase):
             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
+                raise
             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]:
+    def _resolve_accessible_custom_views(self, context: BackendRequestContext, app_key: str) -> tuple[list[JSONObject], list[JSONObject]]:
         """执行内部辅助逻辑。"""
+        warnings: 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 []
+            if _is_optional_app_metadata_error(exc):
+                warnings.append(
+                    _with_api_error_fields(
+                        {
+                        "code": "CUSTOM_VIEW_LIST_UNAVAILABLE",
+                        "message": (
+                            f"app_get could not load custom views for {app_key}; "
+                            "system views and other app metadata may still be usable."
+                        ),
+                        },
+                        exc,
+                    )
+                )
+                return [], warnings
             raise
 
         items: list[JSONObject] = []
         for item in _normalize_view_list(payload):
-            view_key = str(item.get("viewKey") or "").strip()
+            view_key = str(item.get("viewKey") or item.get("viewgraphKey") 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,
+                "name": str(item.get("viewName") or item.get("viewgraphName") or view_key).strip() or view_key,
                 "kind": "custom",
             }
             view_type = str(item.get("viewType") or item.get("viewgraphType") or "").strip()
@@ -529,7 +647,7 @@ class AppTools(ToolBase):
                 normalized["view_type"] = view_type
             normalized["analysis_supported"] = _analysis_supported_for_view_type(view_type or None)
             items.append(normalized)
-        return items
+        return items, warnings
 
     def _compact_base_info(self, result: dict[str, Any]) -> JSONObject:
         """执行内部辅助逻辑。"""
@@ -573,6 +691,30 @@ class AppTools(ToolBase):
             },
         }
 
+    def _base_info_from_visible_app(self, app_key: str, visible_app: JSONObject) -> JSONObject:
+        """Build a base-info-shaped fallback from a current-user visible app item."""
+        tag_ids: list[int] = []
+        tag_id = _coerce_positive_int(visible_app.get("tag_id"))
+        if tag_id is not None:
+            tag_ids.append(tag_id)
+        for value in visible_app.get("tag_ids") if isinstance(visible_app.get("tag_ids"), list) else []:
+            tag_id = _coerce_positive_int(value)
+            if tag_id is not None and tag_id not in tag_ids:
+                tag_ids.append(tag_id)
+
+        fallback: JSONObject = {
+            "appKey": app_key,
+            "formId": visible_app.get("form_id"),
+            "formTitle": visible_app.get("app_name") or visible_app.get("title") or app_key,
+            "appIcon": visible_app.get("app_icon"),
+            "tagIds": tag_ids,
+            "visibleApp": visible_app,
+        }
+        package_name = visible_app.get("package_name") or visible_app.get("tag_name") or visible_app.get("group_name")
+        if package_name:
+            fallback["tagItems"] = [{"tagId": tag_id, "tagName": package_name} for tag_id in tag_ids]
+        return fallback
+
     def _compact_form_schema(self, result: dict[str, Any]) -> JSONObject:
         """执行内部辅助逻辑。"""
         base_questions_raw = result.get("baseQues") if isinstance(result.get("baseQues"), list) else []
@@ -731,6 +873,7 @@ class AppTools(ToolBase):
             "app_key": app_key,
             "app_name": title,
             "title": title,
+            "app_icon": str(item.get("appIcon") or "").strip() or None,
             "form_id": item.get("formId"),
             "tag_id": package_tag_id,
             "package_name": package_name,
@@ -791,17 +934,26 @@ def _normalize_form_type(value: int | str) -> int:
 
 
 def _normalize_view_list(payload: Any) -> list[JSONObject]:
+    if isinstance(payload, dict):
+        raw_list = payload.get("list")
+        if isinstance(raw_list, list):
+            payload = raw_list
+        else:
+            payload = [payload]
     if not isinstance(payload, list):
         return []
     flattened: list[JSONObject] = []
     for group in payload:
         if not isinstance(group, dict):
             continue
+        if group.get("viewKey") or group.get("viewgraphKey"):
+            flattened.append(group)
+            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"):
+            if isinstance(item, dict) and (item.get("viewKey") or item.get("viewgraphKey")):
                 flattened.append(item)
     return flattened
 
@@ -813,6 +965,23 @@ def _analysis_supported_for_view_type(view_type: str | None) -> bool:
     return normalized not in {"boardview", "ganttview"}
 
 
+def _is_optional_app_metadata_error(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    backend_code = backend_code_int(error)
+    return backend_code in {40002, 40027, 404} or error.http_status == 404
+
+
+def _with_api_error_fields(payload: JSONObject, error: QingflowApiError) -> JSONObject:
+    if error.backend_code is not None:
+        payload["backend_code"] = error.backend_code
+    if error.http_status is not None:
+        payload["http_status"] = error.http_status
+    if error.request_id:
+        payload["request_id"] = error.request_id
+    return payload
+
+
 def _derive_import_capability(base_info: Any) -> tuple[JSONObject, list[JSONObject]]:
     warnings: list[JSONObject] = []
     if not isinstance(base_info, dict):
@@ -924,3 +1093,20 @@ def _coerce_optional_bool(value: Any) -> bool | None:
     if isinstance(value, bool):
         return value
     return None
+
+
+def _normalize_app_list_query(*, query: str = "", keyword: str = "") -> tuple[str, list[JSONObject]]:
+    normalized_query = str(query or "").strip()
+    normalized_keyword = str(keyword or "").strip()
+    warnings: list[JSONObject] = []
+    if normalized_query and normalized_keyword:
+        warnings.append(
+            {
+                "code": "APP_LIST_QUERY_TAKES_PRECEDENCE",
+                "message": "Both query and keyword were provided; query was used and keyword was ignored.",
+                "ignored_keyword": normalized_keyword,
+            }
+        )
+    if normalized_query:
+        return normalized_query, warnings
+    return normalized_keyword, warnings