@qingflow-tech/qingflow-app-builder-mcp 1.0.14 → 1.0.16

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @qingflow-tech/qingflow-app-builder-mcp@1.0.14
+npm install @qingflow-tech/qingflow-app-builder-mcp@1.0.16
 ```
 
 Run:
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-app-builder-mcp@1.0.14 qingflow-app-builder-mcp
+npx -y -p @qingflow-tech/qingflow-app-builder-mcp@1.0.16 qingflow-app-builder-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-app-builder-mcp",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "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 = "1.0.14"
+version = "1.0.16"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/src/qingflow_mcp/builder_facade/service.py

@@ -11803,6 +11803,96 @@ class AiBuilderFacade:
             "live_result": live_result,
         })
 
+    def portal_delete(self, *, profile: str, dash_key: str) -> JSONObject:
+        normalized_args = {"dash_key": dash_key}
+        dash_key = str(dash_key or "").strip()
+        if not dash_key:
+            return _failed(
+                "PORTAL_DASH_KEY_REQUIRED",
+                "dash_key is required when deleting a portal",
+                normalized_args=normalized_args,
+                missing_fields=["dash_key"],
+                suggested_next_call={"tool_name": "portal_delete", "arguments": {"profile": profile, "dash_key": "DASH_KEY"}},
+            )
+        try:
+            self.portals.portal_delete(profile=profile, dash_key=dash_key)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "PORTAL_DELETE_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"dash_key": dash_key},
+                suggested_next_call={"tool_name": "portal_delete", "arguments": {"profile": profile, **normalized_args}},
+            )
+
+        delete_readback = self._verify_portal_deleted_by_key(profile=profile, dash_key=dash_key)
+        verified = delete_readback.get("readback_status") == "deleted"
+        return {
+            "status": "success" if verified else "partial_success",
+            "error_code": None if verified else delete_readback.get("error_code") or "PORTAL_DELETE_READBACK_PENDING",
+            "recoverable": not verified,
+            "message": "deleted portal" if verified else "portal delete completed; readback pending",
+            "normalized_args": normalized_args,
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {} if verified else {"delete_readback": delete_readback},
+            "request_id": delete_readback.get("request_id"),
+            "backend_code": delete_readback.get("backend_code"),
+            "http_status": delete_readback.get("http_status"),
+            "suggested_next_call": None if verified else {"tool_name": "portal_get", "arguments": {"profile": profile, "dash_key": dash_key}},
+            "noop": False,
+            "warnings": [] if verified else [_warning("PORTAL_DELETE_READBACK_PENDING", "portal delete was sent, but deletion readback is not fully verified")],
+            "verification": {"portal_deleted": verified, "delete_readback": delete_readback},
+            "verified": verified,
+            "dash_key": dash_key,
+            "deleted": verified,
+            "delete_executed": True,
+            "readback_status": delete_readback.get("readback_status"),
+            "safe_to_retry_delete": False,
+            "write_executed": True,
+            "safe_to_retry": False,
+        }
+
+    def _verify_portal_deleted_by_key(self, *, profile: str, dash_key: str) -> JSONObject:
+        try:
+            self.portals.portal_get(profile=profile, dash_key=dash_key, being_draft=True)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            if _delete_readback_is_not_found(api_error):
+                return {
+                    "dash_key": dash_key,
+                    "operation": "delete",
+                    "status": "removed",
+                    "delete_executed": True,
+                    "readback_status": "deleted",
+                    "safe_to_retry_delete": False,
+                }
+            return {
+                "dash_key": dash_key,
+                "operation": "delete",
+                "status": "readback_pending",
+                "delete_executed": True,
+                "readback_status": "unavailable",
+                "safe_to_retry_delete": False,
+                "error_code": "PORTAL_DELETE_READBACK_UNAVAILABLE",
+                "message": "delete request completed, but portal existence could not be verified by dash_key readback",
+                "request_id": api_error.request_id,
+                "backend_code": api_error.backend_code,
+                "http_status": None if api_error.http_status == 404 else api_error.http_status,
+                "transport_error": _transport_error_payload(api_error),
+            }
+        return {
+            "dash_key": dash_key,
+            "operation": "delete",
+            "status": "readback_pending",
+            "delete_executed": True,
+            "readback_status": "still_exists",
+            "safe_to_retry_delete": False,
+            "error_code": "PORTAL_DELETE_READBACK_STILL_EXISTS",
+            "message": "delete request completed, but the portal still exists during dash_key readback",
+        }
+
     def _publish_current_edit_version(self, *, profile: str, app_key: str, edit_version_no: int | None = None) -> JSONObject:
         normalized_args = {"app_key": app_key}
         if edit_version_no is None:

package/src/qingflow_mcp/cli/commands/builder.py

@@ -179,6 +179,10 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     portal_apply.add_argument("--config-file")
     portal_apply.set_defaults(handler=_handle_portal_apply, format_hint="builder_summary", force_json_output=True)
 
+    portal_delete = portal_subparsers.add_parser("delete", help="删除门户")
+    portal_delete.add_argument("--dash-key", required=True)
+    portal_delete.set_defaults(handler=_handle_portal_delete, format_hint="builder_summary", force_json_output=True)
+
     schema_apply = builder_subparsers.add_parser("schema", help="字段搭建")
     schema_apply_subparsers = schema_apply.add_subparsers(dest="builder_schema_command", required=True)
     schema_apply_apply = schema_apply_subparsers.add_parser("apply", help="执行字段变更")
@@ -614,6 +618,13 @@ def _handle_portal_apply(args: argparse.Namespace, context: CliContext) -> dict:
     )
 
 
+def _handle_portal_delete(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.portal_delete(
+        profile=args.profile,
+        dash_key=args.dash_key,
+    )
+
+
 def _handle_publish_verify(args: argparse.Namespace, context: CliContext) -> dict:
     return context.builder.app_publish_verify(
         profile=args.profile,

package/src/qingflow_mcp/cli/main.py

@@ -208,6 +208,8 @@ def _builder_apply_operation_from_args(args: argparse.Namespace) -> str | None:
         return "app_associated_resources_apply"
     if section == "portal" and getattr(args, "builder_portal_command", "") == "apply":
         return "portal_apply"
+    if section == "portal" and getattr(args, "builder_portal_command", "") == "delete":
+        return "portal_delete"
     if section == "schema" and getattr(args, "builder_schema_command", "") == "apply":
         return "app_schema_apply"
     if section == "layout" and getattr(args, "builder_layout_command", "") == "apply":
@@ -229,7 +231,7 @@ def _builder_apply_operation_from_argv(argv: list[str]) -> str | None:
         return None
     section = tokens[1]
     action = tokens[2]
-    if action != "apply" and not (section == "publish" and action == "verify"):
+    if action != "apply" and not (section == "publish" and action == "verify") and not (section == "portal" and action == "delete"):
         return None
     mapping = {
         "package": "package_apply",
@@ -244,6 +246,8 @@ def _builder_apply_operation_from_argv(argv: list[str]) -> str | None:
         "charts": "app_charts_apply",
         "publish": "app_publish_verify",
     }
+    if section == "portal" and action == "delete":
+        return "portal_delete"
     return mapping.get(section)
 
 

package/src/qingflow_mcp/public_surface.py

@@ -162,6 +162,7 @@ BUILDER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
     PublicToolSpec(BUILDER_DOMAIN, "app_views_apply", ("app_views_apply",), ("builder", "views", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(BUILDER_DOMAIN, "app_charts_apply", ("app_charts_apply",), ("builder", "charts", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(BUILDER_DOMAIN, "portal_apply", ("portal_apply",), ("builder", "portal", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "portal_delete", ("portal_delete",), ("builder", "portal", "delete"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(BUILDER_DOMAIN, "app_publish_verify", ("app_publish_verify",), ("builder", "publish", "verify"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
 )
 

package/src/qingflow_mcp/response_trim.py

@@ -1203,6 +1203,7 @@ _register_policy(
         "app_views_apply",
         "app_charts_apply",
         "portal_apply",
+        "portal_delete",
         "app_publish_verify",
     ),
     _trim_builder_list_like,

package/src/qingflow_mcp/server_app_builder.py

@@ -39,7 +39,7 @@ def build_builder_server() -> FastMCP:
             "Use workspace_icon_catalog_get before creating app packages, apps, or portals when supported icon/color candidates are needed; new workspace resources require explicit non-template icon + color, and the CLI validates choices without inferring business defaults. "
             "app_get as the default app map read, then app_get_fields/app_repair_code_blocks/app_get_layout/app_get_views/app_get_flow/app_get_charts/portal_list/portal_get/view_get/chart_get for focused configuration reads, "
             "member_search/role_search/role_create when workflow assignees must come from the directory or role catalog, preferring roles over explicit members unless the user explicitly names members, "
-            "then app_schema_apply/app_layout_apply/app_flow_apply/app_views_apply/app_custom_buttons_apply/app_associated_resources_apply/app_charts_apply/portal_apply to execute normalized patches; these apply tools perform planning, normalization, and dependency checks internally where applicable. Schema/layout/views noop requests skip publish, app_custom_buttons_apply and app_associated_resources_apply publish after at least one write succeeds and expose no draft-only parameter, charts are immediate-live without publish and resolve targets by chart_id first then exact unique chart name, portal updates use replace semantics only when sections are supplied and edit-mode base-info-only updates may omit sections, portal pc layout is a 24-column grid and mobile is a 6-column grid so omit position or use layout_preset when unsure, publish=false only guarantees draft/base-info updates for tools that still expose that parameter, and flow should use publish=false whenever you only want draft/precheck behavior. "
+            "then app_schema_apply/app_layout_apply/app_flow_apply/app_views_apply/app_custom_buttons_apply/app_associated_resources_apply/app_charts_apply/portal_apply/portal_delete to execute normalized patches; these apply/delete tools perform planning, normalization, and dependency checks internally where applicable. Schema/layout/views noop requests skip publish, app_custom_buttons_apply and app_associated_resources_apply publish after at least one write succeeds and expose no draft-only parameter, charts are immediate-live without publish and resolve targets by chart_id first then exact unique chart name, portal updates use replace semantics only when sections are supplied and edit-mode base-info-only updates may omit sections, portal delete separates DELETE execution from readback verification, portal pc layout is a 24-column grid and mobile is a 6-column grid so omit position or use layout_preset when unsure, publish=false only guarantees draft/base-info updates for tools that still expose that parameter, and flow should use publish=false whenever you only want draft/precheck behavior. "
             "Builder apply/write outputs include schema_version, operation, summary, and resources[]; use resources[].id/key/name/ids/parent as the stable UI and agent display entry, and keep legacy fields such as field_diff/views_diff/chart_results only for compatibility or troubleshooting. "
             "For existing object parameter replacement, prefer patch_views, patch_buttons, patch_resources, and patch_charts with set/unset; the tool reads current config and full-saves internally, while upsert_* is for creation or full target configuration and should not be used as an incomplete partial update. "
             "For builder delete/remove apply results, separate delete execution from readback verification: after DELETE is sent, resources expose delete_executed, readback_status, and safe_to_retry_delete=false. If readback_status is unavailable or still_exists, do not blindly repeat the delete; confirm later with app_get/view_get/chart_get or the relevant apply readback. Views/buttons use single-item readback; associated resources use one app-level resource-pool readback because there is no confirmed single-item GET. "
@@ -595,6 +595,16 @@ def build_builder_server() -> FastMCP:
             payload=payload,
         )
 
+    @server.tool()
+    def portal_delete(
+        profile: str = DEFAULT_PROFILE,
+        dash_key: str = "",
+    ) -> dict:
+        return ai_builder.portal_delete(
+            profile=profile,
+            dash_key=dash_key,
+        )
+
     @server.tool()
     def app_publish_verify(
         profile: str = DEFAULT_PROFILE,

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -91,6 +91,7 @@ BUILDER_APPLY_TOOL_NAMES = {
     "app_associated_resources_apply",
     "app_charts_apply",
     "portal_apply",
+    "portal_delete",
     "app_publish_verify",
 }
 
@@ -553,6 +554,13 @@ class AiBuilderTools(ToolBase):
                 payload=payload,
             )
 
+        @mcp.tool(description=self._high_risk_tool_description(operation="delete", target="portal"))
+        def portal_delete(
+            profile: str = DEFAULT_PROFILE,
+            dash_key: str = "",
+        ) -> JSONObject:
+            return self.portal_delete(profile=profile, dash_key=dash_key)
+
         @mcp.tool()
         def app_publish_verify(
             profile: str = DEFAULT_PROFILE,
@@ -2600,6 +2608,18 @@ class AiBuilderTools(ToolBase):
         ))
         return _attach_builder_apply_envelope("portal_apply", result)
 
+    @tool_cn_name("门户删除")
+    def portal_delete(self, *, profile: str, dash_key: str) -> JSONObject:
+        """执行门户删除逻辑。"""
+        normalized_args = {"dash_key": dash_key}
+        result = _publicize_package_fields(_safe_tool_call(
+            lambda: self._facade.portal_delete(profile=profile, dash_key=dash_key),
+            error_code="PORTAL_DELETE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "portal_delete", "arguments": {"profile": profile, **normalized_args}},
+        ))
+        return _attach_builder_apply_envelope("portal_delete", result)
+
     @tool_cn_name("应用发布校验")
     def app_publish_verify(
         self,
@@ -3182,6 +3202,8 @@ def _builder_apply_resources(tool_name: str, payload: JSONObject) -> list[JSONOb
         resources = _builder_chart_resources(payload)
     elif tool_name == "portal_apply":
         resources = _builder_portal_resources(payload)
+    elif tool_name == "portal_delete":
+        resources = _builder_portal_resources(payload, operation_override="removed")
     elif tool_name == "app_custom_buttons_apply":
         resources = _builder_button_resources(payload)
     elif tool_name == "app_associated_resources_apply":
@@ -3377,7 +3399,15 @@ def _builder_package_resources(payload: JSONObject) -> list[JSONObject]:
     package_id = payload.get("package_id") or payload.get("id")
     package_name = payload.get("package_name") or payload.get("name")
     status = _builder_status(payload, "success")
-    operation = "failed" if status == "failed" else ("created" if bool(payload.get("created")) else "updated")
+    operation = (
+        "failed"
+        if status == "failed"
+        else "removed"
+        if bool(payload.get("deleted")) or bool(payload.get("delete_executed"))
+        else "created"
+        if bool(payload.get("created"))
+        else "updated"
+    )
     normalized_args = payload.get("normalized_args") if isinstance(payload.get("normalized_args"), dict) else {}
     icon_config = (
         _builder_container_icon_config(payload, raw_keys=("icon", "tagIcon", "tag_icon"))
@@ -3629,7 +3659,7 @@ def _builder_chart_resources(payload: JSONObject) -> list[JSONObject]:
     return resources
 
 
-def _builder_portal_resources(payload: JSONObject) -> list[JSONObject]:
+def _builder_portal_resources(payload: JSONObject, *, operation_override: str | None = None) -> list[JSONObject]:
     status = _builder_status(payload, "success")
     draft_result = payload.get("draft_result") if isinstance(payload.get("draft_result"), dict) else {}
     live_result = payload.get("live_result") if isinstance(payload.get("live_result"), dict) else {}
@@ -3660,7 +3690,7 @@ def _builder_portal_resources(payload: JSONObject) -> list[JSONObject]:
         first_tag = draft_result.get("tags")[0]
         if isinstance(first_tag, dict):
             package_id = first_tag.get("tagId") or first_tag.get("tag_id") or first_tag.get("id")
-    operation = "failed" if status == "failed" else ("created" if bool(payload.get("created")) else "updated")
+    operation = operation_override or ("failed" if status == "failed" else ("created" if bool(payload.get("created")) else "updated"))
     parent = None
     if package_id:
         parent = _builder_parent("package", id_value=package_id, key=package_id)
@@ -5507,6 +5537,20 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             },
         },
     },
+    "portal_delete": {
+        "allowed_keys": ["dash_key"],
+        "aliases": {"dashKey": "dash_key"},
+        "allowed_values": {},
+        "execution_notes": [
+            "deletes one portal by dash_key",
+            "delete results separate DELETE execution from readback verification",
+            "if delete_executed=true and readback_status=unavailable or still_exists, do not blindly repeat delete; confirm later with portal_get or portal_list",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "dash_key": "DASH_KEY",
+        },
+    },
     "app_publish_verify": {
         "allowed_keys": ["app_key", "expected_package_id"],
         "aliases": {},