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

package/src/qingflow_mcp/tools/resource_read_tools.py

@@ -3,13 +3,13 @@ from __future__ import annotations
 from copy import deepcopy
 from typing import Any
 
-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
 from ..solution.compiler.icon_utils import workspace_icon_config
 from .app_tools import _analysis_supported_for_view_type
 from .base import ToolBase, tool_cn_name
-from .qingbi_report_tools import QingbiReportTools
+from .qingbi_report_tools import QingbiReportTools, _coerce_tool_error
 
 
 class ResourceReadTools(ToolBase):
@@ -141,21 +141,60 @@ class ResourceReadTools(ToolBase):
             warnings: list[JSONObject] = []
             verification = {
                 "view_exists": True,
+                "config_verified": True,
+                "base_info_verified": True,
                 "questions_verified": True,
             }
-            config = self.backend.request("GET", context, f"/view/{view_key}/viewConfig")
-            base_info = self.backend.request("GET", context, f"/view/{view_key}/viewConfig/baseInfo")
+            try:
+                config = self.backend.request("GET", context, f"/view/{view_key}/viewConfig")
+                if not isinstance(config, dict):
+                    config = {}
+            except QingflowApiError as error:
+                if not _is_optional_view_config_error(error):
+                    raise
+                config = {}
+                verification["config_verified"] = False
+                warnings.append(
+                    {
+                        "code": "VIEW_CONFIG_UNAVAILABLE",
+                        "message": "view_get used baseInfo because viewConfig is unavailable for this user.",
+                        "backend_code": error.backend_code,
+                        "http_status": error.http_status,
+                        "request_id": error.request_id,
+                    }
+                )
+            try:
+                base_info = self.backend.request("GET", context, f"/view/{view_key}/viewConfig/baseInfo")
+            except QingflowApiError as error:
+                if not _is_optional_view_base_error(error):
+                    raise
+                base_info = {}
+                verification["base_info_verified"] = False
+                warnings.append(
+                    {
+                        "code": "VIEW_BASE_INFO_UNAVAILABLE",
+                        "message": "view_get used viewConfig because view baseInfo is unavailable for this user.",
+                        "backend_code": error.backend_code,
+                        "http_status": error.http_status,
+                        "request_id": error.request_id,
+                    }
+                )
             questions: list[dict[str, Any]] = []
             try:
                 questions_payload = self.backend.request("GET", context, f"/view/{view_key}/question")
                 if isinstance(questions_payload, list):
                     questions = [deepcopy(item) for item in questions_payload if isinstance(item, dict)]
-            except QingflowApiError:
+            except QingflowApiError as error:
+                if not _is_optional_view_question_error(error):
+                    raise
                 verification["questions_verified"] = False
                 warnings.append(
                     {
                         "code": "VIEW_QUESTIONS_UNAVAILABLE",
                         "message": "view_get could not load visible columns because question readback is unavailable.",
+                        "backend_code": error.backend_code,
+                        "http_status": error.http_status,
+                        "request_id": error.request_id,
                     }
                 )
 
@@ -223,13 +262,32 @@ class ResourceReadTools(ToolBase):
         self._require_chart_id(chart_id)
 
         def runner(session_profile, _context):
-            base = self.charts.qingbi_report_get_base(profile=profile, chart_id=chart_id).get("result") or {}
             warnings: list[JSONObject] = []
             verification = {
                 "chart_exists": True,
+                "chart_base_loaded": False,
                 "chart_data_loaded": False,
                 "chart_config_loaded": False,
             }
+            transport_errors: list[JSONObject] = []
+            base: dict[str, Any] = {}
+            try:
+                base_result = self.charts.qingbi_report_get_base(profile=profile, chart_id=chart_id).get("result") or {}
+                if isinstance(base_result, dict):
+                    base = deepcopy(base_result)
+                    verification["chart_base_loaded"] = True
+            except (QingflowApiError, RuntimeError) as error:
+                api_error = _coerce_tool_error(error)
+                if api_error is None or not _is_optional_chart_base_error(api_error):
+                    raise
+                transport_errors.append(_transport_error_payload(stage="base_info", error=api_error))
+                warnings.append(
+                    {
+                        "code": "CHART_BASE_INFO_UNAVAILABLE",
+                        "message": "chart_get could not load chart base info; continuing with chart data when available.",
+                        **_transport_warning_fields(api_error),
+                    }
+                )
             data: Any = None
             data_config: dict[str, Any] = {}
             try:
@@ -239,23 +297,54 @@ class ResourceReadTools(ToolBase):
                     data_config = deepcopy(data.get("config"))
                     verification["chart_config_loaded"] = True
             except (QingflowApiError, RuntimeError) as error:
-                api_error = error if isinstance(error, QingflowApiError) else None
+                api_error = _coerce_tool_error(error)
+                if api_error is None or not _is_optional_chart_data_error(api_error):
+                    raise
+                transport_errors.append(_transport_error_payload(stage="data", error=api_error))
                 warnings.append(
                     {
                         "code": "CHART_DATA_UNAVAILABLE",
                         "message": "chart_get could not load chart data; returning chart metadata and config when available.",
-                        "backend_code": api_error.backend_code if api_error is not None else None,
-                        "http_status": api_error.http_status if api_error is not None else None,
+                        **_transport_warning_fields(api_error),
                     }
                 )
             if not data_config:
                 try:
                     config_result = self.charts.qingbi_report_get_config(profile=profile, chart_id=chart_id).get("result") or {}
-                except (QingflowApiError, RuntimeError):
+                except (QingflowApiError, RuntimeError) as error:
+                    api_error = _coerce_tool_error(error)
+                    if api_error is None or not _is_optional_chart_config_error(api_error):
+                        raise
+                    transport_errors.append(_transport_error_payload(stage="config", error=api_error))
+                    warnings.append(
+                        {
+                            "code": "CHART_CONFIG_UNAVAILABLE",
+                            "message": "chart_get could not load chart config; returning chart base info or data when available.",
+                            **_transport_warning_fields(api_error),
+                        }
+                    )
                     config_result = {}
                 if isinstance(config_result, dict) and config_result:
                     data_config = deepcopy(config_result)
                     verification["chart_config_loaded"] = True
+            if not any(
+                bool(verification[key])
+                for key in ("chart_base_loaded", "chart_data_loaded", "chart_config_loaded")
+            ):
+                return {
+                    "profile": profile,
+                    "ws_id": session_profile.selected_ws_id,
+                    "ok": False,
+                    "status": "failed",
+                    "error_code": "CHART_READ_UNAVAILABLE",
+                    "message": "chart_get could not load chart base info, data, or config in this permission context.",
+                    "warnings": warnings,
+                    "verification": verification,
+                    "details": {
+                        "chart_id": chart_id,
+                        "transport_errors": transport_errors,
+                    },
+                }
             data_payload: dict[str, Any] = {
                 "chart_id": chart_id,
                 "chart_name": str(base.get("chartName") or base.get("name") or chart_id).strip() or chart_id,
@@ -296,7 +385,9 @@ class ResourceReadTools(ToolBase):
     def _resolve_app_key_from_view_form(self, *, context: Any, view_key: str) -> str | None:
         try:
             form_payload = self.backend.request("GET", context, f"/view/{view_key}/form")
-        except QingflowApiError:
+        except QingflowApiError as exc:
+            if not _is_optional_view_metadata_resolution_error(exc):
+                raise
             return None
         if not isinstance(form_payload, dict):
             return None
@@ -309,38 +400,13 @@ class ResourceReadTools(ToolBase):
             return None
         try:
             payload = self.backend.request("GET", context, "/tag/apps")
-        except QingflowApiError:
+        except QingflowApiError as exc:
+            if not _is_optional_view_metadata_resolution_error(exc):
+                raise
             payload = None
         app_key = _find_visible_app_key_by_form_id(payload, form_id=form_id)
         if app_key:
             return app_key
-        page_num = 1
-        page_size = 200
-        while page_num <= 20:
-            try:
-                page = self.backend.request(
-                    "GET",
-                    context,
-                    "/app/item",
-                    params={"pageNum": page_num, "pageSize": page_size},
-                )
-            except QingflowApiError:
-                return None
-            items = page.get("list") if isinstance(page, dict) else []
-            if not isinstance(items, list) or not items:
-                return None
-            for item in items:
-                if not isinstance(item, dict):
-                    continue
-                if _coerce_positive_int(item.get("formId") or item.get("form_id")) != form_id:
-                    continue
-                app_key = str(item.get("appKey") or item.get("app_key") or "").strip()
-                if app_key:
-                    return app_key
-            total = _coerce_positive_int(page.get("total")) if isinstance(page, dict) else None
-            if total is not None and page_num * page_size >= total:
-                break
-            page_num += 1
         return None
 
 
@@ -423,6 +489,89 @@ def _normalize_user_portal_components(components: Any) -> list[dict[str, Any]]:
     return items
 
 
+def _is_optional_chart_base_error(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    backend_code = _coerce_backend_code(error)
+    return backend_code in {40002, 40027, 404, 81007} or error.http_status == 404
+
+
+def _is_optional_chart_data_error(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    backend_code = _coerce_backend_code(error)
+    return backend_code in {40002, 40027, 404, 44011, 81007, 81011} or error.http_status == 404
+
+
+def _is_optional_chart_config_error(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    backend_code = _coerce_backend_code(error)
+    return backend_code in {40002, 40027, 404, 44011, 81007, 81011} or error.http_status == 404
+
+
+def _is_optional_view_base_error(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    backend_code = _coerce_backend_code(error)
+    return backend_code in {40002, 40027, 404} or error.http_status == 404
+
+
+def _is_optional_view_config_error(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    backend_code = _coerce_backend_code(error)
+    return backend_code in {40002, 40027, 404} or error.http_status == 404
+
+
+def _is_optional_view_question_error(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    backend_code = _coerce_backend_code(error)
+    return backend_code in {40002, 40027, 404} or error.http_status == 404
+
+
+def _is_optional_view_metadata_resolution_error(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    backend_code = _coerce_backend_code(error)
+    return backend_code in {40002, 40027, 404} or error.http_status == 404
+
+
+def _coerce_backend_code(error: QingflowApiError) -> int | None:
+    return backend_code_int(error)
+
+
+def _transport_error_payload(*, stage: str, error: QingflowApiError) -> JSONObject:
+    payload: JSONObject = {
+        "stage": stage,
+        "category": error.category,
+        "message": error.message,
+    }
+    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
+    if error.details:
+        payload["details"] = deepcopy(error.details)
+    return payload
+
+
+def _transport_warning_fields(error: QingflowApiError) -> JSONObject:
+    payload: 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
+    if error.details:
+        payload["details"] = deepcopy(error.details)
+    return payload
+
+
 def _normalize_portal_component_source_type(value: Any) -> str:
     raw = str(value or "").strip()
     mapping = {

package/src/qingflow_mcp/tools/role_tools.py

@@ -1,9 +1,11 @@
 from __future__ import annotations
 
+from typing import Any
+
 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
 
@@ -20,7 +22,7 @@ class RoleTools(ToolBase):
 
     def register(self, mcp: FastMCP) -> None:
         """注册当前工具到 MCP 服务。"""
-        @mcp.tool()
+        @mcp.tool(description="Search workspace roles for builder permission and workflow configuration. Requires contact/role management permission and a non-empty keyword; do not use for record member/department field candidates.")
         def role_search(
             profile: str = DEFAULT_PROFILE,
             keyword: str = "",
@@ -50,18 +52,36 @@ class RoleTools(ToolBase):
         """执行角色相关逻辑。"""
         if page_num <= 0 or page_size <= 0:
             raise_tool_error(QingflowApiError.config_error("page_num and page_size must be positive"))
+        normalized_keyword = keyword.strip()
+        if not normalized_keyword:
+            raise_tool_error(
+                QingflowApiError.config_error(
+                    "keyword is required for role_search; role lookup is a contact-management path, not a record candidate fallback"
+                )
+            )
 
         def runner(session_profile, context):
-            result = self.backend.request(
-                "GET",
-                context,
-                "/contact/roleByPage",
-                params={"keyword": keyword, "pageNum": page_num, "pageSize": page_size},
-            )
+            try:
+                result = self.backend.request(
+                    "GET",
+                    context,
+                    "/contact/roleByPage",
+                    params={"keyword": normalized_keyword, "pageNum": page_num, "pageSize": page_size},
+                )
+            except QingflowApiError as exc:
+                if _is_role_permission_denied(exc):
+                    return _contact_role_permission_denied_payload(
+                        profile=profile,
+                        ws_id=session_profile.selected_ws_id,
+                        error=exc,
+                        operation="role_search",
+                        selection={"keyword": normalized_keyword, "page_num": page_num, "page_size": page_size},
+                    )
+                raise
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
-                "keyword": keyword,
+                "keyword": normalized_keyword,
                 "page": result,
             }
 
@@ -110,3 +130,54 @@ class RoleTools(ToolBase):
             )
 
         return self._run(profile, runner)
+
+
+def _is_role_permission_denied(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    return backend_code_int(error) in {40002, 40027}
+
+
+def _contact_role_permission_denied_payload(
+    *,
+    profile: str,
+    ws_id: Any,
+    error: QingflowApiError,
+    operation: str,
+    selection: JSONObject,
+) -> JSONObject:
+    return {
+        "profile": profile,
+        "ws_id": ws_id,
+        "ok": False,
+        "status": "failed",
+        "error_code": "CONTACT_ROLE_PERMISSION_DENIED",
+        "message": (
+            "Contact role-management data is not readable for the current user. "
+            "This is a role/contact-management permission boundary, not proof that record "
+            "member or department field candidates are unavailable."
+        ),
+        "backend_code": error.backend_code,
+        "request_id": error.request_id,
+        "http_status": error.http_status,
+        "keyword": selection.get("keyword"),
+        "page": {"list": [], "total": 0, "pageAmount": 0},
+        "data": {
+            "items": [],
+            "pagination": {
+                "page": selection.get("page_num"),
+                "page_size": selection.get("page_size"),
+                "returned_items": 0,
+                "reported_total": 0,
+                "page_amount": 0,
+            },
+            "selection": selection,
+        },
+        "warnings": [
+            {
+                "code": "CONTACT_ROLE_PERMISSION_DENIED",
+                "message": "This is a role/contact-management permission boundary, not a record field candidate failure.",
+                "operation": operation,
+            }
+        ],
+    }

package/src/qingflow_mcp/tools/solution_tools.py

@@ -9,7 +9,7 @@ from mcp.server.fastmcp import FastMCP
 from pydantic import BaseModel, ValidationError
 
 from ..config import DEFAULT_PROFILE
-from ..errors import QingflowApiError
+from ..errors import QingflowApiError, backend_code_int, is_auth_like_error, raise_tool_error
 from ..list_type_labels import get_record_list_type_label
 from ..solution.build_assembly_store import BuildAssemblyStore, default_manifest
 from ..solution.compiler import CompiledSolution, ExecutionPlan, ExecutionStep, build_execution_plan, compile_solution
@@ -1615,14 +1615,15 @@ class SolutionTools(ToolBase):
                 )
             except Exception as exc:  # noqa: BLE001
                 verification["status"] = "partial"
-                verification["errors"].append(
+                error_payload = _verification_error_payload(exc)
+                error_payload.update(
                     {
                         "category": "verification",
-                        "detail": str(exc),
                         "entity_id": entity_id,
                         "app_key": app_key,
                     }
                 )
+                verification["errors"].append(error_payload)
         if verification["views_created"]:
             verification["views_strategy"] = "created"
         else:
@@ -1908,7 +1909,9 @@ class SolutionTools(ToolBase):
                 result = packages.package_get(profile=profile, tag_id=package_tag_id, include_raw=False)
             except (QingflowApiError, RuntimeError) as exc:
                 error = _coerce_solution_api_error(exc)
-                if error.backend_code in {40002, 40027}:
+                if is_auth_like_error(error):
+                    raise_tool_error(error)
+                if backend_code_int(error) in {40002, 40027}:
                     return {
                         "status": "resolved",
                         "matched_via": "tag_id",
@@ -1934,13 +1937,33 @@ class SolutionTools(ToolBase):
                     retried=False,
                 )
             summary = result.get("result") if isinstance(result.get("result"), dict) else {}
-            return {
+            resolution: dict[str, Any] = {
                 "status": "resolved",
                 "matched_via": "tag_id",
                 "tag_id": package_tag_id,
                 "tag_name": summary.get("tagName"),
                 "candidates": [],
             }
+            warnings = result.get("warnings")
+            if isinstance(warnings, list):
+                for warning in warnings:
+                    if not isinstance(warning, dict):
+                        continue
+                    if warning.get("code") not in {"PACKAGE_BASE_INFO_UNAVAILABLE", "PACKAGE_DETAIL_READ_DEGRADED"}:
+                        continue
+                    resolution["metadata_unverified"] = True
+                    resolution["lookup_permission_blocked"] = {
+                        "scope": "package",
+                        "target": {"tag_id": package_tag_id},
+                        "transport_error": {
+                            "http_status": warning.get("http_status"),
+                            "backend_code": warning.get("backend_code"),
+                            "category": "backend",
+                            "request_id": warning.get("request_id"),
+                        },
+                    }
+                    break
+            return resolution
         if not normalized_name:
             return {
                 "status": "new_package",
@@ -3090,24 +3113,30 @@ def _builder_package_resolution_failed(
     error: QingflowApiError,
     retried: bool,
 ) -> dict[str, Any]:
+    permission_restricted_listing = (
+        package_tag_id <= 0
+        and not is_auth_like_error(error)
+        and backend_code_int(error) in {40002, 40027}
+    )
     if package_tag_id > 0:
         detail = f"failed to resolve package_tag_id '{package_tag_id}': {error.message}"
-    elif error.backend_code in {40002, 40027}:
+    elif permission_restricted_listing:
         detail = (
             f"failed to resolve package '{package_name}' because package listing is permission-restricted; "
             "provide package_tag_id explicitly or use an account that can list packages"
         )
     else:
         detail = f"failed to resolve package '{package_name}': {error.message}"
-    error_fields = _solution_error_fields(category="config", detail=detail, suggested_next_call=None, stage="app")
-    error_fields["error_code"] = "PACKAGE_RESOLVE_FAILED"
+    category = "config" if permission_restricted_listing else str(error.category or "backend")
+    error_fields = _solution_error_fields(category=category, detail=detail, suggested_next_call=None, stage="app")
+    error_fields["error_code"] = "AUTH_REQUIRED" if is_auth_like_error(error) else "PACKAGE_RESOLVE_FAILED"
     return {
         "status": "failed",
         "response": {
             "status": "failed",
             "mode": "plan",
             "stage": "app",
-            "errors": [{"category": "config", "detail": detail}],
+            "errors": [{"category": category, "detail": detail}],
             "package_resolution": {
                 "status": "failed",
                 "requested_name": package_name or None,
@@ -3409,15 +3438,28 @@ def _stage_skip_reason(stage_name: str) -> str:
     return reasons.get(stage_name, "Stage skipped because no applicable payload was provided.")
 
 
+def _verification_error_payload(exc: Exception) -> dict[str, Any]:
+    payload: dict[str, Any] = {"detail": str(exc)}
+    if isinstance(exc, QingflowApiError):
+        payload["transport_error"] = {
+            "http_status": exc.http_status,
+            "backend_code": exc.backend_code,
+            "category": exc.category,
+            "request_id": exc.request_id,
+        }
+        payload["request_id"] = exc.request_id
+        payload["backend_code"] = exc.backend_code
+        payload["http_status"] = exc.http_status
+    return payload
+
+
 def _append_verification_error(verification: dict[str, Any], scope: str, exc: Exception) -> None:
     errors = verification.setdefault("errors", [])
     if isinstance(errors, list):
-        errors.append(
-            {
-                "scope": scope,
-                "message": str(exc),
-            }
-        )
+        error_payload = _verification_error_payload(exc)
+        error_payload["scope"] = scope
+        error_payload["message"] = str(exc)
+        errors.append(error_payload)
 
 
 PREFERRED_RECORD_TITLE_LABELS = (