@josephyan/qingflow-app-builder-mcp 1.1.21 → 1.1.22

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-builder-mcp@1.1.21
+npm install @josephyan/qingflow-app-builder-mcp@1.1.22
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-builder-mcp@1.1.21 qingflow-app-builder-mcp
+npx -y -p @josephyan/qingflow-app-builder-mcp@1.1.22 qingflow-app-builder-mcp
 ```
 
 Environment:

package/package.json

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

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

@@ -119,7 +119,7 @@ Treat these as the official surface. Do not default to `package_create`, `packag
   - do not use `summary` for a single metric card; use `target` / `indicator`
   - supported `chart_type` values include legacy public aliases `target`, `table` and QingBI types such as `summary`, `columnar`, `area`, `stacked_area`, `funnel`, `waterfall`, `gauge`, `heatmap`, `histogram`, `treemap`, `radar`, `stacked_bar`, `stacked_column`, `scatter`, `ring`, `rose`, `dualaxes`, `map`, and `timeline`
   - chart `filters` use the unified fixed-filter DSL: `field_name + operator + value/values`; the tool compiles them to QingBI string judge types
-  - for complete systems, submit `upsert_charts` in batches of 4-8. More than 8 upserts is blocked before write with `CHART_UPSERT_BATCH_TOO_LARGE`; execute `details.suggested_batch_payloads[]` one batch at a time.
+  - for complete systems, keep chart payloads business-scoped, commonly 4-8 `upsert_charts` by app or topic. Larger calls are accepted; if `CHART_UPSERT_BATCH_SIZE_RECOMMENDED` appears, read back before retrying and only repair failed items.
   - use `patch_charts` for changing a chart name, visibility, filters, or one config fragment on an existing chart
   - `visibility` is a public capability and should be treated as a base-only permission update
   - do not model chart visibility changes as raw config rewrites

package/skills/qingflow-app-builder/references/complete-system-development-guide.md

@@ -43,7 +43,7 @@ Optional:
 5. For each app, apply layout.
 6. Apply workflow with `app_flow_apply` when the user asks for approval, fill, copy, reminders, or process routing.
 7. Apply views; declare ordinary business buttons in `action_buttons` while designing the core operating views.
-8. Create charts before portals when the portal needs metrics or BI sections. Submit chart upserts in batches of 4-8; if `CHART_UPSERT_BATCH_TOO_LARGE` appears, execute `details.suggested_batch_payloads[]` one at a time.
+8. Create charts before portals when the portal needs metrics or BI sections. Keep chart payloads business-scoped, commonly 4-8 upserts by app or topic. Larger calls are accepted; if `CHART_UPSERT_BATCH_SIZE_RECOMMENDED` appears, read back before retrying and only repair failed items.
 9. Add associated resources and advanced standalone buttons when they are part of the requested business process.
 10. Create portal only after referenced apps, views, and charts are known.
 11. Before the final response, write the complete-system delivery summary file described below.
@@ -76,7 +76,7 @@ Optional:
 - Two-metric comparison uses `dualaxes` with `left_metric` and `right_metric`.
 - Do not use `summary` for a single KPI; `summary` is for table-style grouped summaries.
 - Do not handwrite raw `indicator_field_ids`, `selectedMetrics`, or QingBI filter matrices on the main path.
-- For complete systems, submit new charts in batches of 4-8.
+- For complete systems, keep new chart writes business-scoped, commonly 4-8 charts by app or topic; larger calls are accepted but should be read back before retrying.
 
 ## Button Rules
 

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

@@ -16,7 +16,7 @@ Hierarchy reminder:
 - package -> app -> field -> relation
 - another business object is another app, not a text field
 
-If creating a brand new package would help, ask the user to confirm package creation first. After confirmation, create it through `package_apply(create_if_missing=true, package_name=...)`.
+If creating a brand new package would help, ask the user to confirm package creation first. After confirmation, create it through `package_apply(package_name=..., icon=..., color=...)`.
 
 ## Minimal sequence
 
@@ -37,7 +37,7 @@ then do not treat that as one app.
 
 Use this pattern instead:
 
-1. `package_get` or `package_apply(create_if_missing=true, package_name=...)`
+1. `package_get` or `package_apply(package_name=..., icon=..., color=...)`
 2. for a multi-app system, run one `app_schema_apply` with `package_id` and `apps[]`
 3. use `apps[].client_key` plus relation field `target_app_ref` when one new app references another new app
 
@@ -64,7 +64,6 @@ Create a new package only after the user confirms package creation:
   "arguments": {
     "profile": "default",
     "package_name": "研发项目管理",
-    "create_if_missing": true,
     "icon": "briefcase",
     "color": "azure"
   }
@@ -94,7 +93,6 @@ Apply schema for a new app:
     "package_id": 1218950,
     "icon": "delivery-box-1",
     "color": "emerald",
-    "create_if_missing": true,
     "publish": true,
     "add_fields": [
       {"name": "订单编号", "type": "text", "required": true, "as_data_title": true},
@@ -117,7 +115,6 @@ Apply schema for multiple apps in one call:
   "arguments": {
     "profile": "default",
     "package_id": 1218950,
-    "create_if_missing": true,
     "publish": true,
     "apps": [
       {
@@ -156,7 +153,7 @@ Data title is required: mark exactly one top-level field with `as_data_title: tr
 
 ### `APP_NOT_FOUND`
 
-Expected on create. Continue with `create_if_missing=true`.
+For new apps, submit `app_schema_apply` with `package_id + app_name + icon + color`. For existing apps, resolve and pass the real `app_key`.
 
 ### `CREATE_APP_ROUTE_NOT_FOUND`
 

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

@@ -38,7 +38,7 @@ Decision gate before writing:
 ## Resolve
 
 - `package_get`: read one known package by `package_id`; it reads package `baseInfo` first and may warn `PACKAGE_DETAIL_READ_DEGRADED` when the richer detail endpoint needs package edit/add-app permission. Treat that warning as degraded detail, not as package-read failure.
-- `package_apply`: create or update one package; use `create_if_missing=true` only after explicit user intent; layout/group/order changes require package edit permission because they call the backend package ordering route
+- `package_apply`: create or update one package; `package_name` without `package_id` creates a package; layout/group/order changes require package edit permission because they call the backend package ordering route
 - `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
@@ -65,7 +65,7 @@ These execute normalized patches. Some app apply tools publish by default and st
 - `app_views_apply`: use `patch_views` for existing-view parameter replacement; use `upsert_views` for creation or full target config; remove views by key; for normal view-specific business buttons, declare `action_buttons` in the view object or `patch_views[].set`; new views default associated report/view display to visible with `limit_type="all"`
 - `app_custom_buttons_apply`: advanced custom-button maintenance only: style/icon changes, cross-view reuse, deleting button bodies, bulk reordering bindings, or exact qRobot/wings configs. Use `patch_buttons` for existing-button parameter replacement; use `upsert_buttons` for creation or full target config; 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. Permission is split like the backend: resource pool writes use EditAppAuth, while `view_configs` uses the view config/DataManageAuth path. 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` with `target_field + operator + source_field/value` 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 `app_get_fields.chart_fields` as the source for dimensions, metrics, and filters. Use semantic `metric`, `metrics`, `group_by`, and `where`: `target/indicator` for one KPI, `bar/columnar/pie` for distribution, `line/area` for trend, `table/detail/summary` for tabular summaries, and `dualaxes` for two-metric comparison. Do not use `summary` for a single metric card. Use `filters` with `field_name + operator + value/values`; the tool compiles them to QingBI string judge types. Use `patch_charts` for existing-chart parameter replacement; use `upsert_charts` for creation or full target config; avoid raw `indicator_field_ids`, `selectedMetrics`, and QingBI filter matrices on the main path; charts are immediate-live and do not publish; use `chart_id` when names are not unique; for complete systems, submit large chart sets in batches of 4-8 upserts. More than 8 upserts is blocked before write with `CHART_UPSERT_BATCH_TOO_LARGE`; execute `details.suggested_batch_payloads[]` one batch at a time.
+- `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 `app_get_fields.chart_fields` as the source for dimensions, metrics, and filters. Use semantic `metric`, `metrics`, `group_by`, and `where`: `target/indicator` for one KPI, `bar/columnar/pie` for distribution, `line/area` for trend, `table/detail/summary` for tabular summaries, and `dualaxes` for two-metric comparison. Do not use `summary` for a single metric card. Use `filters` with `field_name + operator + value/values`; the tool compiles them to QingBI string judge types. Use `patch_charts` for existing-chart parameter replacement; use `upsert_charts` for creation or full target config; avoid raw `indicator_field_ids`, `selectedMetrics`, and QingBI filter matrices on the main path; charts are immediate-live and do not publish; use `chart_id` when names are not unique; for complete systems, keep chart writes business-scoped, commonly 4-8 upserts by app or topic. Larger calls are accepted; if `CHART_UPSERT_BATCH_SIZE_RECOMMENDED` appears, read back before retrying and only repair failed items.
 - `portal_apply`: create or replace-update portal pages; use `dash_key` for update mode or `package_id + dash_name` for create mode; create mode only prechecks package add_app, matching backend portal creation; edit mode may omit `sections` for base-info-only updates; when sections are supplied they still use replace semantics. Build portals only after referenced apps, raw `view_key`s, and chart ids/keys are known. PC layout uses 24 columns: components with the same `y` must have the same `rows`, same-row `cols` should sum to 24, metric cards use `rows=5`, BI charts use `rows=7`, data views use `rows=11`, and business-entry grids must include real `config.items[]`. Use business entry -> metrics -> BI charts -> concrete data views; do not use platform default views or raw `source_type: "filter"` as the main path.
 
 For object-level updates, the safe partial syntax is `patch_*` with the object's real selector field plus `set` and optional `unset`. `selector` is only a concept, not a literal key. Examples: `patch_views: [{"view_key": "VIEW_KEY", "set": {...}}]`, `patch_buttons: [{"button_id": 1001, "set": {...}}]`, `patch_resources: [{"associated_item_id": 123, "set": {...}}]`, `patch_charts: [{"chart_id": 456, "set": {...}}]`. The tool reads the current backend config, merges the patch, then submits the full backend payload internally. Do not send a partial `upsert_*` and expect missing required fields to be preserved.
@@ -79,9 +79,9 @@ For object-level updates, the safe partial syntax is `patch_*` with the object's
 - Create one app inside an existing package:
   `package_get -> app_resolve -> app_schema_apply`
 - Create a brand new package, then create one app in it:
-  `package_apply(create_if_missing=true) -> app_schema_apply`
+  `package_apply(package_name, icon, color) -> app_schema_apply`
 - Create a brand new multi-app system/package:
-  `package_apply(create_if_missing=true) -> app_schema_apply(apps[])`; use `apps[].client_key` plus `target_app_ref`, or `target_app` when referencing by app name
+  `package_apply(package_name, icon, color) -> app_schema_apply(apps[])`; use `apps[].client_key` plus `target_app_ref`, or `target_app` when referencing by app name
 - Update fields on an existing app:
   `app_resolve -> app_get_fields -> app_schema_apply`
 - Tidy layout:

package/src/qingflow_mcp/builder_facade/models.py

@@ -2603,7 +2603,6 @@ class SchemaPlanRequest(StrictModel):
     icon: str | None = None
     color: str | None = None
     visibility: VisibilityPatch | None = None
-    create_if_missing: bool = False
     add_fields: list[FieldPatch] = Field(default_factory=list)
     update_fields: list[FieldUpdatePatch] = Field(default_factory=list)
     remove_fields: list[FieldRemovePatch] = Field(default_factory=list)