@josephyan/qingflow-app-builder-mcp 0.2.0-beta.3 → 0.2.0-beta.5

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-builder-mcp",
-  "version": "0.2.0-beta.3",
+  "version": "0.2.0-beta.5",
   "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.0b3"
+version = "0.2.0b5"
 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.0b3"
+__version__ = "0.2.0b5"

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",
@@ -762,16 +768,23 @@ class AiBuilderFacade:
             app_name=str(resolved["app_name"]),
             tag_ids=_coerce_int_list(resolved.get("tag_ids")),
         )
-        schema = self.apps.app_get_form_schema(
-            profile=profile,
-            app_key=target.app_key,
-            form_type=1,
-            being_draft=True,
-            being_apply=None,
-            audit_node_id=None,
-            include_raw=True,
-        )
-        schema_result = schema.get("result") if isinstance(schema.get("result"), dict) else {}
+        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"]
@@ -879,13 +892,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",
@@ -894,21 +902,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")),
@@ -917,11 +915,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,
@@ -938,16 +996,7 @@ class AiBuilderFacade:
             "sections": [section.model_dump(mode="json") for section in sections],
             "publish": publish,
         }
-        schema = self.apps.app_get_form_schema(
-            profile=profile,
-            app_key=app_key,
-            form_type=1,
-            being_draft=True,
-            being_apply=None,
-            audit_node_id=None,
-            include_raw=True,
-        )
-        schema_result = schema.get("result") if isinstance(schema.get("result"), dict) else {}
+        schema_result, _schema_source = self._read_schema_with_fallback(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}
@@ -1130,15 +1179,7 @@ class AiBuilderFacade:
                 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 = self.apps.app_get_form_schema(
-            profile=profile,
-            app_key=app_key,
-            form_type=1,
-            being_draft=True,
-            being_apply=None,
-            audit_node_id=None,
-            include_raw=True,
-        ).get("result") or {}
+        schema, _schema_source = self._read_schema_with_fallback(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":
@@ -1246,15 +1287,7 @@ class AiBuilderFacade:
             }
             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 = self.apps.app_get_form_schema(
-            profile=profile,
-            app_key=app_key,
-            form_type=1,
-            being_draft=True,
-            being_apply=None,
-            audit_node_id=None,
-            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 []
         existing_by_name = {}
         for view in existing_views if isinstance(existing_views, list) else []:
@@ -1527,27 +1560,49 @@ class AiBuilderFacade:
 
     def _load_app_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 = self.apps.app_get_form_schema(
-            profile=profile,
-            app_key=app_key,
-            form_type=1,
-            being_draft=True,
-            being_apply=None,
-            audit_node_id=None,
-            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 {}
-        schema_result = schema.get("result") if isinstance(schema.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 _read_schema_with_fallback(self, *, profile: str, app_key: str) -> tuple[dict[str, Any], str]:
+        attempts = (
+            ("draft", True),
+            ("current", None),
+            ("published", False),
+        )
+        last_error: Exception | None = None
+        for label, being_draft in attempts:
+            try:
+                schema = self.apps.app_get_form_schema(
+                    profile=profile,
+                    app_key=app_key,
+                    form_type=1,
+                    being_draft=being_draft,
+                    being_apply=None,
+                    audit_node_id=None,
+                    include_raw=True,
+                )
+                result = schema.get("result")
+                return (result if isinstance(result, dict) else {}), label
+            except (QingflowApiError, RuntimeError) as error:
+                api_error = _coerce_api_error(error)
+                last_error = error
+                if api_error.http_status == 404:
+                    continue
+                raise
+        if last_error is not None:
+            raise last_error
+        return {}, "unknown"
+
     def _preview_target_app(
         self,
         *,
@@ -1635,7 +1690,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,
@@ -1807,6 +1883,15 @@ def _coerce_int_list(values: Any) -> list[int]:
     return result
 
 
+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/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