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

package/README.md

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

package/package.json

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

package/skills/qingflow-app-builder/SKILL.md

@@ -49,6 +49,9 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - Package work:
   - use `package_get(package_id=...)` to read one known package
   - use `package_apply(...)` for package creation, rename, icon, visibility, grouping, ordering, and app/portal layout
+- Multi-app schema work:
+  - use one `app_schema_apply(apps=[...])` / CLI `builder schema apply --apps-file` when creating several apps in one package
+  - same-call relation fields may use `target_app_ref` to point at another `apps[].client_key`
 - App base permissions:
   - trust `app_get.editability.can_edit_app_base` for app base-info writes like app name, icon, and visibility
   - `can_edit_form` only means schema/form-route capability; it no longer implies app base-info write capability
@@ -97,6 +100,7 @@ Treat these as the official surface. Do not default to `package_create`, `packag
   - builder view writes use raw `view_key` values from `app_get.views`; `custom:<viewKey>` is a record-data `view_id` form, not a builder `view_key`
   - use `builder_tool_contract` whenever the minimal legal shape is unclear
   - keep view `filters` and `query_conditions` separate: `filters` are fixed saved filters; `query_conditions` configure the frontend query panel fields and only take effect after users enter query values
+  - new views default the associated report/view display area to visible with `limit_type="all"`; existing views preserve their current associated-resource display unless `associated_resources` is explicitly patched
   - configure associated reports/views through `app_associated_resources_apply`, not through `app_views_apply`
 
 ## Standard Operating Order
@@ -145,6 +149,10 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 
 ## Response Interpretation
 
+- All builder apply/write tools return a standard UI envelope in addition to legacy fields:
+  `schema_version`, `operation`, `summary`, and `resources[]`.
+- For UI cards or quick narration, read `resources[]` first. Each resource has `resource_type`, `operation`, `status`, `id`, `key`, `name`, typed `ids`, and `parent`.
+- Use legacy fields such as `field_diff`, `views_diff`, `chart_results`, `created/updated/removed`, and `verification` only for compatibility and troubleshooting.
 - Treat post-write readback as the source of truth, not just write status codes.
 - `success` means write and verification completed; `partial_success` means the write landed but verification is incomplete.
 - For portals, distinguish clearly between:

package/skills/qingflow-app-builder/references/create-app.md

@@ -37,8 +37,8 @@ then do not treat that as one app.
 Use this pattern instead:
 
 1. `package_get` or `package_apply(create_if_missing=true, package_name=...)`
-2. for each app name, run `app_schema_apply`
-3. once the apps exist, add `relation` fields between them
+2. for a multi-app system, run one `app_schema_apply` with `apps[]`
+3. use `apps[].client_key` plus relation field `target_app_ref` when one new app references another new app
 
 ## Example
 
@@ -91,6 +91,43 @@ Apply schema for a new app:
 }
 ```
 
+Apply schema for multiple apps in one call:
+
+```json
+{
+  "tool_name": "app_schema_apply",
+  "arguments": {
+    "profile": "default",
+    "package_id": 1218950,
+    "create_if_missing": true,
+    "publish": true,
+    "apps": [
+      {
+        "client_key": "customer",
+        "app_name": "客户",
+        "add_fields": [
+          {"name": "客户名称", "type": "text", "required": true, "as_data_title": true}
+        ]
+      },
+      {
+        "client_key": "order",
+        "app_name": "订单",
+        "add_fields": [
+          {"name": "订单编号", "type": "text", "required": true, "as_data_title": true},
+          {
+            "name": "关联客户",
+            "type": "relation",
+            "target_app_ref": "customer",
+            "display_field": {"name": "客户名称"},
+            "visible_fields": [{"name": "客户名称"}]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
 Data title is required: mark exactly one top-level field with `as_data_title: true`. Data cover is optional and only valid on a top-level `attachment` field.
 
 ## Common failures

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

@@ -45,7 +45,7 @@ These execute normalized patches. Some app apply tools publish by default and st
 - `app_schema_apply`: create app shell or change fields
 - `app_layout_apply`: merge or replace layout
 - `app_flow_apply`: replace workflow
-- `app_views_apply`: use `patch_views` for existing-view parameter replacement; use `upsert_views` for creation or full target config; remove views by key
+- `app_views_apply`: use `patch_views` for existing-view parameter replacement; use `upsert_views` for creation or full target config; remove views by key; new views default associated report/view display to visible with `limit_type="all"`
 - `app_custom_buttons_apply`: use `patch_buttons` for existing-button parameter replacement; use `upsert_buttons` for creation or full target config; configure add-data field mappings/default values; bind buttons to header/detail/list view positions; `placement=list` maps to the backend `INSIDE` row/list button position; merge-mode view configs require `buttons`; use `view_configs[].mode="replace"` or `buttons=[]` to clear a view's custom button bindings. For child-record creation linked to the current source record, map `source_field: "数据ID"` to the target relation field.
 - `app_associated_resources_apply`: attach existing BI reports/views to the Qingflow app associated-resource pool and per-view display area; it does not create or edit QingBI report bodies/configs. Use `patch_resources` for existing associated-resource parameter replacement; use `upsert_resources` for creation or full target config; `view_configs`, remove, and reorder may reference existing resources by internal `associated_item_id` or by `chart_id`/`chart_key`/`view_key`; use `match_mappings` for associated view/report filters; publishes after successful writes; omit raw `sourceType`, and use `report_source="dataset"` only to attach an existing BI dataset report. Before `upsert_resources`, read `app_get.associated_resources` and reuse an existing matching `target_app_key + view_key/chart_key`; repeated upsert can create duplicates because `client_key` is only valid inside one apply call.
 - `app_charts_apply`: create/edit/remove/reorder app-source QingBI report bodies/configs with `dataSourceType=qingflow`; it does not create/edit dataset BI reports and does not attach reports to Qingflow app associated-resource display. Use `patch_charts` for existing-chart parameter replacement; use `upsert_charts` for creation or full target config; supports `target/table` aliases plus QingBI chart types such as `summary`, `columnar`, `area`, `funnel`, `radar`, `scatter`, `dualaxes`, and `map`; charts are immediate-live and do not publish; use `chart_id` when names are not unique
@@ -64,7 +64,7 @@ For object-level updates, the safe partial syntax is `patch_*` with the object's
 - Create a brand new package, then create one app in it:
   `package_apply(create_if_missing=true) -> app_schema_apply`
 - Create a brand new multi-app system/package:
-  `package_apply(create_if_missing=true) -> per-app app_schema_apply -> relation field patches`
+  `package_apply(create_if_missing=true) -> app_schema_apply(apps[])`
 - Update fields on an existing app:
   `app_resolve -> app_get_fields -> app_schema_apply`
 - Tidy layout:

package/skills/qingflow-app-builder/references/update-views.md

@@ -30,7 +30,8 @@ Canonical rules before any example:
 - Treat `fields` only as a legacy alias the MCP may normalize, not as the preferred shape
 - Use `filters` with canonical keys `field_name`, `operator`, `value`/`values`
 - Use `query_conditions` for the frontend query panel. Do not put query-panel fields into `filters`.
-- Use `app_associated_resources_apply` for the frontend associated report/view area. `associated_item_id` is the internal associated-resource id from `app_get.associated_resources`; `view_configs`, remove, and reorder may also pass an existing resource's `chart_id`/`chart_key`/`view_key`, which the tool resolves to the internal id. Do not write backend raw `sourceType`; reports default to BI app reports, and dataset reports use `report_source="dataset"`. Use `match_mappings` for associated view/report filters; read `match-rules.md` if field type compatibility is unclear.
+- New views created by `app_views_apply` default the frontend associated report/view area to visible with `limit_type="all"`. Existing views preserve their current associated-resource display unless `associated_resources` is explicitly patched.
+- Use `app_associated_resources_apply` for the associated report/view resource pool, selected resources, and match rules. `associated_item_id` is the internal associated-resource id from `app_get.associated_resources`; `view_configs`, remove, and reorder may also pass an existing resource's `chart_id`/`chart_key`/`view_key`, which the tool resolves to the internal id. Do not write backend raw `sourceType`; reports default to BI app reports, and dataset reports use `report_source="dataset"`. Use `match_mappings` for associated view/report filters; read `match-rules.md` if field type compatibility is unclear.
 - For gantt, use `start_field`, `end_field`, and optionally `title_field`
 - If `app_get.views` or `app_get_views` shows duplicate view names, include `view_key` in `upsert_views[]` and update that exact target
 - Builder view writes always use the raw `view_key` from `app_get.views[].view_key`, such as `emsrao25rs02`. Do not pass `custom:emsrao25rs02`; that prefixed form is only for record-data `view_id`.

package/src/qingflow_mcp/builder_facade/models.py

@@ -1893,8 +1893,9 @@ class PortalComponentPositionPatch(StrictModel):
     pc_h: int = Field(default=8, validation_alias=AliasChoices("pc_h", "pcH", "h"))
     mobile_x: int = Field(default=0, validation_alias=AliasChoices("mobile_x", "mobileX"))
     mobile_y: int = Field(default=0, validation_alias=AliasChoices("mobile_y", "mobileY"))
-    mobile_w: int = Field(default=12, validation_alias=AliasChoices("mobile_w", "mobileW"))
+    mobile_w: int = Field(default=6, validation_alias=AliasChoices("mobile_w", "mobileW"))
     mobile_h: int = Field(default=8, validation_alias=AliasChoices("mobile_h", "mobileH"))
+    mobile_provided: bool = Field(default=False, exclude=True)
 
     @model_validator(mode="before")
     @classmethod
@@ -1904,6 +1905,8 @@ class PortalComponentPositionPatch(StrictModel):
         payload = dict(value)
         pc = payload.pop("pc", None)
         mobile = payload.pop("mobile", None)
+        mobile_keys = {"mobile_x", "mobileX", "mobile_y", "mobileY", "mobile_w", "mobileW", "mobile_h", "mobileH"}
+        mobile_provided = isinstance(mobile, dict) or any(key in payload for key in mobile_keys)
         if isinstance(pc, dict):
             if "pc_x" not in payload and "x" in pc:
                 payload["pc_x"] = pc.get("x")
@@ -1922,6 +1925,7 @@ class PortalComponentPositionPatch(StrictModel):
                 payload["mobile_w"] = mobile.get("cols")
             if "mobile_h" not in payload and "rows" in mobile:
                 payload["mobile_h"] = mobile.get("rows")
+        payload["mobile_provided"] = mobile_provided
         return payload
 
 
@@ -2003,9 +2007,10 @@ class PortalSectionPatch(StrictModel):
 class PortalApplyRequest(StrictModel):
     dash_key: str | None = None
     dash_name: str | None = None
-    package_tag_id: int | None = None
+    package_tag_id: int | None = Field(default=None, validation_alias=AliasChoices("package_tag_id", "packageTagId", "package_id", "packageId"))
     publish: bool = True
     sections: list[PortalSectionPatch] = Field(default_factory=list)
+    layout_preset: str | None = Field(default=None, validation_alias=AliasChoices("layout_preset", "layoutPreset"))
     visibility: VisibilityPatch | None = None
     auth: dict[str, Any] | None = None
     icon: str | None = None
@@ -2014,6 +2019,33 @@ class PortalApplyRequest(StrictModel):
     dash_global_config: dict[str, Any] | None = Field(default=None, validation_alias=AliasChoices("dash_global_config", "dashGlobalConfig"))
     config: dict[str, Any] = Field(default_factory=dict)
 
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_compat_payload(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        payload = dict(value)
+        if "dash_name" not in payload and "dashName" not in payload and "name" in payload:
+            payload["dash_name"] = payload.pop("name")
+        if "sections" not in payload and "pages" in payload:
+            pages = payload.pop("pages")
+            if not isinstance(pages, list):
+                raise ValueError("portal pages must be a list")
+            if len(pages) != 1:
+                raise ValueError("portal_apply currently supports a single page; pass one page or flatten components into sections")
+            page = pages[0]
+            if not isinstance(page, dict):
+                raise ValueError("portal pages[0] must be an object")
+            components = page.get("components")
+            if not isinstance(components, list) or not components:
+                raise ValueError("portal pages[0].components must be a non-empty list")
+            payload["sections"] = components
+        if "theme" in payload:
+            payload.pop("theme")
+        if "type" in payload:
+            payload.pop("type")
+        return payload
+
     @model_validator(mode="after")
     def validate_shape(self) -> "PortalApplyRequest":
         if not self.dash_key and not self.package_tag_id:
@@ -2024,6 +2056,8 @@ class PortalApplyRequest(StrictModel):
             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")
+        if self.layout_preset is not None and self.layout_preset not in {"auto", "dashboard_2col", "dashboard_3col"}:
+            raise ValueError("layout_preset must be one of: auto, dashboard_2col, dashboard_3col")
         return self
 
 
@@ -2034,8 +2068,11 @@ FieldUpdatePatch.model_rebuild()
 
 class AppGetResponse(StrictModel):
     app_key: str
+    app_name: str | None = None
+    name: str | None = None
     title: str | None = None
     app_icon: str | None = None
+    icon_config: dict[str, Any] = Field(default_factory=dict)
     visibility: dict[str, Any] = Field(default_factory=dict)
     tag_ids: list[int] = Field(default_factory=list)
     publish_status: int | None = None
@@ -2060,6 +2097,8 @@ class AppGetFieldsResponse(StrictModel):
     app_key: str
     fields: list[dict[str, Any]] = Field(default_factory=list)
     field_count: int = 0
+    chart_fields: list[dict[str, Any]] = Field(default_factory=list)
+    chart_field_count: int = 0
     form_settings: dict[str, Any] = Field(default_factory=dict)
 
 
@@ -2107,6 +2146,7 @@ class PortalReadSummaryResponse(StrictModel):
     dash_name: str | None = None
     package_tag_ids: list[int] = Field(default_factory=list)
     dash_icon: str | None = None
+    icon_config: dict[str, Any] = Field(default_factory=dict)
     hide_copyright: bool | None = None
     config_keys: list[str] = Field(default_factory=list)
     dash_global_config_keys: list[str] = Field(default_factory=list)
@@ -2120,6 +2160,7 @@ class PortalGetResponse(StrictModel):
     dash_name: str | None = None
     package_tag_ids: list[int] = Field(default_factory=list)
     dash_icon: str | None = None
+    icon_config: dict[str, Any] = Field(default_factory=dict)
     hide_copyright: bool | None = None
     visibility: dict[str, Any] = Field(default_factory=dict)
     auth: dict[str, Any] = Field(default_factory=dict)