@qingflow-tech/qingflow-app-builder-mcp 1.0.8 → 1.0.10

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-app-builder-mcp",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "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.8"
+version = "1.0.10"
 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
@@ -61,7 +64,10 @@ Treat these as the official surface. Do not default to `package_create`, `packag
   - in edit mode, omitting `sections` means “preserve existing layout and update base info only”
   - supplying `sections` means full replace semantics for sections
 - Chart work:
-  - `app_charts_apply` is the public write path
+  - `app_charts_apply` is the public write path for app-source QingBI report bodies/configs; it creates/updates reports with `dataSourceType=qingflow`
+  - dataset BI reports are not created or edited by `app_charts_apply` yet; create them in QingBI first, then attach the existing report with `app_associated_resources_apply` and `report_source="dataset"`
+  - it does not attach the report to the Qingflow app associated-resource display; use `app_associated_resources_apply` for that
+  - 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`
   - 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
@@ -79,12 +85,13 @@ Treat these as the official surface. Do not default to `package_create`, `packag
   - `placement=list` configures row/list buttons and maps to the backend `INSIDE` button position
   - advanced bindings may use `button_limit`, `button_formula`, `button_formula_type`, and `print_tpls` only when visibility or print-template behavior is required
 - Associated resources:
-  - `app_associated_resources_apply` is the public write path for the app-level associated report/view pool and per-view display config
+  - `app_associated_resources_apply` is the public write path for the Qingflow app-level associated report/view pool and per-view display config
+  - it attaches existing BI reports/views for in-app display; it does not create or edit QingBI report bodies/configs, including dataset reports
   - use `patch_resources` for changing match rules or other existing associated-resource parameters; the tool preserves backend-required raw fields internally
-  - `associated_item_id` must come from `app_get.associated_resources[].associated_item_id`; it is not `chart_id`, `chart_key`, or `view_key`
+  - `associated_item_id` is the backend internal associated-resource id; for `view_configs`, `remove_associated_item_ids`, and `reorder_associated_item_ids`, you may pass `associated_item_id` or an existing resource's `chart_id`/`chart_key`/`view_key`, and the tool resolves it to the internal id
   - before creating a resource, check `app_get.associated_resources` for the same `target_app_key + view_key/chart_key`; if it already exists, use `patch_resources` with that `associated_item_id`
   - `client_key` is only a same-call reference for `view_configs[].associated_item_refs`; it is not saved and cannot deduplicate later calls
-  - do not pass backend raw `sourceType`; view resources infer the internal Qingflow view source, report/chart resources default to BI app reports, and dataset reports use `report_source="dataset"`
+  - do not pass backend raw `sourceType`; view resources infer the internal Qingflow view source, report/chart resources default to BI app reports, and existing dataset reports use `report_source="dataset"`
   - use `match_mappings` for associated view/report filters; dynamic conditions use `source_field`, static conditions use `value`
   - if field type compatibility is unclear, read [references/match-rules.md](references/match-rules.md)
 - Views and flows:
@@ -93,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
@@ -141,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/gotchas.md

@@ -25,6 +25,14 @@
 - `app_custom_buttons_apply` and `app_associated_resources_apply` publish after at least one write succeeds and do not accept `publish=false`
 - `app_publish_verify` is for explicit final verification, not the default next step after every write
 
+## BI Reports
+
+- Use `app_charts_apply` for QingBI report body/config creation or updates.
+- Use `app_associated_resources_apply` only when an existing BI report or view needs to appear in the Qingflow app associated-resource area or a specific view.
+- `app_charts_apply` currently creates/updates app-source BI reports only (`dataSourceType=qingflow`); dataset BI reports can only be attached when they already exist.
+- Creating a chart with `app_charts_apply` does not automatically show it in the Qingflow app UI; attach it separately if display is required.
+- `target` and `table` remain compatibility aliases for QingBI `indicator` and `detail`; use the real QingBI chart type when you need a specific type such as `summary`, `columnar`, `stacked_bar`, `scatter`, or `dualaxes`.
+
 ## Custom buttons
 
 - Use `app_custom_buttons_apply` for button creation/update/removal and view placement; do not split placement into `app_views_apply.buttons` unless you are maintaining a legacy patch.
@@ -45,6 +53,7 @@
 
 - Before creating an associated view/report, check `app_get.associated_resources` for the same `target_app_key + view_key/chart_key`.
 - If the resource already exists, use `patch_resources` with its `associated_item_id`; do not call `upsert_resources` again.
+- For per-view display, remove, and reorder, existing associated reports/views may be referenced by `associated_item_id`, `chart_id`/`chart_key`, or `view_key`; the tool resolves these to the internal id before writing.
 - `client_key` is only a same-call alias for `view_configs[].associated_item_refs`. It is not stored by Qingflow and cannot prevent duplicates in later calls.
 - Repeated `upsert_resources` without `associated_item_id` can create multiple app-level associated items pointing to the same view/report.
 

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

@@ -45,10 +45,10 @@ 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`: use `patch_resources` for existing associated-resource parameter replacement; use `upsert_resources` for creation or full target config; use `match_mappings` for associated view/report filters; manage per-view display config; publishes after successful writes; omit raw `sourceType`, and use `report_source="dataset"` only for BI dataset reports. 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`: use `patch_charts` for existing-chart parameter replacement; use `upsert_charts` for creation or full target config; remove/reorder QingBI charts; charts are immediate-live and do not publish; use `chart_id` when names are not unique
+- `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
 - `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
 
 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.
@@ -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:
@@ -75,6 +75,8 @@ For object-level updates, the safe partial syntax is `patch_*` with the object's
   `builder_tool_contract -> app_get_fields -> app_get_views -> app_views_apply.patch_views/upsert_views -> app_get_views`
 - Add QingBI charts:
   `builder_tool_contract -> app_get_fields -> app_get_charts -> app_charts_apply.patch_charts/upsert_charts -> app_get_charts`
+- Show an existing QingBI chart inside a Qingflow app/view:
+  `app_get -> app_associated_resources_apply.upsert_resources/patch_resources + view_configs -> app_get`
 - Create or update a portal:
   `builder_tool_contract -> portal_get -> portal_apply -> portal_get`
 

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` must be copied from `app_get.associated_resources[].associated_item_id`; it is not `chart_id` or `chart_key`. 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`.
@@ -116,7 +117,7 @@ View associated resources example:
 }
 ```
 
-Use `{"visible": true, "limit_type": "all"}` to show all app-level associated resources, and `{"visible": false}` to hide the area. The ids above must come from `app_get.associated_resources`. Before creating a resource, check whether the same `target_app_key + view_key/chart_key` already exists; if it does, use `patch_resources` with that `associated_item_id`. If you create a new associated item in the same call, give it a `client_key` and reference it from `view_configs[].associated_item_refs`; `client_key` is not persisted and cannot deduplicate a later call.
+Use `{"visible": true, "limit_type": "all"}` to show all app-level associated resources, and `{"visible": false}` to hide the area. The ids above can be internal `associated_item_id` values or existing resource `chart_id`/`chart_key`/`view_key` values from `app_get.associated_resources`. Before creating a resource, check whether the same `target_app_key + view_key/chart_key` already exists; if it does, use `patch_resources` with that `associated_item_id`. Dataset BI reports must already exist in QingBI and should be attached with `report_source="dataset"`; do not try to create them through `app_charts_apply`. If you create a new associated item in the same call, give it a `client_key` and reference it from `view_configs[].associated_item_refs`; `client_key` is not persisted and cannot deduplicate a later call.
 
 Create and show a BI indicator-card report in the same call:
 

package/src/qingflow_mcp/builder_facade/models.py

@@ -142,10 +142,34 @@ class PublicButtonPlacement(str, Enum):
 
 class PublicChartType(str, Enum):
     target = "target"
+    indicator = "indicator"
+    summary = "summary"
     pie = "pie"
     bar = "bar"
+    columnar = "columnar"
     line = "line"
     table = "table"
+    detail = "detail"
+    area = "area"
+    stacked_area = "stacked_area"
+    pct_stack_area = "pct_stack_area"
+    funnel = "funnel"
+    waterfall = "waterfall"
+    gauge = "gauge"
+    heatmap = "heatmap"
+    histogram = "histogram"
+    treemap = "treemap"
+    radar = "radar"
+    stacked_bar = "stacked_bar"
+    pct_stack_bar = "pct_stack_bar"
+    stacked_column = "stacked_column"
+    pct_stack_col = "pct_stack_col"
+    scatter = "scatter"
+    ring = "ring"
+    rose = "rose"
+    dualaxes = "dualaxes"
+    map = "map"
+    timeline = "timeline"
 
 
 class LayoutApplyMode(str, Enum):
@@ -1576,8 +1600,8 @@ class AssociatedResourcesApplyRequest(StrictModel):
     app_key: str
     upsert_resources: list[AssociatedResourceUpsertPatch] = Field(default_factory=list)
     patch_resources: list[AssociatedResourcePartialPatch] = Field(default_factory=list)
-    remove_associated_item_ids: list[int] = Field(default_factory=list)
-    reorder_associated_item_ids: list[int] = Field(default_factory=list)
+    remove_associated_item_ids: list[Any] = Field(default_factory=list)
+    reorder_associated_item_ids: list[Any] = Field(default_factory=list)
     view_configs: list[AssociatedResourceViewConfigPatch] = Field(default_factory=list)
 
     @model_validator(mode="before")
@@ -1775,10 +1799,18 @@ class ChartUpsertPatch(StrictModel):
             normalized = raw_type.strip().lower()
             aliases = {
                 "targetchart": PublicChartType.target.value,
+                "indicatorchart": PublicChartType.indicator.value,
+                "summarychart": PublicChartType.summary.value,
                 "piechart": PublicChartType.pie.value,
                 "barchart": PublicChartType.bar.value,
+                "columnchart": PublicChartType.columnar.value,
+                "columnarchart": PublicChartType.columnar.value,
                 "linechart": PublicChartType.line.value,
                 "tablechart": PublicChartType.table.value,
+                "detailchart": PublicChartType.detail.value,
+                "percent_stacked_column": PublicChartType.pct_stack_col.value,
+                "percent_stacked_bar": PublicChartType.pct_stack_bar.value,
+                "percent_stacked_area": PublicChartType.pct_stack_area.value,
             }
             if normalized in aliases:
                 payload["chart_type"] = aliases[normalized]
@@ -2002,6 +2034,8 @@ 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
     visibility: dict[str, Any] = Field(default_factory=dict)