@qingflow-tech/qingflow-app-builder-mcp 1.0.2 → 1.0.4

package/skills/qingflow-app-builder/references/tool-selection.md

@@ -4,7 +4,7 @@ Use the smallest v2 builder tool chain that can finish the task.
 
 ## Default path
 
-`resolve -> summary read -> apply -> attach -> publish_verify`
+`summary read -> apply -> publish_verify`
 
 Public builder `apply` tools already perform server-side planning, normalization, and dependency checks internally. Do not route normal public builder work through explicit `*_plan` tools.
 
@@ -21,13 +21,12 @@ If the user asks for multiple forms/modules that relate to each other, this is a
 
 ## Resolve
 
-- `package_create`: create a new package only after the user confirms package creation; exact-name duplicates return `noop=true`
-- `package_resolve`: exact package lookup by name
-- `package_list`: read-only fallback when package resolution is ambiguous
+- `package_get`: read one known package by `package_id`
+- `package_apply`: create or update one package; use `create_if_missing=true` only after explicit user intent
 - `member_search`: resolve named people from the directory
 - `role_search`: resolve reusable roles from the directory
 - `role_create`: create a reusable role when the business owner wants role-based routing
-- `app_resolve`: locate an existing app by exactly one selector mode: `app_key`, or `app_name + package_tag_id`
+- `app_resolve`: locate an existing app by exactly one selector mode: `app_key`, or `app_name + package_id`
 
 ## Summary reads
 
@@ -48,21 +47,20 @@ These execute normalized patches and publish by default unless `publish=false`.
 - `app_flow_apply`: replace workflow
 - `app_views_apply`: upsert or remove views
 - `app_charts_apply`: upsert/remove/reorder QingBI charts; charts are immediate-live and do not publish; use `chart_id` when names are not unique
-- `portal_apply`: create or replace-update portal pages; use `dash_key` for update mode or `package_tag_id + dash_name` for create mode; sections are replace-only and omission deletes old sections; `publish=false` only guarantees draft/base-info updates
+- `portal_apply`: create or replace-update portal pages; use `dash_key` for update mode or `package_id + dash_name` for create mode; edit mode may omit `sections` for base-info-only updates; when sections are supplied they still use replace semantics
 
 ## Explicit post-apply tools
 
-- `package_attach_app`: attach an app to a package with `tag_id + app_key`; do not assume create or publish attaches it
 - `app_publish_verify`: explicit final publish verification when the user asks for live confirmation
 
 ## Decision shortcuts
 
 - Create one app inside an existing package:
-  `package_resolve -> app_resolve -> app_schema_apply -> package_attach_app`
+  `package_get -> app_resolve -> app_schema_apply`
 - Create a brand new package, then create one app in it:
-  `package_create -> package_resolve -> app_schema_apply -> package_attach_app`
+  `package_apply(create_if_missing=true) -> app_schema_apply`
 - Create a brand new multi-app system/package:
-  `package_create/resolve -> per-app app_schema_apply -> package_attach_app per app -> relation field patches`
+  `package_apply(create_if_missing=true) -> per-app app_schema_apply -> relation field patches`
 - Update fields on an existing app:
   `app_resolve -> app_get_fields -> app_schema_apply`
 - Tidy layout:
@@ -81,6 +79,7 @@ These execute normalized patches and publish by default unless `publish=false`.
 - Do not handcraft raw Qingflow schema payloads
 - Do not rely on internal `solution_*` tools in public builder flows
 - Do not create a new package without first asking the user to confirm package creation
+- Do not regress to `package_create` or `package_attach_app` as the public default story
 - Do not treat a package/system name as `app_name` when the user clearly wants multiple apps inside it
 - Do not compress multiple business objects into one app with several text fields
 - Do not skip summary reads before flow or view work

package/src/qingflow_mcp/__init__.py

@@ -1,5 +1,37 @@
 from __future__ import annotations
 
+from importlib.metadata import PackageNotFoundError, packages_distributions, version as _dist_version
+from pathlib import Path
+
 __all__ = ["__version__"]
 
-__version__ = "0.2.0b87"
+_FALLBACK_VERSION = "0.2.0b1017"
+
+
+def _resolve_local_pyproject_version() -> str | None:
+    module_path = Path(__file__).resolve()
+    for parent in module_path.parents:
+        candidate = parent / "pyproject.toml"
+        if not candidate.is_file():
+            continue
+        for line in candidate.read_text(encoding="utf-8").splitlines():
+            stripped = line.strip()
+            if stripped.startswith("version = "):
+                return stripped.split("=", 1)[1].strip().strip('"')
+        break
+    return None
+
+
+def _resolve_runtime_version() -> str:
+    local_version = _resolve_local_pyproject_version()
+    if local_version:
+        return local_version
+    for dist_name in packages_distributions().get("qingflow_mcp", []):
+        try:
+            return _dist_version(dist_name)
+        except PackageNotFoundError:
+            continue
+    return _FALLBACK_VERSION
+
+
+__version__ = _resolve_runtime_version()

package/src/qingflow_mcp/backend_client.py

@@ -474,6 +474,115 @@ class BackendClient:
                 pass
         return import_result
 
+    def start_socket_record_export(
+        self,
+        context: BackendRequestContext,
+        *,
+        app_key: str,
+        view_id: str,
+        filter_bean: JSONObject,
+        export_config: JSONObject,
+        view_key: str | None = None,
+        result_amount: int = 0,
+        ack_timeout_seconds: float = 8.0,
+    ) -> dict[str, Any]:
+        try:
+            import socketio  # type: ignore[import-not-found]
+        except ImportError as exc:
+            raise QingflowApiError(
+                category="config",
+                message=f"socket.io client dependency is missing: {exc}",
+            )
+
+        socket_base_url = self._build_socket_base_url(context.base_url)
+        export_result: dict[str, Any] = {
+            "backend_export_id": None,
+            "warnings": [],
+        }
+        sio = socketio.Client(reconnection=False, logger=False, engineio_logger=False)
+        event_name = "excelViewgraph" if view_key else "excel"
+        event_args: tuple[Any, ...]
+        if view_key:
+            event_args = (
+                context.token,
+                None,
+                view_key,
+                filter_bean,
+                export_config,
+                int(result_amount),
+            )
+        else:
+            event_args = (
+                context.token,
+                app_key,
+                filter_bean,
+                export_config,
+                int(result_amount),
+            )
+        try:
+            sio.connect(
+                socket_base_url,
+                transports=["websocket"],
+                socketio_path="socket.io",
+                headers=self._base_headers(
+                    context.token,
+                    context.ws_id,
+                    qf_version=context.qf_version,
+                ),
+                wait_timeout=ack_timeout_seconds,
+            )
+            sio.emit("token", context.token)
+            sleep(0.2)
+            ack = sio.call(
+                event_name,
+                event_args,
+                timeout=ack_timeout_seconds,
+            )
+            ack_payload = ack[0] if isinstance(ack, list) and ack else ack
+            export_id: Any = ack_payload
+            if isinstance(ack_payload, dict):
+                error_code = ack_payload.get("error")
+                ack_message = ack_payload.get("message")
+                export_id = ack_payload.get("data")
+                if isinstance(export_id, dict):
+                    export_id = (
+                        export_id.get("exportId")
+                        or export_id.get("export_id")
+                        or export_id.get("id")
+                    )
+                if error_code not in (None, 0):
+                    raise QingflowApiError(
+                        category="backend",
+                        message=str(ack_message or f"socket export rejected with error {error_code}"),
+                        details={
+                            "socket_error_code": error_code,
+                            "app_key": app_key,
+                            "view_id": view_id,
+                            "view_key": view_key,
+                        },
+                    )
+            if not export_id:
+                raise QingflowApiError(category="backend", message="socket export ack did not return export_id")
+            export_result["backend_export_id"] = str(export_id)
+        except Exception as exc:
+            message = str(exc)
+            if "timeout" in message.lower():
+                raise QingflowApiError(
+                    category="network",
+                    message="socket export ack timed out",
+                    details={"error_code": "EXPORT_SOCKET_ACK_TIMEOUT"},
+                )
+            if isinstance(exc, QingflowApiError):
+                raise
+            raise QingflowApiError(category="network", message=message or "socket export failed")
+        finally:
+            try:
+                if sio.connected:
+                    sio.disconnect()
+            except Exception:
+                pass
+        return export_result
+
     def _request_with_meta(
         self,
         method: str,

package/src/qingflow_mcp/builder_facade/button_style_catalog.py

@@ -0,0 +1,282 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+BUTTON_BACKGROUND_COLORS: tuple[str, ...] = (
+    "transparent",
+    "#FB9337",
+    "#FA6F32",
+    "#FAB300",
+    "#67C200",
+    "#00BD77",
+    "#00C5FB",
+    "#268BFB",
+    "#001A72",
+    "#9E64FB",
+    "#D164FB",
+    "#FB4B51",
+    "#FFFFFF",
+)
+
+BUTTON_TEXT_COLORS: tuple[str, ...] = (
+    "#FB9337",
+    "#FA6F32",
+    "#FAB300",
+    "#67C200",
+    "#00BD77",
+    "#00C5FB",
+    "#268BFB",
+    "#001A72",
+    "#9E64FB",
+    "#D164FB",
+    "#FB4B51",
+    "#494F57",
+    "#FFFFFF",
+)
+
+BUTTON_ICONS: tuple[str, ...] = (
+    "ex-print",
+    "ex-attachment",
+    "ex-handoff",
+    "ex-delete",
+    "ex-copy",
+    "ex-share",
+    "ex-edit2",
+    "ex-admin-outlined",
+    "ex-stamp",
+    "ex-kanban",
+    "ex-update",
+    "ex-tickincircle-outlined",
+    "ex-crossincircle-outlined",
+    "ex-plus-circle",
+    "ex-logout",
+    "ex-check",
+    "ex-rename",
+    "ex-locked",
+    "ex-shift",
+    "ex-new-tabpage",
+    "ex-cross",
+    "ex-switch",
+    "ex-layer",
+    "ex-import",
+    "ex-pin-outlined",
+    "ex-disabled",
+    "ex-duplicate",
+    "ex-heart-outlined",
+    "ex-plus",
+    "ex-save",
+    "ex-upload",
+    "ex-upgrade1",
+    "ex-downgrade",
+    "ex-unfold",
+    "ex-fold",
+    "ex-sort",
+    "ex-menu-control",
+    "ex-download",
+    "ex-insert-below",
+    "ex-left-outlined-double",
+    "ex-right-outlined-double",
+    "ex-recovery",
+    "ex-layout",
+    "ex-search",
+    "ex-preview",
+    "ex-invisible",
+    "ex-carboncopy",
+    "ex-basicInfo",
+    "ex-fillIn",
+    "ex-refresh",
+    "ex-display",
+    "ex-message",
+    "ex-edit",
+    "ex-heart-filled",
+    "ex-pin-filled",
+    "ex-transfer",
+    "ex-cross-circle",
+    "ex-clock",
+    "ex-admin-filled",
+    "ex-tickincircle-circle",
+    "ex-all-application",
+    "ex-help-filled",
+    "ex-streamline",
+    "ex-table",
+    "ex-rowheight-short",
+    "ex-rowheight-medium",
+    "ex-rowheight-tall",
+    "ex-rowheight-tallest",
+)
+
+BUTTON_STYLE_PRESETS: tuple[dict[str, Any], ...] = (
+    {
+        "key": "primary_blue",
+        "label": "Primary Blue",
+        "button_type": "default",
+        "background_color": "#268BFB",
+        "text_color": "#FFFFFF",
+        "recommended_icons": ["ex-plus-circle", "ex-plus"],
+    },
+    {
+        "key": "text_blue",
+        "label": "Text Blue",
+        "button_type": "text",
+        "background_color": "transparent",
+        "text_color": "#268BFB",
+        "recommended_icons": ["ex-share", "ex-new-tabpage"],
+    },
+    {
+        "key": "warning_orange",
+        "label": "Warning Orange",
+        "button_type": "default",
+        "background_color": "#FB9337",
+        "text_color": "#FFFFFF",
+        "recommended_icons": ["ex-message", "ex-clock"],
+    },
+    {
+        "key": "danger_red",
+        "label": "Danger Red",
+        "button_type": "default",
+        "background_color": "#FB4B51",
+        "text_color": "#FFFFFF",
+        "recommended_icons": ["ex-delete", "ex-cross-circle"],
+    },
+    {
+        "key": "neutral_outline",
+        "label": "Neutral Outline",
+        "button_type": "default",
+        "background_color": "#FFFFFF",
+        "text_color": "#494F57",
+        "recommended_icons": ["ex-edit", "ex-search"],
+    },
+    {
+        "key": "secondary_gray",
+        "label": "Secondary Gray",
+        "button_type": "text",
+        "background_color": "transparent",
+        "text_color": "#494F57",
+        "recommended_icons": ["ex-edit", "ex-search"],
+    },
+)
+
+_PRESET_BY_KEY: dict[str, dict[str, Any]] = {
+    str(item["key"]).strip(): dict(item) for item in BUTTON_STYLE_PRESETS
+}
+
+_COLOR_FAMILY_BY_VALUE: dict[str, str] = {
+    "transparent": "neutral",
+    "#FB9337": "orange",
+    "#FA6F32": "orange",
+    "#FAB300": "yellow",
+    "#67C200": "green",
+    "#00BD77": "green",
+    "#00C5FB": "cyan",
+    "#268BFB": "blue",
+    "#001A72": "blue",
+    "#9E64FB": "purple",
+    "#D164FB": "purple",
+    "#FB4B51": "red",
+    "#FFFFFF": "white",
+    "#494F57": "gray",
+}
+
+
+def _normalize_color_value(value: str | None) -> str | None:
+    normalized = str(value or "").strip()
+    if not normalized:
+        return None
+    lowered = normalized.lower().replace(" ", "")
+    if lowered == "transparent":
+        return "transparent"
+    if lowered in {
+        "#fff",
+        "#ffffff",
+        "white",
+        "rgb(255,255,255)",
+        "rgba(255,255,255,1)",
+    }:
+        return "#FFFFFF"
+    if normalized.startswith("#"):
+        return normalized.upper()
+    return normalized
+
+
+def button_style_catalog_payload() -> dict[str, Any]:
+    return {
+        "icons": [{"value": icon, "label": icon} for icon in BUTTON_ICONS],
+        "background_colors": [
+            {
+                "value": color,
+                "label": color,
+                "family": _COLOR_FAMILY_BY_VALUE.get(color, "custom"),
+            }
+            for color in BUTTON_BACKGROUND_COLORS
+        ],
+        "text_colors": [
+            {
+                "value": color,
+                "label": color,
+                "family": _COLOR_FAMILY_BY_VALUE.get(color, "custom"),
+            }
+            for color in BUTTON_TEXT_COLORS
+        ],
+        "presets": [deepcopy(item) for item in BUTTON_STYLE_PRESETS],
+    }
+
+
+def resolve_button_style(
+    *,
+    style_preset: str | None,
+    button_icon: str | None,
+    background_color: str | None,
+    text_color: str | None,
+    require_complete_style: bool,
+) -> dict[str, str | None]:
+    preset_key = str(style_preset or "").strip() or None
+    resolved_icon = str(button_icon or "").strip() or None
+    resolved_background = _normalize_color_value(background_color)
+    resolved_text = _normalize_color_value(text_color)
+
+    if preset_key is not None:
+        preset = _PRESET_BY_KEY.get(preset_key)
+        if preset is None:
+            raise ValueError(
+                "unsupported style_preset; use button_style_catalog_get to inspect available presets"
+            )
+        if resolved_background is None:
+            resolved_background = str(preset["background_color"])
+        if resolved_text is None:
+            resolved_text = str(preset["text_color"])
+        if resolved_icon is None:
+            recommended = preset.get("recommended_icons") or []
+            if recommended:
+                resolved_icon = str(recommended[0]).strip() or None
+
+    if require_complete_style:
+        missing: list[str] = []
+        if resolved_icon is None:
+            missing.append("button_icon")
+        if resolved_background is None:
+            missing.append("background_color")
+        if resolved_text is None:
+            missing.append("text_color")
+        if missing:
+            raise ValueError(f"button style requires {', '.join(missing)}")
+
+    if resolved_icon is not None and resolved_icon not in BUTTON_ICONS:
+        raise ValueError(
+            "unsupported button_icon; use button_style_catalog_get to inspect available icons"
+        )
+    if resolved_background is not None and resolved_background not in BUTTON_BACKGROUND_COLORS:
+        raise ValueError(
+            "unsupported background_color; current frontend only supports template colors from button_style_catalog_get"
+        )
+    if resolved_text is not None and resolved_text not in BUTTON_TEXT_COLORS:
+        raise ValueError(
+            "unsupported text_color; current frontend only supports template colors from button_style_catalog_get"
+        )
+
+    return {
+        "style_preset": preset_key,
+        "button_icon": resolved_icon,
+        "background_color": resolved_background,
+        "text_color": resolved_text,
+    }

package/src/qingflow_mcp/builder_facade/models.py

@@ -5,6 +5,7 @@ from typing import Any
 
 from pydantic import AliasChoices, Field, model_validator
 
+from .button_style_catalog import resolve_button_style
 from ..solution.spec_models import StrictModel
 
 
@@ -819,6 +820,10 @@ class FieldMutation(StrictModel):
         validation_alias=AliasChoices("custom_button_text", "customButtonText", "custom_btn_text", "customBtnText"),
     )
     subfields: list[FieldPatch] | None = None
+    subfield_updates: list["FieldUpdatePatch"] | None = Field(
+        default=None,
+        validation_alias=AliasChoices("subfield_updates", "subfieldUpdates"),
+    )
 
     @model_validator(mode="after")
     def validate_shape(self) -> "FieldMutation":
@@ -848,8 +853,12 @@ class FieldMutation(StrictModel):
             or self.custom_button_text is not None
         ):
             raise ValueError("code_block_config, code_block_binding, auto_trigger, custom_button_text_enabled, and custom_button_text are only allowed for code_block fields")
-        if self.type == PublicFieldType.subtable and not self.subfields:
-            raise ValueError("subtable field requires subfields")
+        if self.type == PublicFieldType.subtable and not self.subfields and not self.subfield_updates:
+            raise ValueError("subtable field requires subfields or subfield_updates")
+        if self.type is not None and self.type != PublicFieldType.subtable and self.subfield_updates:
+            raise ValueError("subfield_updates are only allowed for subtable fields")
+        if self.subfields and self.subfield_updates:
+            raise ValueError("subfields and subfield_updates cannot be used together")
         return self
 
     @model_validator(mode="before")
@@ -1172,10 +1181,10 @@ def _is_white_button_color(value: str | None) -> bool:
 
 class CustomButtonPatch(StrictModel):
     button_text: str = Field(validation_alias=AliasChoices("button_text", "buttonText"))
-    background_color: str = Field(validation_alias=AliasChoices("background_color", "backgroundColor"))
-    text_color: str = Field(validation_alias=AliasChoices("text_color", "textColor"))
-    button_icon: str = Field(validation_alias=AliasChoices("button_icon", "buttonIcon"))
-    icon_color: str | None = Field(default=None, validation_alias=AliasChoices("icon_color", "iconColor"))
+    background_color: str | None = Field(default=None, validation_alias=AliasChoices("background_color", "backgroundColor"))
+    text_color: str | None = Field(default=None, validation_alias=AliasChoices("text_color", "textColor"))
+    button_icon: str | None = Field(default=None, validation_alias=AliasChoices("button_icon", "buttonIcon"))
+    style_preset: str | None = Field(default=None, validation_alias=AliasChoices("style_preset", "stylePreset"))
     trigger_action: PublicButtonTriggerAction = Field(validation_alias=AliasChoices("trigger_action", "triggerAction"))
     trigger_link_url: str | None = Field(default=None, validation_alias=AliasChoices("trigger_link_url", "triggerLinkUrl"))
     trigger_add_data_config: CustomButtonAddDataConfigPatch | None = Field(
@@ -1196,8 +1205,29 @@ class CustomButtonPatch(StrictModel):
         validation_alias=AliasChoices("trigger_wings_config", "triggerWingsConfig"),
     )
 
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_aliases(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        payload = dict(value)
+        if "icon_color" in payload or "iconColor" in payload:
+            raise ValueError("icon_color is not supported; icon color follows text_color")
+        return payload
+
     @model_validator(mode="after")
     def validate_shape(self) -> "CustomButtonPatch":
+        resolved = resolve_button_style(
+            style_preset=self.style_preset,
+            button_icon=self.button_icon,
+            background_color=self.background_color,
+            text_color=self.text_color,
+            require_complete_style=True,
+        )
+        self.style_preset = resolved["style_preset"]
+        self.button_icon = resolved["button_icon"]
+        self.background_color = resolved["background_color"]
+        self.text_color = resolved["text_color"]
         if self.trigger_action == PublicButtonTriggerAction.link and not str(self.trigger_link_url or "").strip():
             raise ValueError("link buttons require trigger_link_url")
         if self.trigger_action == PublicButtonTriggerAction.add_data and self.trigger_add_data_config is None:
@@ -1217,7 +1247,7 @@ class ViewButtonBindingPatch(StrictModel):
     button_id: int = Field(validation_alias=AliasChoices("button_id", "buttonId", "id"))
     button_text: str | None = Field(default=None, validation_alias=AliasChoices("button_text", "buttonText"))
     button_icon: str | None = Field(default=None, validation_alias=AliasChoices("button_icon", "buttonIcon"))
-    icon_color: str | None = Field(default=None, validation_alias=AliasChoices("icon_color", "iconColor"))
+    style_preset: str | None = Field(default=None, validation_alias=AliasChoices("style_preset", "stylePreset"))
     background_color: str | None = Field(default=None, validation_alias=AliasChoices("background_color", "backgroundColor"))
     text_color: str | None = Field(default=None, validation_alias=AliasChoices("text_color", "textColor"))
     trigger_action: str | None = Field(default=None, validation_alias=AliasChoices("trigger_action", "triggerAction"))
@@ -1236,6 +1266,8 @@ class ViewButtonBindingPatch(StrictModel):
         if not isinstance(value, dict):
             return value
         payload = dict(value)
+        if "icon_color" in payload or "iconColor" in payload:
+            raise ValueError("icon_color is not supported; icon color follows text_color")
         raw_button_type = payload.get("button_type", payload.get("buttonType"))
         if isinstance(raw_button_type, str):
             normalized_type = raw_button_type.strip().lower()
@@ -1257,6 +1289,21 @@ class ViewButtonBindingPatch(StrictModel):
 
     @model_validator(mode="after")
     def validate_shape(self) -> "ViewButtonBindingPatch":
+        require_complete_style = self.button_type == PublicViewButtonType.system or any(
+            str(value or "").strip()
+            for value in (self.style_preset, self.button_icon, self.background_color, self.text_color)
+        )
+        resolved = resolve_button_style(
+            style_preset=self.style_preset,
+            button_icon=self.button_icon,
+            background_color=self.background_color,
+            text_color=self.text_color,
+            require_complete_style=require_complete_style,
+        )
+        self.style_preset = resolved["style_preset"]
+        self.button_icon = resolved["button_icon"]
+        self.background_color = resolved["background_color"]
+        self.text_color = resolved["text_color"]
         if self.button_type == PublicViewButtonType.system:
             missing = [
                 field_name
@@ -1528,14 +1575,16 @@ class PortalApplyRequest(StrictModel):
             raise ValueError("package_tag_id is required when dash_key is empty")
         if not self.dash_key and not self.dash_name:
             raise ValueError("dash_name is required when creating a portal")
-        if not self.sections:
-            raise ValueError("portal apply requires a non-empty sections list")
+        if not self.dash_key and not self.sections:
+            raise ValueError("portal apply requires a non-empty sections list when creating a portal")
         if self.visibility is not None and self.auth is not None:
             raise ValueError("visibility and auth cannot be provided together")
         return self
 
 
 FieldPatch.model_rebuild()
+FieldMutation.model_rebuild()
+FieldUpdatePatch.model_rebuild()
 
 
 class AppGetResponse(StrictModel):