@josephyan/qingflow-app-builder-mcp 0.2.0-beta.4 → 0.2.0-beta.6

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.4
+npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.6
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.4 qingflow-app-builder-mcp
+npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.6 qingflow-app-builder-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-builder-mcp",
-  "version": "0.2.0-beta.4",
+  "version": "0.2.0-beta.6",
   "description": "Builder MCP for Qingflow app/package/system design and staged solution workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "0.2.0b4"
+version = "0.2.0b6"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/src/qingflow_mcp/__init__.py

@@ -2,4 +2,4 @@ from __future__ import annotations
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.0b4"
+__version__ = "0.2.0b6"

package/src/qingflow_mcp/builder_facade/service.py

@@ -221,8 +221,14 @@ class AiBuilderFacade:
         if app_key:
             try:
                 base = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True)
-            except RuntimeError as exc:
-                return _failed("APP_NOT_FOUND", f"failed to resolve app_key '{app_key}'", details={"error": str(exc)})
+            except (QingflowApiError, RuntimeError) as exc:
+                api_error = _coerce_api_error(exc)
+                return _failed_from_api_error(
+                    "APP_NOT_FOUND" if api_error.http_status == 404 else "APP_RESOLVE_FAILED",
+                    api_error,
+                    details={"app_key": app_key},
+                    suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+                )
             result = base.get("result") if isinstance(base.get("result"), dict) else {}
             return {
                 "status": "success",
@@ -299,8 +305,30 @@ class AiBuilderFacade:
         }
 
     def app_read_summary(self, *, profile: str, app_key: str) -> JSONObject:
-        state = self._load_app_state(profile=profile, app_key=app_key)
+        try:
+            state = self._load_base_schema_state(profile=profile, app_key=app_key)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "APP_READ_FAILED",
+                api_error,
+                normalized_args={"app_key": app_key},
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_resolve", "arguments": {"profile": profile, "app_key": app_key}},
+            )
+        views, views_unavailable = self._load_views_result(profile=profile, app_key=app_key, tolerate_404=True)
+        workflow, workflow_unavailable = self._load_workflow_result(profile=profile, app_key=app_key, tolerate_404=True)
         parsed = state["parsed"]
+        verification_hints = _build_verification_hints(
+            tag_ids=_coerce_int_list(state["base"].get("tagIds")),
+            fields=parsed["fields"],
+            layout=parsed["layout"],
+            views=_summarize_views(views),
+        )
+        if views_unavailable:
+            verification_hints.append("views_read_unavailable")
+        if workflow_unavailable:
+            verification_hints.append("workflow_read_unavailable")
         response = AppReadSummaryResponse(
             app_key=app_key,
             title=state["base"].get("formTitle"),
@@ -308,14 +336,9 @@ class AiBuilderFacade:
             publish_status=state["base"].get("appPublishStatus"),
             field_count=len(parsed["fields"]),
             layout_section_count=len(parsed["layout"].get("sections", [])),
-            view_count=len(_summarize_views(state["views"])),
-            workflow_enabled=bool(state["workflow"]),
-            verification_hints=_build_verification_hints(
-                tag_ids=_coerce_int_list(state["base"].get("tagIds")),
-                fields=parsed["fields"],
-                layout=parsed["layout"],
-                views=_summarize_views(state["views"]),
-            ),
+            view_count=len(_summarize_views(views)),
+            workflow_enabled=bool(workflow),
+            verification_hints=verification_hints,
         )
         return {
             "status": "success",
@@ -334,7 +357,17 @@ class AiBuilderFacade:
         }
 
     def app_read_fields(self, *, profile: str, app_key: str) -> JSONObject:
-        state = self._load_app_state(profile=profile, app_key=app_key)
+        try:
+            state = self._load_base_schema_state(profile=profile, app_key=app_key)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "FIELDS_READ_FAILED",
+                api_error,
+                normalized_args={"app_key": app_key},
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
         parsed = state["parsed"]
         response = AppFieldsReadResponse(
             app_key=app_key,
@@ -368,7 +401,17 @@ class AiBuilderFacade:
         }
 
     def app_read_layout_summary(self, *, profile: str, app_key: str) -> JSONObject:
-        state = self._load_app_state(profile=profile, app_key=app_key)
+        try:
+            state = self._load_base_schema_state(profile=profile, app_key=app_key)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "LAYOUT_READ_FAILED",
+                api_error,
+                normalized_args={"app_key": app_key},
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
         parsed = state["parsed"]
         layout = parsed["layout"]
         response = AppLayoutReadResponse(
@@ -394,10 +437,20 @@ class AiBuilderFacade:
         }
 
     def app_read_views_summary(self, *, profile: str, app_key: str) -> JSONObject:
-        state = self._load_app_state(profile=profile, app_key=app_key)
+        try:
+            views, _ = self._load_views_result(profile=profile, app_key=app_key, tolerate_404=False)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "VIEWS_READ_FAILED",
+                api_error,
+                normalized_args={"app_key": app_key},
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
         response = AppViewsReadResponse(
             app_key=app_key,
-            views=_summarize_views(state["views"]),
+            views=_summarize_views(views),
         )
         return {
             "status": "success",
@@ -416,11 +469,21 @@ class AiBuilderFacade:
         }
 
     def app_read_flow_summary(self, *, profile: str, app_key: str) -> JSONObject:
-        state = self._load_app_state(profile=profile, app_key=app_key)
+        try:
+            workflow, workflow_unavailable = self._load_workflow_result(profile=profile, app_key=app_key, tolerate_404=True)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "FLOW_READ_FAILED",
+                api_error,
+                normalized_args={"app_key": app_key},
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
         response = AppFlowReadResponse(
             app_key=app_key,
-            enabled=bool(state["workflow"]),
-            nodes=_summarize_workflow_nodes(state["workflow"]),
+            enabled=bool(workflow),
+            nodes=_summarize_workflow_nodes(workflow),
             transitions=[],
         )
         return {
@@ -435,7 +498,7 @@ class AiBuilderFacade:
             "request_id": None,
             "suggested_next_call": None,
             "noop": False,
-            "verification": {"app_exists": True},
+            "verification": {"app_exists": True, "workflow_read_unavailable": workflow_unavailable},
             **response.model_dump(mode="json"),
         }
 
@@ -453,7 +516,11 @@ class AiBuilderFacade:
             return target
         current_fields: list[dict[str, Any]] = []
         if not bool(target.get("would_create")):
-            current_fields = self.app_read_fields(profile=profile, app_key=str(target["app_key"])).get("fields", [])
+            fields_result = self.app_read_fields(profile=profile, app_key=str(target["app_key"]))
+            if fields_result.get("status") == "failed":
+                fields_result.setdefault("normalized_args", normalized_args)
+                return fields_result
+            current_fields = fields_result.get("fields", [])
         current_by_name = {str(field.get("name") or ""): field for field in current_fields}
         blocking_issues: list[dict[str, Any]] = []
         preview_added: list[str] = []
@@ -511,8 +578,12 @@ class AiBuilderFacade:
 
     def app_layout_plan(self, *, profile: str, request: LayoutPlanRequest) -> JSONObject:
         read_fields = self.app_read_fields(profile=profile, app_key=request.app_key)
+        if read_fields.get("status") == "failed":
+            return read_fields
         current_names = [str(field.get("name") or "") for field in read_fields.get("fields", []) if field.get("name")]
         current_layout = self.app_read_layout_summary(profile=profile, app_key=request.app_key)
+        if current_layout.get("status") == "failed":
+            return current_layout
         requested_sections = [section.model_dump(mode="json") for section in request.sections]
         if request.preset is not None:
             requested_sections = _build_layout_preset_sections(preset=request.preset, field_names=current_names)
@@ -575,7 +646,10 @@ class AiBuilderFacade:
         transitions = [transition.model_dump(mode="json", by_alias=True) for transition in request.transitions]
         if request.preset is not None:
             nodes, transitions = _build_flow_preset(request.preset)
-        current_fields = self.app_read_fields(profile=profile, app_key=request.app_key).get("fields", [])
+        fields_result = self.app_read_fields(profile=profile, app_key=request.app_key)
+        if fields_result.get("status") == "failed":
+            return fields_result
+        current_fields = fields_result.get("fields", [])
         status_field_present = _infer_status_field_id(current_fields) is not None
         node_types = {str(node.get("type") or "") for node in nodes}
         if ("approve" in node_types or request.preset in {FlowPreset.basic_approval, FlowPreset.basic_fill_then_approve}) and not status_field_present:
@@ -645,7 +719,10 @@ class AiBuilderFacade:
         }
 
     def app_views_plan(self, *, profile: str, request: ViewsPlanRequest) -> JSONObject:
-        current_fields = self.app_read_fields(profile=profile, app_key=request.app_key).get("fields", [])
+        fields_result = self.app_read_fields(profile=profile, app_key=request.app_key)
+        if fields_result.get("status") == "failed":
+            return fields_result
+        current_fields = fields_result.get("fields", [])
         field_names = {str(field.get("name") or "") for field in current_fields}
         upsert_views = [view.model_dump(mode="json") for view in request.upsert_views]
         if request.preset is not None:
@@ -762,7 +839,23 @@ class AiBuilderFacade:
             app_name=str(resolved["app_name"]),
             tag_ids=_coerce_int_list(resolved.get("tag_ids")),
         )
-        schema_result, _schema_source = self._read_schema_with_fallback(profile=profile, app_key=target.app_key)
+        schema_readback_delayed = False
+        try:
+            schema_result, _schema_source = self._read_schema_with_fallback(profile=profile, app_key=target.app_key)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            if not bool(resolved.get("created")) or api_error.http_status != 404:
+                return _failed_from_api_error(
+                    "SCHEMA_READBACK_FAILED",
+                    api_error,
+                    normalized_args=normalized_args,
+                    allowed_values={"field_types": [item.value for item in PublicFieldType]},
+                    details={"app_key": target.app_key},
+                    suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": target.app_key}},
+                )
+            schema_result = _empty_schema_result(target.app_name)
+            _schema_source = "synthetic_new_app"
+            schema_readback_delayed = True
         parsed = _parse_schema(schema_result)
         current_fields = parsed["fields"]
         layout = parsed["layout"]
@@ -870,13 +963,8 @@ class AiBuilderFacade:
                 },
                 suggested_next_call={"tool_name": "app_read_fields", "arguments": {"profile": profile, "app_key": target.app_key}},
             )
-        verified = self.app_read(profile=profile, app_key=target.app_key, include_raw=False)
-        verified_field_names = {field["name"] for field in verified["schema"]["fields"]}
-        tag_ids_after = _coerce_int_list((self.apps.app_get_base(profile=profile, app_key=target.app_key, include_raw=True).get("result") or {}).get("tagIds"))
-        verification_ok = all(name in verified_field_names for name in added + updated) and all(name not in verified_field_names for name in removed)
-        package_attached = None if package_tag_id is None else package_tag_id in tag_ids_after
         response = {
-            "status": "success" if verification_ok and (package_attached is not False) else "partial_success",
+            "status": "success",
             "error_code": None,
             "recoverable": False,
             "message": "applied schema patch",
@@ -885,21 +973,11 @@ class AiBuilderFacade:
             "allowed_values": {"field_types": [item.value for item in PublicFieldType]},
             "details": {},
             "request_id": None,
-            "suggested_next_call": None
-            if package_attached is not False
-            else {
-                "tool_name": "package_attach_app",
-                "arguments": {
-                    "profile": profile,
-                    "tag_id": package_tag_id,
-                    "app_key": target.app_key,
-                    "app_title": app_name or target.app_name,
-                },
-            },
+            "suggested_next_call": None,
             "noop": False,
             "verification": {
-                "fields_verified": verification_ok,
-                "package_attached": package_attached,
+                "fields_verified": False,
+                "package_attached": None,
             },
             "app_key": target.app_key,
             "created": bool(resolved.get("created")),
@@ -908,11 +986,71 @@ class AiBuilderFacade:
                 "updated": updated,
                 "removed": removed,
             },
-            "verified": verification_ok,
-            "tag_ids_after": tag_ids_after,
-            "package_attached": package_attached,
+            "verified": False,
+            "tag_ids_after": [],
+            "package_attached": None,
         }
-        return self._append_publish_result(profile=profile, app_key=target.app_key, publish=publish, response=response)
+        if schema_readback_delayed:
+            response["verification"]["schema_readback_delayed"] = True
+        response = self._append_publish_result(profile=profile, app_key=target.app_key, publish=publish, response=response)
+        verification_ok = False
+        tag_ids_after: list[int] = []
+        package_attached: bool | None = None
+        verification_error: QingflowApiError | None = None
+        try:
+            verified = self.app_read(profile=profile, app_key=target.app_key, include_raw=False)
+            verified_field_names = {field["name"] for field in verified["schema"]["fields"]}
+            verification_ok = all(name in verified_field_names for name in added + updated) and all(name not in verified_field_names for name in removed)
+        except (QingflowApiError, RuntimeError) as error:
+            verification_error = _coerce_api_error(error)
+            verification_ok = False
+        try:
+            base_info = self.apps.app_get_base(profile=profile, app_key=target.app_key, include_raw=True).get("result") or {}
+            tag_ids_after = _coerce_int_list(base_info.get("tagIds"))
+            package_attached = None if package_tag_id is None else package_tag_id in tag_ids_after
+        except (QingflowApiError, RuntimeError) as error:
+            base_error = _coerce_api_error(error)
+            if verification_error is None:
+                verification_error = base_error
+            tag_ids_after = []
+            package_attached = None if package_tag_id is None else False
+        response["verification"]["fields_verified"] = verification_ok
+        response["verification"]["package_attached"] = package_attached
+        response["verified"] = verification_ok
+        response["tag_ids_after"] = tag_ids_after
+        response["package_attached"] = package_attached
+        if package_attached is False:
+            response["suggested_next_call"] = {
+                "tool_name": "package_attach_app",
+                "arguments": {
+                    "profile": profile,
+                    "tag_id": package_tag_id,
+                    "app_key": target.app_key,
+                    "app_title": app_name or target.app_name,
+                },
+            }
+        publish_failed = bool(response.get("publish_requested")) and not bool(response.get("published"))
+        if verification_ok and package_attached is not False and not publish_failed:
+            response["status"] = "success"
+        else:
+            response["status"] = "partial_success"
+        if verification_error is not None:
+            response["recoverable"] = True
+            response["error_code"] = response.get("error_code") or (
+                "READBACK_PENDING" if verification_error.http_status == 404 else "READBACK_FAILED"
+            )
+            response["message"] = f"{response.get('message') or 'apply succeeded'}; readback pending"
+            response["request_id"] = response.get("request_id") or verification_error.request_id
+            details = response.get("details")
+            if not isinstance(details, dict):
+                details = {}
+                response["details"] = details
+            details["verification_error"] = {
+                "message": verification_error.message,
+                "http_status": verification_error.http_status,
+                "backend_code": verification_error.backend_code,
+            }
+        return response
 
     def app_layout_apply(
         self,
@@ -929,7 +1067,17 @@ class AiBuilderFacade:
             "sections": [section.model_dump(mode="json") for section in sections],
             "publish": publish,
         }
-        schema_result, _schema_source = self._read_schema_with_fallback(profile=profile, app_key=app_key)
+        try:
+            schema_result, _schema_source = self._read_schema_with_fallback(profile=profile, app_key=app_key)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "LAYOUT_READ_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_layout_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
         parsed = _parse_schema(schema_result)
         current_fields = parsed["fields"]
         fields_by_name = {field["name"]: field for field in current_fields}
@@ -1060,7 +1208,32 @@ class AiBuilderFacade:
                     },
                     suggested_next_call={"tool_name": "app_layout_plan", "arguments": {"profile": profile, **normalized_args}},
                 )
-        verified = self.app_read(profile=profile, app_key=app_key, include_raw=False)
+        verified = self.app_read_layout_summary(profile=profile, app_key=app_key)
+        if verified.get("status") == "failed":
+            response = {
+                "status": "partial_success",
+                "error_code": "LAYOUT_READBACK_PENDING",
+                "recoverable": True,
+                "message": "applied app layout; layout readback pending",
+                "normalized_args": normalized_args,
+                "missing_fields": [],
+                "allowed_values": {"modes": ["merge", "replace"]},
+                "details": {},
+                "request_id": verified.get("request_id"),
+                "suggested_next_call": {"tool_name": "app_read_layout_summary", "arguments": {"profile": profile, "app_key": app_key}},
+                "noop": False,
+                "verification": {"layout_verified": False, "layout_read_unavailable": True},
+                "app_key": app_key,
+                "layout_diff": {
+                    "mode": mode.value,
+                    "replaced": mode == LayoutApplyMode.replace,
+                    "merged": mode == LayoutApplyMode.merge,
+                    "auto_added_fields": merged["auto_added_fields"] if mode == LayoutApplyMode.merge else [],
+                    "fallback_applied": fallback_applied,
+                },
+                "verified": False,
+            }
+            return self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response)
         response = {
             "status": "partial_success" if fallback_applied else "success",
             "error_code": None,
@@ -1073,7 +1246,7 @@ class AiBuilderFacade:
             "request_id": None,
             "suggested_next_call": None,
             "noop": False,
-            "verification": {"layout_verified": verified["layout"] == applied_layout},
+            "verification": {"layout_verified": verified["sections"] == applied_layout.get("sections", [])},
             "app_key": app_key,
             "layout_diff": {
                 "mode": mode.value,
@@ -1082,7 +1255,7 @@ class AiBuilderFacade:
                 "auto_added_fields": merged["auto_added_fields"] if mode == LayoutApplyMode.merge else [],
                 "fallback_applied": fallback_applied,
             },
-            "verified": verified["layout"] == applied_layout,
+            "verified": verified["sections"] == applied_layout.get("sections", []),
         }
         return self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response)
 
@@ -1111,8 +1284,18 @@ class AiBuilderFacade:
                 allowed_values={"modes": ["replace"]},
                 suggested_next_call={"tool_name": "app_flow_plan", "arguments": {"profile": profile, **normalized_args}},
             )
-        base = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True).get("result") or {}
-        schema, _schema_source = self._read_schema_with_fallback(profile=profile, app_key=app_key)
+        try:
+            base = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True).get("result") or {}
+            schema, _schema_source = self._read_schema_with_fallback(profile=profile, app_key=app_key)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "FLOW_READ_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_flow_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
         entity = _entity_spec_from_app(base_info=base, schema=schema, views=None)
         workflow_spec = _build_public_workflow_spec(nodes=nodes, transitions=transitions)
         if workflow_spec.get("status") == "failed":
@@ -1121,7 +1304,8 @@ class AiBuilderFacade:
             workflow_spec["suggested_next_call"] = {"tool_name": "app_flow_plan", "arguments": {"profile": profile, **normalized_args}}
             return workflow_spec
         desired_node_count = len([node for node in nodes if node.get("type") != "end"])
-        current_node_count = len(_summarize_workflow_nodes(self.workflows.workflow_list_nodes(profile=profile, app_key=app_key).get("result")))
+        current_workflow, _workflow_unavailable = self._load_workflow_result(profile=profile, app_key=app_key, tolerate_404=True)
+        current_node_count = len(_summarize_workflow_nodes(current_workflow))
         if current_node_count == desired_node_count and desired_node_count > 0:
             # Lightweight idempotency check for repeat submissions of same simple graph.
             pass
@@ -1165,12 +1349,12 @@ class AiBuilderFacade:
             failed["normalized_args"] = normalized_args
             failed["suggested_next_call"] = failed.get("suggested_next_call") or {"tool_name": "app_flow_plan", "arguments": {"profile": profile, **normalized_args}}
             return failed
-        verified_nodes = self.workflows.workflow_list_nodes(profile=profile, app_key=app_key).get("result")
+        verified_nodes, verified_nodes_unavailable = self._load_workflow_result(profile=profile, app_key=app_key, tolerate_404=True)
         response = {
-            "status": "success",
+            "status": "success" if bool(verified_nodes) or not verified_nodes_unavailable else "partial_success",
             "error_code": None,
-            "recoverable": False,
-            "message": "applied workflow patch",
+            "recoverable": bool(verified_nodes_unavailable),
+            "message": "applied workflow patch" if not verified_nodes_unavailable else "applied workflow patch; flow readback pending",
             "normalized_args": normalized_args,
             "missing_fields": [],
             "allowed_values": {"modes": ["replace"]},
@@ -1178,11 +1362,14 @@ class AiBuilderFacade:
             "request_id": None,
             "suggested_next_call": None,
             "noop": False,
-            "verification": {"workflow_verified": bool(verified_nodes)},
+            "verification": {"workflow_verified": bool(verified_nodes), "workflow_read_unavailable": verified_nodes_unavailable},
             "app_key": app_key,
             "flow_diff": {"mode": "replace", "node_count": desired_node_count},
             "verified": bool(verified_nodes),
         }
+        if verified_nodes_unavailable:
+            response["error_code"] = "FLOW_READBACK_PENDING"
+            response["suggested_next_call"] = {"tool_name": "app_read_flow_summary", "arguments": {"profile": profile, "app_key": app_key}}
         return self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response)
 
     def app_views_apply(
@@ -1219,9 +1406,20 @@ class AiBuilderFacade:
                 "verified": True,
             }
             return self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response)
-        base = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True).get("result") or {}
-        schema, _schema_source = self._read_schema_with_fallback(profile=profile, app_key=app_key)
-        existing_views = self.views.view_list_flat(profile=profile, app_key=app_key).get("result") or []
+        try:
+            base = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True).get("result") or {}
+            schema, _schema_source = self._read_schema_with_fallback(profile=profile, app_key=app_key)
+            existing_views, _views_unavailable = self._load_views_result(profile=profile, app_key=app_key, tolerate_404=False)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "VIEWS_READ_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_views_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
+        existing_views = existing_views or []
         existing_by_name = {}
         for view in existing_views if isinstance(existing_views, list) else []:
             if not isinstance(view, dict):
@@ -1334,22 +1532,37 @@ class AiBuilderFacade:
                         "arguments": {"profile": profile, "app_key": app_key},
                     },
                 )
-        verified_names = {item.get("viewgraphName") or item.get("viewName") or item.get("title") for item in (self.views.view_list_flat(profile=profile, app_key=app_key).get("result") or []) if isinstance(item, dict)}
-        verified = all(name in verified_names for name in created + updated) and all(name not in verified_names for name in removed)
+        try:
+            verified_view_result, verified_views_unavailable = self._load_views_result(profile=profile, app_key=app_key, tolerate_404=True)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "VIEWS_READ_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_views_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
+        verified_names = {
+            item.get("viewgraphName") or item.get("viewName") or item.get("title")
+            for item in (verified_view_result or [])
+            if isinstance(item, dict)
+        }
+        verified = (not verified_views_unavailable) and all(name in verified_names for name in created + updated) and all(name not in verified_names for name in removed)
         noop = not created and not updated and not removed
         response = {
             "status": "success" if verified else "partial_success",
-            "error_code": None,
-            "recoverable": False,
-            "message": "applied view patch",
+            "error_code": None if not verified_views_unavailable else "VIEWS_READBACK_PENDING",
+            "recoverable": bool(verified_views_unavailable),
+            "message": "applied view patch" if not verified_views_unavailable else "applied view patch; views readback pending",
             "normalized_args": normalized_args,
             "missing_fields": [],
             "allowed_values": {"view_types": ["table", "card", "board"]},
             "details": {},
             "request_id": None,
-            "suggested_next_call": None,
+            "suggested_next_call": None if not verified_views_unavailable else {"tool_name": "app_read_views_summary", "arguments": {"profile": profile, "app_key": app_key}},
             "noop": noop,
-            "verification": {"views_verified": verified},
+            "verification": {"views_verified": verified, "views_read_unavailable": verified_views_unavailable},
             "app_key": app_key,
             "views_diff": {"created": created, "updated": updated, "removed": removed},
             "verified": verified,
@@ -1364,12 +1577,33 @@ class AiBuilderFacade:
         expected_package_tag_id: int | None = None,
     ) -> JSONObject:
         normalized_args = {"app_key": app_key, "expected_package_tag_id": expected_package_tag_id}
-        base_before = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True).get("result") or {}
+        try:
+            base_before = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True).get("result") or {}
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "APP_READ_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
         tag_ids_before = _coerce_int_list(base_before.get("tagIds"))
         already_published = bool(base_before.get("appPublishStatus") in {1, 2})
         package_already_attached = None if not expected_package_tag_id else expected_package_tag_id in tag_ids_before
-        views_before = self.views.view_list_flat(profile=profile, app_key=app_key).get("result") or []
-        if already_published and package_already_attached is not False and isinstance(views_before, list):
+        try:
+            views_before, views_before_unavailable = self._load_views_result(profile=profile, app_key=app_key, tolerate_404=True)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "VIEWS_READ_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_views_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
+        views_before = views_before or []
+        if already_published and package_already_attached is not False and isinstance(views_before, list) and not views_before_unavailable:
             return {
                 "status": "success",
                 "error_code": None,
@@ -1404,17 +1638,38 @@ class AiBuilderFacade:
                 details={"app_key": app_key, "edit_version_no": edit_version_no},
                 suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
             )
-        base = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True).get("result") or {}
+        try:
+            base = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True).get("result") or {}
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "APP_READ_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
         tag_ids_after = _coerce_int_list(base.get("tagIds"))
         package_attached = None if not expected_package_tag_id else expected_package_tag_id in tag_ids_after
-        views = self.views.view_list_flat(profile=profile, app_key=app_key).get("result") or []
-        views_ok = isinstance(views, list)
+        try:
+            views, views_unavailable = self._load_views_result(profile=profile, app_key=app_key, tolerate_404=True)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "VIEWS_READ_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_views_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
+        views = views or []
+        views_ok = isinstance(views, list) and not views_unavailable
         verified = bool(base.get("appPublishStatus") in {1, 2}) and (package_attached is not False) and views_ok
         return {
             "status": "success" if verified else "partial_success",
-            "error_code": None,
-            "recoverable": False,
-            "message": "published and verified app",
+            "error_code": None if not views_unavailable else "VIEWS_READBACK_PENDING",
+            "recoverable": bool(views_unavailable),
+            "message": "published and verified app" if not views_unavailable else "published app; views readback pending",
             "normalized_args": normalized_args,
             "missing_fields": [],
             "allowed_values": {},
@@ -1427,7 +1682,7 @@ class AiBuilderFacade:
                 "arguments": {"profile": profile, "tag_id": expected_package_tag_id, "app_key": app_key},
             },
             "noop": False,
-            "verification": {"published": bool(base.get("appPublishStatus") in {1, 2}), "package_attached": package_attached, "views_ok": views_ok},
+            "verification": {"published": bool(base.get("appPublishStatus") in {1, 2}), "package_attached": package_attached, "views_ok": views_ok, "views_read_unavailable": views_unavailable},
             "app_key": app_key,
             "published": bool(base.get("appPublishStatus") in {1, 2}),
             "package_attached": package_attached,
@@ -1491,21 +1746,59 @@ class AiBuilderFacade:
                 response["suggested_next_call"] = publish_result.get("suggested_next_call")
         return response
 
-    def _load_app_state(self, *, profile: str, app_key: str) -> dict[str, Any]:
+    def _load_base_schema_state(self, *, profile: str, app_key: str) -> dict[str, Any]:
         base = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True)
         schema_result, schema_source = self._read_schema_with_fallback(profile=profile, app_key=app_key)
-        views = self.views.view_list_flat(profile=profile, app_key=app_key)
-        workflow = self.workflows.workflow_list_nodes(profile=profile, app_key=app_key)
         base_result = base.get("result") if isinstance(base.get("result"), dict) else {}
         return {
             "base": base_result,
             "schema": schema_result,
             "parsed": _parse_schema(schema_result),
-            "views": views.get("result"),
-            "workflow": workflow.get("result"),
             "schema_source": schema_source,
         }
 
+    def _load_views_result(self, *, profile: str, app_key: str, tolerate_404: bool) -> tuple[Any, bool]:
+        try:
+            views = self.views.view_list_flat(profile=profile, app_key=app_key)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            if api_error.http_status == 404:
+                try:
+                    legacy_views = self.views.view_list(profile=profile, app_key=app_key)
+                except (QingflowApiError, RuntimeError) as legacy_error:
+                    legacy_api_error = _coerce_api_error(legacy_error)
+                    if tolerate_404 and legacy_api_error.http_status == 404:
+                        return [], True
+                    raise
+                legacy_result = legacy_views.get("result")
+                if _is_view_collection_shape(legacy_result):
+                    return _normalize_view_collection(legacy_result), False
+                if tolerate_404:
+                    return [], True
+                raise error
+            raise
+        return _normalize_view_collection(views.get("result")), False
+
+    def _load_workflow_result(self, *, profile: str, app_key: str, tolerate_404: bool) -> tuple[Any, bool]:
+        try:
+            workflow = self.workflows.workflow_list_nodes(profile=profile, app_key=app_key)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            if tolerate_404 and api_error.http_status == 404:
+                return [], True
+            raise
+        return workflow.get("result"), False
+
+    def _load_app_state(self, *, profile: str, app_key: str) -> dict[str, Any]:
+        state = self._load_base_schema_state(profile=profile, app_key=app_key)
+        views, views_unavailable = self._load_views_result(profile=profile, app_key=app_key, tolerate_404=True)
+        workflow, workflow_unavailable = self._load_workflow_result(profile=profile, app_key=app_key, tolerate_404=True)
+        state["views"] = views
+        state["workflow"] = workflow
+        state["views_unavailable"] = views_unavailable
+        state["workflow_unavailable"] = workflow_unavailable
+        return state
+
     def _read_schema_with_fallback(self, *, profile: str, app_key: str) -> tuple[dict[str, Any], str]:
         attempts = (
             ("draft", True),
@@ -1623,7 +1916,28 @@ class AiBuilderFacade:
         new_app_key = str(result.get("appKey") or (result.get("appKeys")[0] if isinstance(result.get("appKeys"), list) and result.get("appKeys") else ""))
         if not new_app_key:
             return _failed("APP_CREATE_FAILED", "failed to create app shell", details={"result": result}, suggested_next_call=None)
-        base = self.apps.app_get_base(profile=profile, app_key=new_app_key, include_raw=True).get("result") or {}
+        try:
+            base = self.apps.app_get_base(profile=profile, app_key=new_app_key, include_raw=True).get("result") or {}
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            if api_error.http_status != 404:
+                return _failed_from_api_error(
+                    "APP_CREATE_READBACK_FAILED",
+                    api_error,
+                    details={"app_key": new_app_key, "app_name": app_name, "package_tag_id": package_tag_id},
+                    suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": new_app_key}},
+                )
+            return {
+                "status": "success",
+                "error_code": None,
+                "recoverable": False,
+                "message": "created app; base readback pending",
+                "suggested_next_call": None,
+                "app_key": new_app_key,
+                "app_name": app_name or "未命名应用",
+                "tag_ids": [],
+                "created": True,
+            }
         return {
             "status": "success",
             "error_code": None,
@@ -1718,18 +2032,30 @@ def _failed_from_api_error(
     suggested_next_call: JSONObject | None = None,
     recoverable: bool = True,
 ) -> JSONObject:
+    public_message = _public_error_message(error_code, error)
+    public_http_status = None if error.http_status == 404 else error.http_status
+    merged_details = dict(details or {})
+    if error.http_status is not None or error.backend_code is not None:
+        merged_details.setdefault(
+            "transport_error",
+            {
+                "http_status": error.http_status,
+                "backend_code": error.backend_code,
+                "category": error.category,
+            },
+        )
     return _failed(
         error_code,
-        error.message,
+        public_message,
         recoverable=recoverable,
         normalized_args=normalized_args,
         missing_fields=missing_fields,
         allowed_values=allowed_values,
-        details=details,
+        details=merged_details,
         suggested_next_call=suggested_next_call,
         request_id=error.request_id,
         backend_code=error.backend_code,
-        http_status=error.http_status,
+        http_status=public_http_status,
     )
 
 
@@ -1768,6 +2094,27 @@ def _coerce_api_error(error: Exception) -> QingflowApiError:
     return QingflowApiError(category="runtime", message=str(error))
 
 
+def _public_error_message(error_code: str, error: QingflowApiError) -> str:
+    if error.http_status != 404:
+        return error.message
+    mapping = {
+        "APP_READ_FAILED": "app base or schema is unavailable in the current route",
+        "FIELDS_READ_FAILED": "app fields are unavailable in the current route",
+        "LAYOUT_READ_FAILED": "layout resource is unavailable for this app in the current route",
+        "VIEWS_READ_FAILED": "views resource is unavailable for this app in the current route",
+        "FLOW_READ_FAILED": "workflow resource is unavailable for this app in the current route",
+        "SCHEMA_READBACK_FAILED": "schema was written but schema readback is unavailable in the current route",
+        "CREATE_APP_ROUTE_NOT_FOUND": "create app route is unavailable in the current workspace route",
+        "APP_CREATE_READBACK_FAILED": "app was created but base readback is unavailable in the current route",
+        "PACKAGE_ATTACH_FAILED": "package attachment could not be verified in the current route",
+        "PUBLISH_FAILED": "publish route is unavailable in the current route",
+        "VIEW_APPLY_FAILED": "view resource rejected the operation or is unavailable in the current route",
+        "LAYOUT_APPLY_FAILED": "layout resource rejected the operation or is unavailable in the current route",
+        "SCHEMA_APPLY_FAILED": "schema resource rejected the operation or is unavailable in the current route",
+    }
+    return mapping.get(error_code, "requested builder resource is unavailable in the current route")
+
+
 def _coerce_positive_int(value: Any) -> int | None:
     if isinstance(value, bool) or value is None:
         return None
@@ -1795,6 +2142,34 @@ def _coerce_int_list(values: Any) -> list[int]:
     return result
 
 
+def _normalize_view_collection(values: Any) -> list[dict[str, Any]]:
+    if isinstance(values, list):
+        return [item for item in values if isinstance(item, dict)]
+    if isinstance(values, dict):
+        for key in ("list", "viewList", "views", "result"):
+            candidate = values.get(key)
+            if isinstance(candidate, list):
+                return [item for item in candidate if isinstance(item, dict)]
+    return []
+
+
+def _is_view_collection_shape(values: Any) -> bool:
+    if isinstance(values, list):
+        return True
+    if isinstance(values, dict):
+        return any(isinstance(values.get(key), list) for key in ("list", "viewList", "views", "result"))
+    return False
+
+
+def _empty_schema_result(title: str) -> dict[str, Any]:
+    return {
+        "formTitle": title,
+        "editVersionNo": 1,
+        "formQues": [],
+        "questionRelations": [],
+    }
+
+
 def _slugify(text: str, *, default: str) -> str:
     normalized = "".join(ch.lower() if ch.isalnum() else "_" for ch in str(text or ""))
     collapsed = "_".join(part for part in normalized.split("_") if part)

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -1,8 +1,11 @@
 from __future__ import annotations
 
+import json
+
 from pydantic import ValidationError
 
 from ..config import DEFAULT_PROFILE
+from ..errors import QingflowApiError
 from ..json_types import JSONObject
 from ..builder_facade.models import (
     FieldPatch,
@@ -240,31 +243,85 @@ class AiBuilderTools(ToolBase):
             )
 
     def package_list(self, *, profile: str, trial_status: str = "all") -> JSONObject:
-        return self._facade.package_list(profile=profile, trial_status=trial_status)
+        normalized_args = {"trial_status": trial_status}
+        return _safe_tool_call(
+            lambda: self._facade.package_list(profile=profile, trial_status=trial_status),
+            error_code="PACKAGE_LIST_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "package_list", "arguments": {"profile": profile, "trial_status": trial_status}},
+        )
 
     def package_resolve(self, *, profile: str, package_name: str) -> JSONObject:
-        return self._facade.package_resolve(profile=profile, package_name=package_name)
+        normalized_args = {"package_name": package_name}
+        return _safe_tool_call(
+            lambda: self._facade.package_resolve(profile=profile, package_name=package_name),
+            error_code="PACKAGE_RESOLVE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "package_resolve", "arguments": {"profile": profile, "package_name": package_name}},
+        )
 
     def package_attach_app(self, *, profile: str, tag_id: int, app_key: str, app_title: str = "") -> JSONObject:
-        return self._facade.package_attach_app(profile=profile, tag_id=tag_id, app_key=app_key, app_title=app_title)
+        normalized_args = {"tag_id": tag_id, "app_key": app_key, "app_title": app_title}
+        return _safe_tool_call(
+            lambda: self._facade.package_attach_app(profile=profile, tag_id=tag_id, app_key=app_key, app_title=app_title),
+            error_code="PACKAGE_ATTACH_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "package_attach_app", "arguments": {"profile": profile, **normalized_args}},
+        )
 
     def app_resolve(self, *, profile: str, app_key: str = "", app_name: str = "", package_tag_id: int | None = None) -> JSONObject:
-        return self._facade.app_resolve(profile=profile, app_key=app_key, app_name=app_name, package_tag_id=package_tag_id)
+        normalized_args = {"app_key": app_key, "app_name": app_name, "package_tag_id": package_tag_id}
+        return _safe_tool_call(
+            lambda: self._facade.app_resolve(profile=profile, app_key=app_key, app_name=app_name, package_tag_id=package_tag_id),
+            error_code="APP_RESOLVE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_resolve", "arguments": {"profile": profile, **normalized_args}},
+        )
 
     def app_read_summary(self, *, profile: str, app_key: str) -> JSONObject:
-        return self._facade.app_read_summary(profile=profile, app_key=app_key)
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_read_summary(profile=profile, app_key=app_key),
+            error_code="APP_READ_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+        )
 
     def app_read_fields(self, *, profile: str, app_key: str) -> JSONObject:
-        return self._facade.app_read_fields(profile=profile, app_key=app_key)
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_read_fields(profile=profile, app_key=app_key),
+            error_code="FIELDS_READ_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_read_fields", "arguments": {"profile": profile, "app_key": app_key}},
+        )
 
     def app_read_layout_summary(self, *, profile: str, app_key: str) -> JSONObject:
-        return self._facade.app_read_layout_summary(profile=profile, app_key=app_key)
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_read_layout_summary(profile=profile, app_key=app_key),
+            error_code="LAYOUT_READ_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_read_layout_summary", "arguments": {"profile": profile, "app_key": app_key}},
+        )
 
     def app_read_views_summary(self, *, profile: str, app_key: str) -> JSONObject:
-        return self._facade.app_read_views_summary(profile=profile, app_key=app_key)
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_read_views_summary(profile=profile, app_key=app_key),
+            error_code="VIEWS_READ_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_read_views_summary", "arguments": {"profile": profile, "app_key": app_key}},
+        )
 
     def app_read_flow_summary(self, *, profile: str, app_key: str) -> JSONObject:
-        return self._facade.app_read_flow_summary(profile=profile, app_key=app_key)
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_read_flow_summary(profile=profile, app_key=app_key),
+            error_code="FLOW_READ_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_read_flow_summary", "arguments": {"profile": profile, "app_key": app_key}},
+        )
 
     def app_schema_plan(
         self,
@@ -307,7 +364,12 @@ class AiBuilderTools(ToolBase):
                     },
                 },
             )
-        return self._facade.app_schema_plan(profile=profile, request=request)
+        return _safe_tool_call(
+            lambda: self._facade.app_schema_plan(profile=profile, request=request),
+            error_code="SCHEMA_PLAN_FAILED",
+            normalized_args=request.model_dump(mode="json"),
+            suggested_next_call={"tool_name": "app_schema_plan", "arguments": {"profile": profile, **request.model_dump(mode="json")}},
+        )
 
     def app_layout_plan(
         self,
@@ -341,7 +403,12 @@ class AiBuilderTools(ToolBase):
                     },
                 },
             )
-        return self._facade.app_layout_plan(profile=profile, request=request)
+        return _safe_tool_call(
+            lambda: self._facade.app_layout_plan(profile=profile, request=request),
+            error_code="LAYOUT_PLAN_FAILED",
+            normalized_args=request.model_dump(mode="json"),
+            suggested_next_call={"tool_name": "app_layout_plan", "arguments": {"profile": profile, **request.model_dump(mode="json")}},
+        )
 
     def app_flow_plan(
         self,
@@ -378,7 +445,12 @@ class AiBuilderTools(ToolBase):
                     },
                 },
             )
-        return self._facade.app_flow_plan(profile=profile, request=request)
+        return _safe_tool_call(
+            lambda: self._facade.app_flow_plan(profile=profile, request=request),
+            error_code="FLOW_PLAN_FAILED",
+            normalized_args=request.model_dump(mode="json"),
+            suggested_next_call={"tool_name": "app_flow_plan", "arguments": {"profile": profile, **request.model_dump(mode="json")}},
+        )
 
     def app_views_plan(
         self,
@@ -412,7 +484,12 @@ class AiBuilderTools(ToolBase):
                     },
                 },
             )
-        return self._facade.app_views_plan(profile=profile, request=request)
+        return _safe_tool_call(
+            lambda: self._facade.app_views_plan(profile=profile, request=request),
+            error_code="VIEWS_PLAN_FAILED",
+            normalized_args=request.model_dump(mode="json"),
+            suggested_next_call={"tool_name": "app_views_plan", "arguments": {"profile": profile, **request.model_dump(mode="json")}},
+        )
 
     def app_schema_apply(
         self,
@@ -450,16 +527,31 @@ class AiBuilderTools(ToolBase):
                     },
                 },
             )
-        return self._facade.app_schema_apply(
-            profile=profile,
-            app_key=app_key,
-            package_tag_id=package_tag_id,
-            app_name=effective_app_name,
-            create_if_missing=create_if_missing,
-            publish=publish,
-            add_fields=parsed_add,
-            update_fields=parsed_update,
-            remove_fields=parsed_remove,
+        normalized_args = {
+            "app_key": app_key,
+            "package_tag_id": package_tag_id,
+            "app_name": effective_app_name,
+            "create_if_missing": create_if_missing,
+            "publish": publish,
+            "add_fields": [patch.model_dump(mode="json") for patch in parsed_add],
+            "update_fields": [patch.model_dump(mode="json") for patch in parsed_update],
+            "remove_fields": [patch.model_dump(mode="json") for patch in parsed_remove],
+        }
+        return _safe_tool_call(
+            lambda: self._facade.app_schema_apply(
+                profile=profile,
+                app_key=app_key,
+                package_tag_id=package_tag_id,
+                app_name=effective_app_name,
+                create_if_missing=create_if_missing,
+                publish=publish,
+                add_fields=parsed_add,
+                update_fields=parsed_update,
+                remove_fields=parsed_remove,
+            ),
+            error_code="SCHEMA_APPLY_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_schema_apply", "arguments": {"profile": profile, **normalized_args}},
         )
 
     def app_layout_apply(self, *, profile: str, app_key: str, mode: str = "merge", publish: bool = True, sections: list[JSONObject]) -> JSONObject:
@@ -495,7 +587,18 @@ class AiBuilderTools(ToolBase):
                     },
                 },
             )
-        return self._facade.app_layout_apply(profile=profile, app_key=app_key, mode=parsed_mode, publish=publish, sections=parsed_sections)
+        normalized_args = {
+            "app_key": app_key,
+            "mode": parsed_mode.value,
+            "publish": publish,
+            "sections": [section.model_dump(mode="json") for section in parsed_sections],
+        }
+        return _safe_tool_call(
+            lambda: self._facade.app_layout_apply(profile=profile, app_key=app_key, mode=parsed_mode, publish=publish, sections=parsed_sections),
+            error_code="LAYOUT_APPLY_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_layout_apply", "arguments": {"profile": profile, **normalized_args}},
+        )
 
     def app_flow_apply(
         self,
@@ -531,13 +634,25 @@ class AiBuilderTools(ToolBase):
                     },
                 },
             )
-        return self._facade.app_flow_apply(
-            profile=profile,
-            app_key=request.app_key,
-            mode=request.mode,
-            publish=publish,
-            nodes=[node.model_dump(mode="json") for node in request.nodes],
-            transitions=[transition.model_dump(mode="json", by_alias=True) for transition in request.transitions],
+        normalized_args = {
+            "app_key": request.app_key,
+            "mode": request.mode,
+            "publish": publish,
+            "nodes": [node.model_dump(mode="json") for node in request.nodes],
+            "transitions": [transition.model_dump(mode="json", by_alias=True) for transition in request.transitions],
+        }
+        return _safe_tool_call(
+            lambda: self._facade.app_flow_apply(
+                profile=profile,
+                app_key=request.app_key,
+                mode=request.mode,
+                publish=publish,
+                nodes=[node.model_dump(mode="json") for node in request.nodes],
+                transitions=[transition.model_dump(mode="json", by_alias=True) for transition in request.transitions],
+            ),
+            error_code="FLOW_APPLY_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_flow_apply", "arguments": {"profile": profile, **normalized_args}},
         )
 
     def app_views_apply(
@@ -564,10 +679,27 @@ class AiBuilderTools(ToolBase):
                     },
                 },
             )
-        return self._facade.app_views_apply(profile=profile, app_key=app_key, publish=publish, upsert_views=parsed_views, remove_views=remove_views)
+        normalized_args = {
+            "app_key": app_key,
+            "publish": publish,
+            "upsert_views": [view.model_dump(mode="json") for view in parsed_views],
+            "remove_views": list(remove_views),
+        }
+        return _safe_tool_call(
+            lambda: self._facade.app_views_apply(profile=profile, app_key=app_key, publish=publish, upsert_views=parsed_views, remove_views=remove_views),
+            error_code="VIEWS_APPLY_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_views_apply", "arguments": {"profile": profile, **normalized_args}},
+        )
 
     def app_publish_verify(self, *, profile: str, app_key: str, expected_package_tag_id: int | None = None) -> JSONObject:
-        return self._facade.app_publish_verify(profile=profile, app_key=app_key, expected_package_tag_id=expected_package_tag_id)
+        normalized_args = {"app_key": app_key, "expected_package_tag_id": expected_package_tag_id}
+        return _safe_tool_call(
+            lambda: self._facade.app_publish_verify(profile=profile, app_key=app_key, expected_package_tag_id=expected_package_tag_id),
+            error_code="PUBLISH_VERIFY_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_publish_verify", "arguments": {"profile": profile, **normalized_args}},
+        )
 
 
 def _validation_failure(detail: str, *, suggested_next_call: JSONObject | None = None) -> JSONObject:
@@ -587,3 +719,86 @@ def _validation_failure(detail: str, *, suggested_next_call: JSONObject | None =
         "noop": False,
         "verification": {},
     }
+
+
+def _safe_tool_call(
+    call,
+    *,
+    error_code: str,
+    normalized_args: JSONObject,
+    suggested_next_call: JSONObject | None,
+) -> JSONObject:
+    try:
+        return call()
+    except (QingflowApiError, RuntimeError) as error:
+        api_error = _coerce_api_error(error)
+        public_http_status = None if api_error.http_status == 404 else api_error.http_status
+        return {
+            "status": "failed",
+            "error_code": error_code,
+            "recoverable": True,
+            "message": _public_error_message(error_code, api_error),
+            "normalized_args": normalized_args,
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {
+                "transport_error": {
+                    "http_status": api_error.http_status,
+                    "backend_code": api_error.backend_code,
+                    "category": api_error.category,
+                }
+            },
+            "suggested_next_call": suggested_next_call,
+            "request_id": api_error.request_id,
+            "backend_code": api_error.backend_code,
+            "http_status": public_http_status,
+            "noop": False,
+            "verification": {},
+        }
+
+
+def _coerce_api_error(error: Exception) -> QingflowApiError:
+    if isinstance(error, QingflowApiError):
+        return error
+    if isinstance(error, RuntimeError):
+        try:
+            payload = json.loads(str(error))
+        except json.JSONDecodeError:
+            payload = None
+        if isinstance(payload, dict) and payload.get("category") and payload.get("message"):
+            details = payload.get("details")
+            return QingflowApiError(
+                category=str(payload.get("category")),
+                message=str(payload.get("message")),
+                backend_code=payload.get("backend_code"),
+                request_id=payload.get("request_id"),
+                http_status=payload.get("http_status"),
+                details=details if isinstance(details, dict) else None,
+            )
+    return QingflowApiError(category="runtime", message=str(error))
+
+
+def _public_error_message(error_code: str, error: QingflowApiError) -> str:
+    if error.http_status != 404:
+        return error.message
+    mapping = {
+        "PACKAGE_LIST_FAILED": "package list is unavailable in the current route",
+        "PACKAGE_RESOLVE_FAILED": "package resolution is unavailable in the current route",
+        "PACKAGE_ATTACH_FAILED": "package attachment could not be verified in the current route",
+        "APP_RESOLVE_FAILED": "app resolution is unavailable in the current route",
+        "APP_READ_FAILED": "app base or schema is unavailable in the current route",
+        "FIELDS_READ_FAILED": "app fields are unavailable in the current route",
+        "LAYOUT_READ_FAILED": "layout resource is unavailable for this app in the current route",
+        "VIEWS_READ_FAILED": "views resource is unavailable for this app in the current route",
+        "FLOW_READ_FAILED": "workflow resource is unavailable for this app in the current route",
+        "SCHEMA_PLAN_FAILED": "schema planning could not load the required app state in the current route",
+        "LAYOUT_PLAN_FAILED": "layout planning could not load the required app state in the current route",
+        "FLOW_PLAN_FAILED": "flow planning could not load the required app state in the current route",
+        "VIEWS_PLAN_FAILED": "views planning could not load the required app state in the current route",
+        "SCHEMA_APPLY_FAILED": "schema apply could not complete because the app route or readback is unavailable",
+        "LAYOUT_APPLY_FAILED": "layout apply could not complete because the layout route or readback is unavailable",
+        "FLOW_APPLY_FAILED": "flow apply could not complete because the workflow route or readback is unavailable",
+        "VIEWS_APPLY_FAILED": "views apply could not complete because the views route or readback is unavailable",
+        "PUBLISH_VERIFY_FAILED": "publish verification is unavailable in the current route",
+    }
+    return mapping.get(error_code, "requested builder resource is unavailable in the current route")

package/src/qingflow_mcp/tools/app_tools.py

@@ -237,7 +237,7 @@ class AppTools(ToolBase):
 
         def runner(session_profile, context):
             attempted_contexts = [context]
-            if context.qf_version is not None and (context.qf_version_source or "unset") != "explicit":
+            if context.qf_version is not None:
                 attempted_contexts.append(
                     BackendRequestContext(
                         base_url=context.base_url,
@@ -270,7 +270,6 @@ class AppTools(ToolBase):
                     is_retryable_404 = (
                         error.http_status == 404
                         and call_context.qf_version is not None
-                        and (context.qf_version_source or "unset") != "explicit"
                     )
                     if not is_retryable_404:
                         raise