@qingflow-tech/qingflow-app-user-mcp 1.0.8 → 1.0.9

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-app-user-mcp",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "Operational end-user MCP for Qingflow records, tasks, comments, and directory 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.9"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

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]

package/src/qingflow_mcp/builder_facade/service.py

@@ -3672,6 +3672,7 @@ class AiBuilderFacade:
         client_key_to_id: dict[str, int] = {}
         used_client_keys: set[str] = set()
         force_update_resource_ids: set[int] = set()
+        resolved_associated_item_refs: dict[str, list[int]] = {}
 
         upsert_resources = list(request.upsert_resources)
         if request.patch_resources:
@@ -3778,34 +3779,35 @@ class AiBuilderFacade:
             else:
                 upsert_ops.append({"operation": "create", "associated_item_id": None, "patch": patch, "index": index})
 
-        remove_ids = [
-            item_id
-            for item_id in (_coerce_positive_int(raw_id) for raw_id in request.remove_associated_item_ids)
-            if item_id is not None
-        ]
+        remove_ids: list[int] = []
         for raw_id in request.remove_associated_item_ids:
-            item_id = _coerce_positive_int(raw_id)
+            item_id, issue = _resolve_associated_resource_selector(
+                raw_id,
+                existing_resources=existing_resources,
+                existing_by_id=existing_by_id,
+                reason_path="remove_associated_item_ids",
+            )
             if item_id is None:
-                blocking_issues.append({"error_code": "ASSOCIATED_RESOURCE_NOT_FOUND", "reason_path": "remove_associated_item_ids", "received": raw_id})
+                blocking_issues.append(issue or {"error_code": "ASSOCIATED_RESOURCE_NOT_FOUND", "reason_path": "remove_associated_item_ids", "received": raw_id})
                 continue
-            if item_id not in existing_by_id:
-                blocking_issues.append(_associated_resource_not_found_issue("remove_associated_item_ids", item_id, existing_by_id))
-            elif item_id in touched_ids:
+            remove_ids.append(item_id)
+            if item_id in touched_ids:
                 blocking_issues.append(_duplicate_associated_resource_issue("remove_associated_item_ids", item_id))
             else:
                 touched_ids.add(item_id)
 
-        reorder_ids = [
-            item_id
-            for item_id in (_coerce_positive_int(raw_id) for raw_id in request.reorder_associated_item_ids)
-            if item_id is not None
-        ]
+        reorder_ids: list[int] = []
         for raw_id in request.reorder_associated_item_ids:
-            item_id = _coerce_positive_int(raw_id)
+            item_id, issue = _resolve_associated_resource_selector(
+                raw_id,
+                existing_resources=existing_resources,
+                existing_by_id=existing_by_id,
+                reason_path="reorder_associated_item_ids",
+            )
             if item_id is None:
-                blocking_issues.append({"error_code": "ASSOCIATED_RESOURCE_NOT_FOUND", "reason_path": "reorder_associated_item_ids", "received": raw_id})
-            elif item_id not in existing_by_id:
-                blocking_issues.append(_associated_resource_not_found_issue("reorder_associated_item_ids", item_id, existing_by_id))
+                blocking_issues.append(issue or {"error_code": "ASSOCIATED_RESOURCE_NOT_FOUND", "reason_path": "reorder_associated_item_ids", "received": raw_id})
+                continue
+            reorder_ids.append(item_id)
 
         for index, view_config in enumerate(request.view_configs):
             refs = [str(ref or "").strip() for ref in view_config.associated_item_refs if str(ref or "").strip()]
@@ -3819,21 +3821,26 @@ class AiBuilderFacade:
                         "message": "associated_item_refs must reference client_key values from upsert_resources in the same apply call",
                     }
                 )
-            invalid_ids = [
-                item_id
-                for item_id in view_config.associated_item_ids
-                if _coerce_positive_int(item_id) is None or _coerce_positive_int(item_id) not in existing_by_id
-            ]
-            if invalid_ids:
-                blocking_issues.append(
-                    {
-                        "error_code": "ASSOCIATED_RESOURCE_NOT_FOUND",
-                        "reason_path": f"view_configs[{index}].associated_item_ids",
-                        "invalid_associated_item_ids": invalid_ids,
-                        "available_associated_item_ids": sorted(existing_by_id),
-                        "message": "view_configs.associated_item_ids must use app-level associated_item_id values from app_get",
-                    }
+            resolved_ids: list[int] = []
+            for raw_id in view_config.associated_item_ids:
+                item_id, issue = _resolve_associated_resource_selector(
+                    raw_id,
+                    existing_resources=existing_resources,
+                    existing_by_id=existing_by_id,
+                    reason_path=f"view_configs[{index}].associated_item_ids",
                 )
+                if item_id is None:
+                    blocking_issues.append(
+                        issue
+                        or {
+                            "error_code": "ASSOCIATED_RESOURCE_NOT_FOUND",
+                            "reason_path": f"view_configs[{index}].associated_item_ids",
+                            "received": raw_id,
+                        }
+                    )
+                    continue
+                resolved_ids.append(item_id)
+            resolved_associated_item_refs[f"view_configs[{index}].associated_item_ids"] = resolved_ids
             raw_limit_type = str(view_config.limit_type or ("all" if view_config.visible else "")).strip().lower()
             if view_config.visible and raw_limit_type and raw_limit_type not in {"all", "select"}:
                 blocking_issues.append(
@@ -3851,6 +3858,8 @@ class AiBuilderFacade:
                 for issue in resource_match_issues
             ]
         )
+        if resolved_associated_item_refs:
+            normalized_args["resolved_associated_item_refs"] = deepcopy(resolved_associated_item_refs)
 
         if blocking_issues:
             return finalize(
@@ -4008,12 +4017,13 @@ class AiBuilderFacade:
             resources_after = []
 
         for index, view_config in enumerate(request.view_configs):
+            resolved_view_config_ids = resolved_associated_item_refs.get(f"view_configs[{index}].associated_item_ids", [])
             selected_ids = [
                 item_id
                 for item_id in (
                     _coerce_positive_int(raw_id)
                     for raw_id in [
-                        *view_config.associated_item_ids,
+                        *resolved_view_config_ids,
                         *[client_key_to_id.get(str(ref or "").strip()) for ref in view_config.associated_item_refs],
                     ]
                 )
@@ -4115,6 +4125,7 @@ class AiBuilderFacade:
                     str(index): _summarize_compiled_match_rules(rules)
                     for index, rules in compiled_resource_match_rules.items()
                 },
+                "resolved_associated_item_refs": resolved_associated_item_refs,
             },
             "request_id": None,
             "suggested_next_call": None if verified else {"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
@@ -9657,6 +9668,13 @@ class AiBuilderFacade:
 
         for patch in upsert_charts:
             try:
+                dataset_source = _chart_patch_dataset_source_type(patch)
+                if dataset_source:
+                    raise ValueError(
+                        "app_charts_apply only creates or edits app-source QingBI reports with dataSourceType=qingflow; "
+                        f"dataset report source '{dataset_source}' is not supported for creation/update yet. "
+                        "Create the dataset report in QingBI first, then attach it with app_associated_resources_apply using report_source='dataset'."
+                    )
                 config_update_requested = _chart_patch_updates_chart_config(patch)
                 chart_visible_auth = (
                     self._compile_visibility_to_chart_visible_auth(profile=profile, visibility=patch.visibility)
@@ -9680,6 +9698,13 @@ class AiBuilderFacade:
                 existing_name = str((existing or {}).get("chartName") or "").strip()
                 existing_type = _normalize_backend_chart_type((existing or {}).get("chartType"))
                 target_type = _map_public_chart_type_to_backend(patch.chart_type)
+                existing_source_type = _chart_item_dataset_source_type(existing or {})
+                if existing_source_type:
+                    raise ValueError(
+                        "app_charts_apply only creates or edits app-source QingBI reports with dataSourceType=qingflow; "
+                        f"existing chart '{chart_id or patch.name}' uses dataset report source '{existing_source_type}' and is not supported for update yet. "
+                        "Update it in QingBI directly, then attach the existing report with app_associated_resources_apply using report_source='dataset'."
+                    )
                 if existing is None:
                     temp_chart_id = str(patch.chart_id or f"mcp_{uuid4().hex[:16]}")
                     create_payload = {
@@ -12337,13 +12362,16 @@ def _bi_field_id_for_field(*, app_key: str, field: dict[str, Any], qingbi_fields
 
 
 def _map_public_chart_type_to_backend(chart_type: PublicChartType) -> str:
-    return {
+    aliases = {
         PublicChartType.target: "indicator",
+        PublicChartType.indicator: "indicator",
         PublicChartType.pie: "pie",
         PublicChartType.bar: "bar",
         PublicChartType.line: "line",
         PublicChartType.table: "detail",
-    }[chart_type]
+        PublicChartType.detail: "detail",
+    }
+    return aliases.get(chart_type, chart_type.value)
 
 
 _CHART_PARTIAL_PATCH_KEY_ALIASES = {
@@ -12579,6 +12607,25 @@ def _build_public_metric_fields(
     return metrics or [_default_public_total_metric()]
 
 
+def _split_axis_metric_fields(metrics: list[dict[str, Any]]) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    if not metrics:
+        default_metric = _default_public_total_metric()
+        return [deepcopy(default_metric)], [deepcopy(default_metric)]
+    if len(metrics) == 1:
+        return [deepcopy(metrics[0])], [deepcopy(metrics[0])]
+    return [deepcopy(metrics[0])], [deepcopy(metrics[1])]
+
+
+def _two_gauge_metric_fields(metrics: list[dict[str, Any]], *, requested_metric_count: int) -> list[dict[str, Any]]:
+    if not metrics:
+        return []
+    if len(metrics) == 1:
+        if requested_metric_count <= 0:
+            return [deepcopy(metrics[0])]
+        return [deepcopy(metrics[0]), _default_public_total_metric()]
+    return [deepcopy(metrics[0]), deepcopy(metrics[1])]
+
+
 def _build_public_chart_filter_matrix(
     rules: list[Any],
     *,
@@ -12647,23 +12694,28 @@ def _build_public_chart_config_payload(
     for selector in list(config.pop("query_condition_field_ids", []) or []):
         field = _resolve_public_field(selector, field_lookup=field_lookup)
         query_condition_field_ids.append(_bi_field_id_for_field(app_key=app_key, field=field, qingbi_fields_by_id=qingbi_fields_by_id))
+    backend_chart_type = _map_public_chart_type_to_backend(patch.chart_type)
+    if backend_chart_type == "gauge" and not patch.indicator_field_ids and "selectedMetrics" not in config:
+        raise ValueError("gauge charts require at least one indicator_field_ids value; pass one metric and the CLI will pair it with 数据总量")
+    selected_dimensions = _build_public_dimension_fields(
+        patch.dimension_field_ids,
+        app_key=app_key,
+        field_lookup=field_lookup,
+        qingbi_fields_by_id=qingbi_fields_by_id,
+    )
+    selected_metrics = _build_public_metric_fields(
+        patch.indicator_field_ids,
+        app_key=app_key,
+        field_lookup=field_lookup,
+        qingbi_fields_by_id=qingbi_fields_by_id,
+        aggregate=aggregate,
+    )
     payload: dict[str, Any] = {
         "chartName": patch.name,
-        "chartType": _map_public_chart_type_to_backend(patch.chart_type),
+        "chartType": backend_chart_type,
         "dataSource": {"dataSourceId": app_key, "dataSourceType": "qingflow"},
-        "selectedDimensions": _build_public_dimension_fields(
-            patch.dimension_field_ids,
-            app_key=app_key,
-            field_lookup=field_lookup,
-            qingbi_fields_by_id=qingbi_fields_by_id,
-        ),
-        "selectedMetrics": _build_public_metric_fields(
-            patch.indicator_field_ids,
-            app_key=app_key,
-            field_lookup=field_lookup,
-            qingbi_fields_by_id=qingbi_fields_by_id,
-            aggregate=aggregate,
-        ),
+        "selectedDimensions": selected_dimensions,
+        "selectedMetrics": selected_metrics,
         "beforeAggregationFilterMatrix": before_filters,
         "afterAggregationFilterMatrix": after_filters,
         "chartStyleConfigs": deepcopy(config.pop("chartStyleConfigs", [])),
@@ -12679,6 +12731,23 @@ def _build_public_chart_config_payload(
         "queryConditionStatus": bool(config.pop("queryConditionStatus", bool(query_condition_field_ids))),
         "queryConditionExact": bool(config.pop("queryConditionExact", False)),
     }
+    if backend_chart_type == "summary":
+        payload.pop("selectedDimensions", None)
+        payload.setdefault("xDimensions", deepcopy(selected_dimensions))
+        payload.setdefault("yDimensions", [])
+    elif backend_chart_type == "scatter":
+        x_metrics, y_metrics = _split_axis_metric_fields(selected_metrics)
+        payload.pop("selectedMetrics", None)
+        payload.setdefault("xMetrics", x_metrics)
+        payload.setdefault("yMetrics", y_metrics)
+    elif backend_chart_type == "dualaxes":
+        left_metrics, right_metrics = _split_axis_metric_fields(selected_metrics)
+        payload.pop("selectedMetrics", None)
+        payload.setdefault("leftMetrics", left_metrics)
+        payload.setdefault("rightMetrics", right_metrics)
+    elif backend_chart_type == "gauge":
+        payload["selectedDimensions"] = []
+        payload["selectedMetrics"] = _two_gauge_metric_fields(selected_metrics, requested_metric_count=len(patch.indicator_field_ids or []))
     for key in (
         "selectedTime",
         "xDimensions",
@@ -12701,6 +12770,46 @@ def _chart_patch_updates_chart_config(patch: ChartUpsertPatch) -> bool:
     return bool({"dimension_field_ids", "indicator_field_ids", "filters", "config"} & explicit_fields)
 
 
+def _chart_patch_dataset_source_type(patch: ChartUpsertPatch) -> str:
+    config = patch.config if isinstance(patch.config, dict) else {}
+    candidates = [
+        config.get("dataSourceType"),
+        config.get("data_source_type"),
+    ]
+    data_source = config.get("dataSource")
+    if isinstance(data_source, dict):
+        candidates.extend([data_source.get("dataSourceType"), data_source.get("data_source_type"), data_source.get("type")])
+    data_source = config.get("data_source")
+    if isinstance(data_source, dict):
+        candidates.extend([data_source.get("dataSourceType"), data_source.get("data_source_type"), data_source.get("type")])
+    for candidate in candidates:
+        normalized = str(candidate or "").strip().lower()
+        if not normalized:
+            continue
+        if normalized not in {"qingflow", "app"}:
+            return normalized
+    return ""
+
+
+def _chart_item_dataset_source_type(item: dict[str, Any]) -> str:
+    candidates = [
+        item.get("dataSourceType"),
+        item.get("data_source_type"),
+        item.get("sourceType"),
+        item.get("source_type"),
+    ]
+    data_source = item.get("dataSource")
+    if isinstance(data_source, dict):
+        candidates.extend([data_source.get("dataSourceType"), data_source.get("data_source_type"), data_source.get("type")])
+    for candidate in candidates:
+        normalized = str(candidate or "").strip().lower()
+        if not normalized:
+            continue
+        if normalized not in {"qingflow", "app", "bi_qingflow"}:
+            return normalized
+    return ""
+
+
 def _build_public_portal_base_payload(
     *,
     dash_name: str,
@@ -12771,16 +12880,33 @@ def _normalize_backend_chart_type(value: Any) -> str:
         "12": "dualaxes",
         "13": "map",
         "14": "timeline",
+        "15": "area",
+        "16": "stacked_column",
+        "17": "stacked_bar",
+        "18": "rose",
+        "19": "stacked_area",
+        "20": "pct_stack_col",
+        "21": "pct_stack_bar",
+        "22": "pct_stack_area",
+        "23": "waterfall",
+        "24": "gauge",
+        "25": "heatmap",
+        "26": "histogram",
+        "27": "treemap",
+    }
+    aliases = {
+        "percent_stacked_column": "pct_stack_col",
+        "percent_stacked_bar": "pct_stack_bar",
+        "percent_stacked_area": "pct_stack_area",
     }
-    return by_code.get(raw, raw.lower())
+    normalized = by_code.get(raw, raw.lower())
+    return aliases.get(normalized, normalized)
 
 
 def _public_chart_type_from_backend(value: Any) -> str:
     normalized = _normalize_backend_chart_type(value)
     return {
         "indicator": PublicChartType.target.value,
-        "summary": PublicChartType.target.value,
-        "columnar": PublicChartType.bar.value,
         "detail": PublicChartType.table.value,
     }.get(normalized, normalized)
 
@@ -20129,7 +20255,7 @@ def _build_view_associated_resources_payload(
                     "missing_fields": [],
                     "received": raw_item_id,
                     "message": "associated_item_id must be an app-level associated resource id from app_get.associated_resources",
-                    "next_action": "call app_get and use associated_resources[].associated_item_id, not chart_id",
+                    "next_action": "prefer app_associated_resources_apply for associated report/view display; it can resolve associated_item_id, chart_id/chart_key, or view_key",
                 }
             ]
         item_ids.append(item_id)
@@ -20143,7 +20269,7 @@ def _build_view_associated_resources_payload(
                 "invalid_associated_item_ids": missing_ids,
                 "available_associated_item_ids": sorted(available_by_id),
                 "message": "associated_resource references ids that are not in the app-level associated resource pool",
-                "next_action": "call app_get and use associated_resources[].associated_item_id, not chart_id",
+                "next_action": "prefer app_associated_resources_apply for associated report/view display; it can resolve associated_item_id, chart_id/chart_key, or view_key",
             }
         ]
     payload = {
@@ -20561,6 +20687,77 @@ def _associated_resource_upsert_payload_from_existing_item(
     return _compact_dict(payload)
 
 
+def _resolve_associated_resource_selector(
+    selector: Any,
+    *,
+    existing_resources: list[dict[str, Any]],
+    existing_by_id: dict[int, dict[str, Any]],
+    reason_path: str,
+) -> tuple[int | None, dict[str, Any] | None]:
+    item_id = _coerce_positive_int(selector)
+    if item_id is not None:
+        if item_id in existing_by_id:
+            return item_id, None
+    raw = str(selector or "").strip()
+    if not raw:
+        return None, {
+            "error_code": "ASSOCIATED_RESOURCE_NOT_FOUND",
+            "reason_path": reason_path,
+            "received": selector,
+            "available_associated_item_ids": sorted(existing_by_id),
+            "message": "associated resource selector cannot be empty",
+        }
+    matches: list[dict[str, Any]] = []
+    for resource in existing_resources:
+        if not isinstance(resource, dict):
+            continue
+        candidates = [
+            resource.get("chart_id"),
+            resource.get("chart_key"),
+            resource.get("view_key"),
+            resource.get("associated_item_id"),
+        ]
+        if raw in {str(candidate).strip() for candidate in candidates if candidate not in {None, ""}}:
+            matches.append(resource)
+    if len(matches) == 1:
+        resolved_id = _coerce_positive_int(matches[0].get("associated_item_id"))
+        if resolved_id is not None:
+            return resolved_id, None
+    if len(matches) > 1:
+        return None, {
+            "error_code": "AMBIGUOUS_ASSOCIATED_RESOURCE",
+            "reason_path": reason_path,
+            "received": selector,
+            "candidate_associated_item_ids": [
+                item_id
+                for item_id in (_coerce_positive_int(item.get("associated_item_id")) for item in matches)
+                if item_id is not None
+            ],
+            "message": "selector matches multiple associated resources; pass associated_item_id",
+        }
+    return None, {
+        "error_code": "ASSOCIATED_RESOURCE_NOT_FOUND",
+        "reason_path": reason_path,
+        "received": selector,
+        "available_associated_item_ids": sorted(existing_by_id),
+        "available_chart_ids": sorted(
+            {
+                str(resource.get("chart_id") or resource.get("chart_key") or "").strip()
+                for resource in existing_resources
+                if str(resource.get("chart_id") or resource.get("chart_key") or "").strip()
+            }
+        ),
+        "available_view_keys": sorted(
+            {
+                str(resource.get("view_key") or "").strip()
+                for resource in existing_resources
+                if str(resource.get("view_key") or "").strip()
+            }
+        ),
+        "message": "selector must be an associated_item_id, QingBI chart_id/chart_key, or Qingflow view_key from the app-level associated resource pool",
+    }
+
+
 def _associated_resource_not_found_issue(reason_path: str, associated_item_id: int, existing_by_id: dict[int, dict[str, Any]]) -> dict[str, Any]:
     return {
         "error_code": "ASSOCIATED_RESOURCE_NOT_FOUND",
@@ -20568,7 +20765,7 @@ def _associated_resource_not_found_issue(reason_path: str, associated_item_id: i
         "associated_item_id": associated_item_id,
         "available_associated_item_ids": sorted(existing_by_id),
         "message": "associated_item_id is not in the app-level associated resource pool",
-        "next_action": "call app_get and use associated_resources[].associated_item_id; do not pass chart_id/chart_key",
+        "next_action": "call app_get and use associated_resources[].associated_item_id, chart_id/chart_key, or view_key",
     }
 
 

package/src/qingflow_mcp/server_app_builder.py

@@ -43,8 +43,9 @@ def build_builder_server() -> FastMCP:
             "For app_schema_apply, configure data title and data cover directly in field JSON with as_data_title=true and as_data_cover=true; data title is required and exactly one field may be marked, while data cover is optional and must be a top-level attachment field. "
             "For app_views_apply, keep fixed saved filters in filters and configure the frontend query panel separately with query_conditions; query_conditions.rows is a matrix of field names compiled to backend queryCondition queIds. "
             "For custom button body create/update/delete and view placement, use app_custom_buttons_apply. For addData buttons, prefer trigger_add_data_config.target_app_key + field_mappings/default_values; do not ask agents to write raw que_relation unless maintaining a legacy config. field_mappings.source_field accepts source schema fields and supported system fields: 数据ID/row_record_id/apply_id/_id means current record id (-17), 编号/record_number means visible record number (0). To fill a target relation with the current record, map {'source_field': '数据ID', 'target_field': '目标引用字段'}; default_values is only for static constants. View button bindings merge by default and merge-mode view_configs must include buttons; use view_configs[].mode=replace or explicit buttons=[] only when clearing/replacing existing bindings is intended. Builder view_key arguments are raw keys from app_get.views[].view_key and must not be prefixed with custom:. "
+            "For BI reports, keep report-body development separate from Qingflow in-app display: use app_charts_apply to create, update, remove, or reorder app-source QingBI chart bodies/configs with dataSourceType=qingflow; dataset BI reports are not created or edited by app_charts_apply yet and should be created in QingBI first, then attached with app_associated_resources_apply using report_source=dataset. "
             "For associated views/reports, use app_associated_resources_apply. Use match_mappings for filtering associated resources: dynamic current-record conditions use source_field, static conditions use value. match_mappings also supports 数据ID(-17) and 编号(0). Do not ask agents to write raw match_rules unless preserving a legacy backend config. "
-            "For associated reports/views, use app_associated_resources_apply for both the app-level associated_resources pool and per-view display config; associated_item_id is the app-level form_asos_chart.id, not chart_id/chart_key. Before creating an associated resource, read app_get.associated_resources and reuse an existing matching target_app_key + view_key/chart_key through patch_resources; client_key only works inside one apply call and is not persisted. Do not ask agents to pass backend raw sourceType: views infer the internal Qingflow view source, reports default to BI app reports, and dataset reports use report_source=dataset. "
+            "For associated reports/views, use app_associated_resources_apply for both the app-level associated_resources pool and per-view display config; associated_item_id is the app-level form_asos_chart.id, and view_configs/remove/reorder may also pass an existing resource's chart_id/chart_key/view_key because the tool resolves those to the internal id. Before creating an associated resource, read app_get.associated_resources and reuse an existing matching target_app_key + view_key/chart_key through patch_resources; client_key only works inside one apply call and is not persisted. Do not ask agents to pass backend raw sourceType: views infer the internal Qingflow view source, reports default to BI app reports, and dataset reports use report_source=dataset. "
             "For code_block fields with output bindings, always use qf_output assignment rather than const/let qf_output, and use app_repair_code_blocks when an existing form hangs because output-bound fields stay loading. "
             "Use package_apply to manage package metadata, visibility, grouping, and ordering, and app_publish_verify for explicit final publish verification. "
             "For workflow edits, keep the public builder surface on stable linear flows only: start/approve/fill/copy/webhook/end. Branch and condition nodes are intentionally disabled because the backend workflow route is not front-end stable for those node types. Declare node assignees and editable fields explicitly. "

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -2976,6 +2976,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "graphType": "graph_type",
             "targetAppKey": "target_app_key",
             "chartKey": "chart_key",
+            "chartId": "chart_key",
             "viewKey": "view_key",
             "viewgraphKey": "view_key",
             "reportSource": "report_source",
@@ -2990,12 +2991,14 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "view_configs[].limit_type": ["all", "select"],
         },
         "execution_notes": [
+            "this tool manages Qingflow in-app associated report/view display; it does not create or edit QingBI report bodies/configs",
+            "create or edit app-source BI report bodies first with app_charts_apply, then attach the resulting chart_id here with graph_type=chart; dataset BI reports can only be attached when they already exist",
             "this is the default associated report/view path; it manages both the app-level associated resource pool and per-view display config",
             "use patch_resources for partial parameter replacement on existing associated resources; the tool reads the current resource including backend-required raw fields, merges patch_resources[].set/unset, then submits the backend full-save payload internally",
-            "associated_item_id is form_asos_chart.id from app_get.associated_resources[].associated_item_id; it is not chart_id, chart_key, or view_key",
+            "associated_item_id is form_asos_chart.id from app_get.associated_resources[].associated_item_id; view_configs/remove/reorder may also pass an existing associated resource's chart_id/chart_key/view_key and the tool resolves it to the internal id",
             "before creating an associated resource, read app_get.associated_resources and reuse an existing item with patch_resources when target_app_key + view_key/chart_key already matches; repeated upsert_resources without associated_item_id can create duplicate associated items",
             "graph_type=view uses view_key and internally compiles to the Qingflow view source; graph_type=chart uses chart_key and defaults to report_source=app",
-            "report_source=app maps to BI_QINGFLOW; report_source=dataset maps to BI_DATASET; do not pass raw backend sourceType",
+            "report_source=app maps to BI_QINGFLOW; report_source=dataset maps to BI_DATASET for associating an existing dataset report; do not pass raw backend sourceType",
             "use match_mappings for associated view/report filtering; dynamic conditions use source_field and static conditions use value",
             "match_mappings.source_field accepts source schema fields plus system fields 数据ID(-17) and 编号(0); match_mappings compiles to backend matchRules",
             "do not write raw match_rules unless preserving a legacy backend config; match_mappings and match_rules are mutually exclusive",
@@ -3673,7 +3676,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "can_edit_form covers form/schema routes only and does not imply app base-info writes",
             "returns normalized app visibility when backend auth is readable",
             "custom_buttons[].button_id is the id required by app_custom_buttons_apply view_configs[].buttons[].button_ref",
-            "associated_resources[].associated_item_id is the id required by app_associated_resources_apply.view_configs.associated_item_ids; do not pass chart_id there",
+            "associated_resources[].associated_item_id is the internal id; app_associated_resources_apply.view_configs/remove/reorder may also pass an existing resource's chart_id/chart_key/view_key",
         ],
         "minimal_example": {
             "profile": "default",
@@ -3797,6 +3800,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             **deepcopy(_VISIBILITY_ALLOWED_VALUES),
         },
             "execution_notes": [
+                "this tool manages QingBI report bodies/configs; it does not attach reports to Qingflow app associated-resource display",
+                "app_charts_apply creates/updates app-source QingBI reports only; generated payloads use dataSourceType=qingflow",
+                "dataset BI reports are not created or edited by this tool yet; create them in QingBI first, then attach the existing report with app_associated_resources_apply report_source=dataset",
+                "after creating or updating an app-source report body, use app_associated_resources_apply when the report should appear inside a Qingflow app/view",
                 "app_charts_apply is immediate-live and does not publish",
                 "use patch_charts for partial parameter replacement on existing charts; the tool reads current chart base/config, merges patch_charts[].set/unset, then submits full QingBI base/config payloads internally",
                 "chart matching precedence is chart_id first, then exact unique chart name",