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

package/src/qingflow_mcp/tools/package_tools.py

@@ -5,8 +5,9 @@ from copy import deepcopy
 from mcp.server.fastmcp import FastMCP
 
 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 ..solution.compiler.icon_utils import workspace_icon_config
 from .base import ToolBase, tool_cn_name
 
 
@@ -75,8 +76,44 @@ class PackageTools(ToolBase):
         self._require_tag_id(tag_id)
 
         def runner(session_profile, context):
-            result = self.backend.request("GET", context, f"/tag/{tag_id}")
-            base_info = self.backend.request("GET", context, f"/tag/{tag_id}/baseInfo")
+            warnings: list[JSONObject] = []
+            verification: JSONObject = {"base_info_verified": True, "fallback_visible_package_used": False}
+            try:
+                base_info = self.backend.request("GET", context, f"/tag/{tag_id}/baseInfo")
+            except QingflowApiError as exc:
+                if not _is_optional_package_metadata_error(exc):
+                    raise
+                base_info = self._resolve_visible_package(context, tag_id)
+                if base_info is None:
+                    raise
+                warnings.append(
+                    {
+                        "code": "PACKAGE_BASE_INFO_UNAVAILABLE",
+                        "message": "package_get used the current user's visible package list because package baseInfo is unavailable in this permission context.",
+                        "backend_code": exc.backend_code,
+                        "http_status": exc.http_status,
+                        "request_id": exc.request_id,
+                    }
+                )
+                verification = {"base_info_verified": False, "fallback_visible_package_used": True}
+            result: JSONObject = base_info if isinstance(base_info, dict) else {}
+            if verification["base_info_verified"]:
+                try:
+                    detail = self.backend.request("GET", context, f"/tag/{tag_id}")
+                    if isinstance(detail, dict):
+                        result = detail
+                except QingflowApiError as exc:
+                    if not _is_optional_package_metadata_error(exc):
+                        raise
+                    warnings.append(
+                        {
+                            "code": "PACKAGE_DETAIL_READ_DEGRADED",
+                            "message": "package_get used package baseInfo because the detail endpoint requires package edit/add-app permission.",
+                            "backend_code": exc.backend_code,
+                            "http_status": exc.http_status,
+                            "request_id": exc.request_id,
+                        }
+                    )
             compact = self._compact_package(
                 result if isinstance(result, dict) else {},
                 base_info=base_info if isinstance(base_info, dict) else None,
@@ -87,7 +124,11 @@ class PackageTools(ToolBase):
                 "tag_id": tag_id,
                 "result": result if include_raw else compact,
                 "compact": not include_raw,
+                "detail_degraded": bool(warnings),
+                "verification": verification,
             }
+            if warnings:
+                response["warnings"] = warnings
             if include_raw:
                 response["summary"] = compact
             return response
@@ -100,7 +141,27 @@ class PackageTools(ToolBase):
         self._require_readable_tag_id(tag_id)
 
         def runner(session_profile, context):
-            result = self.backend.request("GET", context, f"/tag/{tag_id}/baseInfo")
+            warnings: list[JSONObject] = []
+            verification: JSONObject = {"base_info_verified": True, "fallback_visible_package_used": False}
+            try:
+                result = self.backend.request("GET", context, f"/tag/{tag_id}/baseInfo")
+            except QingflowApiError as exc:
+                if not _is_optional_package_metadata_error(exc):
+                    raise
+                visible_package = self._resolve_visible_package(context, tag_id)
+                if visible_package is None:
+                    raise
+                result = visible_package
+                warnings.append(
+                    {
+                        "code": "PACKAGE_BASE_INFO_UNAVAILABLE",
+                        "message": "package_get_base used the current user's visible package list because package baseInfo is unavailable in this permission context.",
+                        "backend_code": exc.backend_code,
+                        "http_status": exc.http_status,
+                        "request_id": exc.request_id,
+                    }
+                )
+                verification = {"base_info_verified": False, "fallback_visible_package_used": True}
             compact = self._compact_package(result if isinstance(result, dict) else {})
             response = {
                 "profile": profile,
@@ -108,7 +169,10 @@ class PackageTools(ToolBase):
                 "tag_id": tag_id,
                 "result": result if include_raw else compact,
                 "compact": not include_raw,
+                "verification": verification,
             }
+            if warnings:
+                response["warnings"] = warnings
             if include_raw:
                 response["summary"] = compact
             return response
@@ -133,15 +197,44 @@ class PackageTools(ToolBase):
         body = self._require_dict(payload)
 
         def runner(session_profile, context):
-            current = self.backend.request("GET", context, f"/tag/{tag_id}")
+            warnings: list[JSONObject] = []
+            try:
+                current = self.backend.request("GET", context, f"/tag/{tag_id}")
+            except QingflowApiError as exc:
+                if not _is_optional_package_metadata_error(exc):
+                    raise
+                try:
+                    current = self.backend.request("GET", context, f"/tag/{tag_id}/baseInfo")
+                    fallback_source = "baseInfo"
+                except QingflowApiError as base_exc:
+                    if not _is_optional_package_metadata_error(base_exc):
+                        raise
+                    visible_package = self._resolve_visible_package(context, tag_id)
+                    if visible_package is None:
+                        raise base_exc
+                    current = visible_package
+                    fallback_source = "visible_package_list"
+                warnings.append(
+                    {
+                        "code": "PACKAGE_DETAIL_READ_DEGRADED",
+                        "message": "package_update used package baseInfo or visible package metadata because package detail is unavailable in this permission context.",
+                        "source": fallback_source,
+                        "backend_code": exc.backend_code,
+                        "http_status": exc.http_status,
+                        "request_id": exc.request_id,
+                    }
+                )
             result = self.backend.request(
                 "PUT",
                 context,
                 f"/tag/{tag_id}",
                 json_body=self._normalize_package_payload(body, existing=current),
             )
+            response = {"profile": profile, "ws_id": session_profile.selected_ws_id, "tag_id": tag_id, "result": result}
+            if warnings:
+                response["warnings"] = warnings
             return self._attach_human_review_notice(
-                {"profile": profile, "ws_id": session_profile.selected_ws_id, "tag_id": tag_id, "result": result},
+                response,
                 operation="update",
                 target="app package settings",
             )
@@ -250,6 +343,19 @@ class PackageTools(ToolBase):
         if tag_id < 0:
             raise_tool_error(QingflowApiError.config_error("tag_id must be non-negative"))
 
+    def _resolve_visible_package(self, context, tag_id: int) -> JSONObject | None:  # type: ignore[no-untyped-def]
+        """Resolve package metadata from the current user's visible package list."""
+        payload = self.backend.request("GET", context, "/tag", params={"trialStatus": "all"})
+        items, _source_shape = self._extract_package_items(payload)
+        for item in items:
+            try:
+                candidate = int(item.get("tagId")) if item.get("tagId") is not None else None
+            except (TypeError, ValueError):
+                candidate = None
+            if candidate == tag_id:
+                return dict(item)
+        return None
+
     def _normalize_package_payload(self, payload: JSONObject, existing: JSONObject | None = None) -> JSONObject:
         """执行内部辅助逻辑。"""
         data = deepcopy(existing) if isinstance(existing, dict) else {}
@@ -281,13 +387,26 @@ class PackageTools(ToolBase):
                     "dashKey": item.get("dashKey"),
                 }
             )
+        item_count = None
+        raw_item_count = result.get("itemCount")
+        try:
+            if raw_item_count is not None:
+                coerced_count = int(raw_item_count)
+                if coerced_count >= 0:
+                    item_count = coerced_count
+        except (TypeError, ValueError):
+            item_count = None
+        if item_count is None and "tagItems" in result:
+            item_count = len(tag_items)
+        tag_icon = result.get("tagIcon") if result.get("tagIcon") is not None else permission_source.get("tagIcon")
         compact = {
             "tagId": result.get("tagId"),
             "tagName": result.get("tagName"),
-            "tagIcon": result.get("tagIcon") if result.get("tagIcon") is not None else permission_source.get("tagIcon"),
+            "tagIcon": tag_icon,
+            "iconConfig": workspace_icon_config(str(tag_icon).strip() if tag_icon not in (None, "") else None),
             "publishStatus": result.get("publishStatus") if result.get("publishStatus") is not None else permission_source.get("publishStatus"),
             "beingTrial": result.get("beingTrial"),
-            "itemCount": len(tag_items),
+            "itemCount": item_count,
             "itemPreview": preview,
             "addAppStatus": permission_source.get("addAppStatus"),
             "editAppStatus": permission_source.get("editAppStatus"),
@@ -324,3 +443,10 @@ def _default_package_auth() -> JSONObject:
         "contactAuth": {"type": "WORKSPACE_ALL", "authMembers": deepcopy(members)},
         "externalMemberAuth": {"type": "NOT", "authMembers": deepcopy(members)},
     }
+
+
+def _is_optional_package_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

package/src/qingflow_mcp/tools/portal_tools.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from mcp.server.fastmcp import FastMCP
 
 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 .base import ToolBase, tool_cn_name
 
@@ -89,8 +89,37 @@ class PortalTools(ToolBase):
         self._require_dash_key(dash_key)
 
         def runner(session_profile, context):
-            result = self.backend.request("GET", context, f"/dash/{dash_key}/baseInfo")
-            return {"profile": profile, "ws_id": session_profile.selected_ws_id, "dash_key": dash_key, "result": result}
+            warnings: list[JSONObject] = []
+            verification: JSONObject = {"base_info_verified": True, "fallback_detail_used": False}
+            try:
+                result = self.backend.request("GET", context, f"/dash/{dash_key}/baseInfo")
+            except QingflowApiError as error:
+                if not _is_optional_portal_base_info_error(error):
+                    raise
+                result = self.backend.request("GET", context, f"/dash/{dash_key}", params={"beingDraft": False})
+                verification["base_info_verified"] = False
+                verification["fallback_detail_used"] = True
+                warning: JSONObject = {
+                    "code": "PORTAL_BASE_INFO_UNAVAILABLE",
+                    "message": "portal_get_base_info used portal detail because portal baseInfo is unavailable in this permission context.",
+                }
+                if error.backend_code is not None:
+                    warning["backend_code"] = error.backend_code
+                if error.http_status is not None:
+                    warning["http_status"] = error.http_status
+                if error.request_id is not None:
+                    warning["request_id"] = error.request_id
+                if error.details:
+                    warning["details"] = error.details
+                warnings.append(warning)
+            return {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "dash_key": dash_key,
+                "result": result,
+                "warnings": warnings,
+                "verification": verification,
+            }
 
         return self._run(profile, runner)
 
@@ -156,3 +185,10 @@ class PortalTools(ToolBase):
         """执行内部辅助逻辑。"""
         if not dash_key:
             raise_tool_error(QingflowApiError.config_error("dash_key is required"))
+
+
+def _is_optional_portal_base_info_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

package/src/qingflow_mcp/tools/qingbi_report_tools.py

@@ -7,7 +7,7 @@ from mcp.server.fastmcp import FastMCP
 
 from ..backend_client import BackendRequestContext
 from ..config import DEFAULT_PROFILE, normalize_base_url
-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, JSONValue
 from .base import ToolBase, tool_cn_name
 
@@ -20,13 +20,27 @@ def _qingbi_base_url(base_url: str) -> str:
 
 
 def _should_retry_qflow_base(error: QingflowApiError) -> bool:
-    return int(getattr(error, "backend_code", 0) or 0) == 81007
+    if is_auth_like_error(error):
+        return False
+    backend_code = backend_code_int(error)
+    http_status = getattr(error, "http_status", None)
+    return backend_code in {40002, 40027, 404, 81007} or http_status == 404
 
 
 def _should_retry_asos_data(error: QingflowApiError) -> bool:
-    backend_code = int(getattr(error, "backend_code", 0) or 0)
+    if is_auth_like_error(error):
+        return False
+    backend_code = backend_code_int(error)
     http_status = getattr(error, "http_status", None)
-    return backend_code in {44011, 81007} or http_status == 404
+    return backend_code in {40002, 40027, 404, 44011, 81007} or http_status == 404
+
+
+def _should_fallback_config_from_data(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    backend_code = backend_code_int(error)
+    http_status = getattr(error, "http_status", None)
+    return backend_code in {40002, 40027, 404, 81007} or http_status == 404
 
 
 def _coerce_tool_error(error: RuntimeError | QingflowApiError) -> QingflowApiError | None:
@@ -177,13 +191,37 @@ class QingbiReportTools(ToolBase):
     def qingbi_report_get_base(self, *, profile: str, chart_id: str) -> JSONObject:
         """执行工具方法逻辑。"""
         self._require_chart_id(chart_id)
+        source_error: QingflowApiError | None = None
         try:
-            return self._request(profile, "GET", f"/qingbi/charts/baseinfo/{chart_id}", chart_id=chart_id)
+            return self._request(profile, "GET", f"/qingbi/charts/qflow/baseinfo/{chart_id}", chart_id=chart_id)
         except (QingflowApiError, RuntimeError) as raw_error:
             error = _coerce_tool_error(raw_error)
             if error is None or not _should_retry_qflow_base(error):
                 raise
-        return self._request(profile, "GET", f"/qingbi/charts/qflow/baseinfo/{chart_id}", chart_id=chart_id)
+            source_error = error
+        try:
+            fallback = self._request(profile, "GET", f"/qingbi/charts/baseinfo/{chart_id}", chart_id=chart_id)
+        except (QingflowApiError, RuntimeError):
+            raise
+        if not _has_chart_base_identity(fallback.get("result"), chart_id=chart_id):
+            raise source_error
+        fallback.setdefault(
+            "warnings",
+            [
+                {
+                    "code": "CHART_BASE_INFO_FALLBACK_FROM_LEGACY",
+                    "message": "qingbi_report_get_base used the legacy chart baseInfo route because qflow baseInfo was unavailable in this permission context.",
+                    "backend_code": source_error.backend_code,
+                    "http_status": source_error.http_status,
+                    "request_id": source_error.request_id,
+                }
+            ],
+        )
+        fallback.setdefault(
+            "verification",
+            {"qflow_base_route_loaded": False, "legacy_base_route_loaded": True},
+        )
+        return fallback
 
     @tool_cn_name("更新报表基础信息")
     def qingbi_report_update_base(self, *, profile: str, chart_id: str, payload: JSONObject) -> JSONObject:
@@ -196,7 +234,45 @@ class QingbiReportTools(ToolBase):
     def qingbi_report_get_config(self, *, profile: str, chart_id: str) -> JSONObject:
         """执行工具方法逻辑。"""
         self._require_chart_id(chart_id)
-        return self._request(profile, "GET", f"/qingbi/charts/{chart_id}/configs", chart_id=chart_id)
+        original_error: QingflowApiError | RuntimeError | None = None
+        try:
+            return self._request(profile, "GET", f"/qingbi/charts/{chart_id}/configs", chart_id=chart_id)
+        except (QingflowApiError, RuntimeError) as raw_error:
+            original_error = raw_error
+            error = _coerce_tool_error(raw_error)
+            if error is None or not _should_fallback_config_from_data(error):
+                raise
+            source_error = error
+        try:
+            data_payload = self.qingbi_report_get_data(profile=profile, chart_id=chart_id, payload={})
+        except (QingflowApiError, RuntimeError):
+            if original_error is not None:
+                raise original_error
+            raise
+        data_result = data_payload.get("result") if isinstance(data_payload, dict) else None
+        if isinstance(data_result, dict) and isinstance(data_result.get("config"), dict) and data_result["config"]:
+            return {
+                "profile": data_payload.get("profile", profile),
+                "ws_id": data_payload.get("ws_id"),
+                "chart_id": chart_id,
+                "result": data_result["config"],
+                "warnings": [
+                    {
+                        "code": "CHART_CONFIG_FALLBACK_FROM_DATA",
+                        "message": "qingbi_report_get_config used config embedded in qflow chart data because the chart config endpoint was unavailable in this permission context.",
+                        "backend_code": source_error.backend_code,
+                        "http_status": source_error.http_status,
+                        "request_id": source_error.request_id,
+                    }
+                ],
+                "verification": {
+                    "config_endpoint_loaded": False,
+                    "data_config_loaded": True,
+                },
+            }
+        if original_error is not None:
+            raise original_error
+        raise_tool_error(QingflowApiError.config_error("chart config fallback did not return config"))
 
     @tool_cn_name("更新报表配置")
     def qingbi_report_update_config(self, *, profile: str, chart_id: str, payload: JSONObject) -> JSONObject:
@@ -251,6 +327,16 @@ class QingbiReportTools(ToolBase):
             error = _coerce_tool_error(raw_error)
             if error is None or not _should_retry_asos_data(error):
                 raise
+        warning: JSONObject = {
+            "code": "CHART_DATA_FALLBACK_FROM_ASOS",
+            "message": "qingbi_report_get_data used the asos data route because the qflow chart data route was unavailable in this permission context.",
+        }
+        if error.backend_code is not None:
+            warning["backend_code"] = error.backend_code
+        if error.http_status is not None:
+            warning["http_status"] = error.http_status
+        if error.request_id:
+            warning["request_id"] = error.request_id
         return self._request(
             profile,
             "POST",
@@ -258,6 +344,11 @@ class QingbiReportTools(ToolBase):
             chart_id=chart_id,
             params=params,
             json_body=payload or {},
+            warnings=[warning],
+            verification={
+                "qflow_data_route_loaded": False,
+                "asos_data_route_loaded": True,
+            },
         )
 
     @tool_cn_name("删除报表")
@@ -372,3 +463,21 @@ def _extract_sorted_chart_items(result: JSONValue) -> list[JSONObject]:
     if isinstance(result, list):
         return result
     return []
+
+
+def _has_chart_base_identity(result: JSONValue, *, chart_id: str) -> bool:
+    if not isinstance(result, dict):
+        return False
+    expected = str(chart_id or "").strip()
+    id_candidates = (
+        result.get("chartId"),
+        result.get("biChartId"),
+        result.get("id"),
+        result.get("chart_id"),
+    )
+    if expected and any(str(value or "").strip() == expected for value in id_candidates):
+        return True
+    return any(
+        str(result.get(key) or "").strip()
+        for key in ("chartName", "chart_name", "name", "title")
+    )