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

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @qingflow-tech/qingflow-app-user-mcp@1.0.7
+npm install @qingflow-tech/qingflow-app-user-mcp@1.0.9
 ```
 
 Run:
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-app-user-mcp@1.0.7 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.7",
+  "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.7"
+version = "1.0.9"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/skills/qingflow-app-user/references/public-surface-sync.md

@@ -39,11 +39,14 @@ It is not a user-facing product spec. It exists to prevent skill drift.
   - `app_layout_apply`
   - `app_flow_apply`
   - `app_views_apply`
+  - `app_custom_buttons_apply`
+  - `app_associated_resources_apply`
   - `app_charts_apply`
   - `portal_apply`
   - `app_publish_verify`
 - `portal_apply` edit mode may omit `sections` for base-info-only updates
 - `app_charts_apply.visibility` is a public capability and should be treated as a base-only visibility update
+- Existing object parameter replacement should use `patch_views`, `patch_buttons`, `patch_resources`, and `patch_charts`; `upsert_*` is for creation or full target config
 - `app_get.editability` uses:
   - `can_edit_app_base`
   - `can_edit_form`

package/src/qingflow_mcp/builder_facade/models.py

@@ -9,6 +9,22 @@ from .button_style_catalog import resolve_button_style
 from ..solution.spec_models import StrictModel
 
 
+def _normalize_builder_view_key_value(value: Any) -> Any:
+    if not isinstance(value, str):
+        return value
+    raw = value.strip()
+    if raw.startswith("custom:"):
+        return raw.split(":", 1)[1].strip()
+    return raw
+
+
+def _normalize_builder_view_key_payload(payload: dict[str, Any]) -> dict[str, Any]:
+    for key in ("view_key", "viewKey", "viewgraphKey", "viewGraphKey"):
+        if key in payload:
+            payload[key] = _normalize_builder_view_key_value(payload[key])
+    return payload
+
+
 class PublicFieldType(str, Enum):
     text = "text"
     long_text = "long_text"
@@ -115,7 +131,7 @@ class PublicViewButtonType(str, Enum):
 class PublicViewButtonConfigType(str, Enum):
     top = "TOP"
     detail = "DETAIL"
-    list = "LIST"
+    list = "INSIDE"
 
 
 class PublicButtonPlacement(str, Enum):
@@ -126,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):
@@ -1068,6 +1108,11 @@ class ViewUpsertPatch(StrictModel):
             "asosChartConfig",
         ),
     )
+    partial_update: bool = Field(default=False, exclude=True, validation_alias=AliasChoices("_partial_update", "partial_update", "partialUpdate"))
+    preserve_filters: bool = Field(default=False, exclude=True, validation_alias=AliasChoices("_preserve_filters", "preserve_filters", "preserveFilters"))
+    preserve_buttons: bool = Field(default=False, exclude=True, validation_alias=AliasChoices("_preserve_buttons", "preserve_buttons", "preserveButtons"))
+    preserve_query_conditions: bool = Field(default=False, exclude=True, validation_alias=AliasChoices("_preserve_query_conditions", "preserve_query_conditions", "preserveQueryConditions"))
+    preserve_associated_resources: bool = Field(default=False, exclude=True, validation_alias=AliasChoices("_preserve_associated_resources", "preserve_associated_resources", "preserveAssociatedResources"))
 
     @model_validator(mode="before")
     @classmethod
@@ -1075,6 +1120,7 @@ class ViewUpsertPatch(StrictModel):
         if not isinstance(value, dict):
             return value
         payload = dict(value)
+        payload = _normalize_builder_view_key_payload(payload)
         if "fields" in payload and "columns" not in payload:
             payload["columns"] = payload.pop("fields")
         if "column_names" in payload and "columns" not in payload:
@@ -1123,6 +1169,28 @@ class ViewUpsertPatch(StrictModel):
         return self
 
 
+class ViewPartialPatch(StrictModel):
+    view_key: str | None = Field(default=None, validation_alias=AliasChoices("view_key", "viewKey", "viewgraphKey", "viewGraphKey"))
+    name: str | None = Field(default=None, validation_alias=AliasChoices("name", "view_name", "viewName"))
+    set: dict[str, Any] = Field(default_factory=dict, validation_alias=AliasChoices("set", "update", "values"))
+    unset: list[str] = Field(default_factory=list, validation_alias=AliasChoices("unset", "clear", "remove"))
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_aliases(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        return _normalize_builder_view_key_payload(dict(value))
+
+    @model_validator(mode="after")
+    def validate_shape(self) -> "ViewPartialPatch":
+        if not str(self.view_key or "").strip() and not str(self.name or "").strip():
+            raise ValueError("patch_views[] requires view_key or unique name")
+        if not self.set and not self.unset:
+            raise ValueError("patch_views[] requires set or unset")
+        return self
+
+
 class CustomButtonJudgeValuePatch(StrictModel):
     id: int | str | None = None
     value: Any | None = None
@@ -1190,6 +1258,21 @@ class CustomButtonFieldMappingPatch(StrictModel):
     target_field: Any = Field(validation_alias=AliasChoices("target_field", "targetField", "target"))
 
 
+class FieldMatchMappingPatch(StrictModel):
+    target_field: Any = Field(validation_alias=AliasChoices("target_field", "targetField", "target", "field"))
+    source_field: Any | None = Field(default=None, validation_alias=AliasChoices("source_field", "sourceField", "source"))
+    value: Any | None = Field(default=None, validation_alias=AliasChoices("value", "static_value", "staticValue"))
+    operator: str = Field(default="eq", validation_alias=AliasChoices("operator", "op", "judge_type", "judgeType"))
+
+    @model_validator(mode="after")
+    def validate_shape(self) -> "FieldMatchMappingPatch":
+        has_source = self.source_field is not None and str(self.source_field).strip() != ""
+        has_value = self.value is not None
+        if has_source == has_value:
+            raise ValueError("match_mappings[] requires exactly one of source_field or value")
+        return self
+
+
 class CustomButtonAddDataConfigPatch(StrictModel):
     related_app_key: str | None = Field(
         default=None,
@@ -1319,6 +1402,22 @@ class CustomButtonUpsertPatch(CustomButtonPatch):
     client_key: str | None = Field(default=None, validation_alias=AliasChoices("client_key", "clientKey"))
 
 
+class CustomButtonPartialPatch(StrictModel):
+    button_id: int | None = Field(default=None, validation_alias=AliasChoices("button_id", "buttonId", "id"))
+    button_text: str | None = Field(default=None, validation_alias=AliasChoices("button_text", "buttonText", "name"))
+    client_key: str | None = Field(default=None, validation_alias=AliasChoices("client_key", "clientKey"))
+    set: dict[str, Any] = Field(default_factory=dict, validation_alias=AliasChoices("set", "update", "values"))
+    unset: list[str] = Field(default_factory=list, validation_alias=AliasChoices("unset", "clear", "remove"))
+
+    @model_validator(mode="after")
+    def validate_shape(self) -> "CustomButtonPartialPatch":
+        if self.button_id is None and not str(self.button_text or "").strip():
+            raise ValueError("patch_buttons[] requires button_id or unique button_text")
+        if not self.set and not self.unset:
+            raise ValueError("patch_buttons[] requires set or unset")
+        return self
+
+
 class CustomButtonRemovePatch(StrictModel):
     button_id: int | None = Field(default=None, validation_alias=AliasChoices("button_id", "buttonId", "id"))
     button_text: str | None = Field(default=None, validation_alias=AliasChoices("button_text", "buttonText", "name"))
@@ -1368,6 +1467,13 @@ class CustomButtonViewConfigPatch(StrictModel):
     mode: str = Field(default="merge", validation_alias=AliasChoices("mode", "apply_mode", "applyMode"))
     buttons: list[CustomButtonViewButtonBindingPatch] = Field(default_factory=list)
 
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_aliases(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        return _normalize_builder_view_key_payload(dict(value))
+
     @model_validator(mode="after")
     def validate_mode(self) -> "CustomButtonViewConfigPatch":
         normalized = str(self.mode or "").strip().lower()
@@ -1382,6 +1488,7 @@ class CustomButtonViewConfigPatch(StrictModel):
 class CustomButtonsApplyRequest(StrictModel):
     app_key: str
     upsert_buttons: list[CustomButtonUpsertPatch] = Field(default_factory=list)
+    patch_buttons: list[CustomButtonPartialPatch] = Field(default_factory=list)
     remove_buttons: list[CustomButtonRemovePatch] = Field(default_factory=list)
     view_configs: list[CustomButtonViewConfigPatch] = Field(default_factory=list)
 
@@ -1395,6 +1502,8 @@ class CustomButtonsApplyRequest(StrictModel):
             payload["upsert_buttons"] = payload.pop("buttons")
         if "upsertButtons" in payload and "upsert_buttons" not in payload:
             payload["upsert_buttons"] = payload.pop("upsertButtons")
+        if "patchButtons" in payload and "patch_buttons" not in payload:
+            payload["patch_buttons"] = payload.pop("patchButtons")
         if "removeButtons" in payload and "remove_buttons" not in payload:
             payload["remove_buttons"] = payload.pop("removeButtons")
         if "viewConfigs" in payload and "view_configs" not in payload:
@@ -1403,8 +1512,8 @@ class CustomButtonsApplyRequest(StrictModel):
 
     @model_validator(mode="after")
     def validate_shape(self) -> "CustomButtonsApplyRequest":
-        if not self.upsert_buttons and not self.remove_buttons and not self.view_configs:
-            raise ValueError("custom button apply requires at least one upsert, remove, or view config operation")
+        if not self.upsert_buttons and not self.patch_buttons and not self.remove_buttons and not self.view_configs:
+            raise ValueError("custom button apply requires at least one upsert, patch, remove, or view config operation")
         return self
 
 
@@ -1421,6 +1530,10 @@ class AssociatedResourceUpsertPatch(StrictModel):
     report_source: str | None = Field(default=None, validation_alias=AliasChoices("report_source", "reportSource"))
     source_type: str | None = Field(default=None, validation_alias=AliasChoices("source_type", "sourceType"))
     match_rules: list[CustomButtonMatchRulePatch] = Field(default_factory=list, validation_alias=AliasChoices("match_rules", "matchRules"))
+    match_mappings: list[FieldMatchMappingPatch] = Field(
+        default_factory=list,
+        validation_alias=AliasChoices("match_mappings", "matchMappings"),
+    )
 
     @model_validator(mode="before")
     @classmethod
@@ -1428,6 +1541,7 @@ class AssociatedResourceUpsertPatch(StrictModel):
         if not isinstance(value, dict):
             return value
         payload = dict(value)
+        payload = _normalize_builder_view_key_payload(payload)
         if "chart_id" in payload and "chart_key" not in payload and "chartKey" not in payload:
             payload["chart_key"] = str(payload.pop("chart_id"))
         raw_graph_type = str(payload.get("graph_type", payload.get("graphType", "")) or "").strip().lower()
@@ -1449,6 +1563,21 @@ class AssociatedResourceUpsertPatch(StrictModel):
         return payload
 
 
+class AssociatedResourcePartialPatch(StrictModel):
+    associated_item_id: int = Field(validation_alias=AliasChoices("associated_item_id", "associatedItemId", "asosChartId", "id"))
+    client_key: str | None = Field(default=None, validation_alias=AliasChoices("client_key", "clientKey"))
+    set: dict[str, Any] = Field(default_factory=dict, validation_alias=AliasChoices("set", "update", "values"))
+    unset: list[str] = Field(default_factory=list, validation_alias=AliasChoices("unset", "clear", "remove"))
+
+    @model_validator(mode="after")
+    def validate_shape(self) -> "AssociatedResourcePartialPatch":
+        if self.associated_item_id <= 0:
+            raise ValueError("patch_resources[].associated_item_id must be a positive integer")
+        if not self.set and not self.unset:
+            raise ValueError("patch_resources[] requires set or unset")
+        return self
+
+
 class AssociatedResourceViewConfigPatch(StrictModel):
     view_key: str = Field(validation_alias=AliasChoices("view_key", "viewKey", "viewgraphKey", "viewGraphKey"))
     visible: bool = Field(default=True, validation_alias=AliasChoices("visible", "enabled", "asosChartVisible"))
@@ -1459,12 +1588,20 @@ class AssociatedResourceViewConfigPatch(StrictModel):
     )
     associated_item_refs: list[str] = Field(default_factory=list, validation_alias=AliasChoices("associated_item_refs", "associatedItemRefs", "refs"))
 
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_aliases(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        return _normalize_builder_view_key_payload(dict(value))
+
 
 class AssociatedResourcesApplyRequest(StrictModel):
     app_key: str
     upsert_resources: list[AssociatedResourceUpsertPatch] = Field(default_factory=list)
-    remove_associated_item_ids: list[int] = Field(default_factory=list)
-    reorder_associated_item_ids: list[int] = Field(default_factory=list)
+    patch_resources: list[AssociatedResourcePartialPatch] = 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")
@@ -1475,6 +1612,8 @@ class AssociatedResourcesApplyRequest(StrictModel):
         payload = dict(value)
         if "upsertResources" in payload and "upsert_resources" not in payload:
             payload["upsert_resources"] = payload.pop("upsertResources")
+        if "patchResources" in payload and "patch_resources" not in payload:
+            payload["patch_resources"] = payload.pop("patchResources")
         if "resources" in payload and "upsert_resources" not in payload:
             payload["upsert_resources"] = payload.pop("resources")
         if "removeAssociatedItemIds" in payload and "remove_associated_item_ids" not in payload:
@@ -1487,8 +1626,8 @@ class AssociatedResourcesApplyRequest(StrictModel):
 
     @model_validator(mode="after")
     def validate_shape(self) -> "AssociatedResourcesApplyRequest":
-        if not self.upsert_resources and not self.remove_associated_item_ids and not self.reorder_associated_item_ids and not self.view_configs:
-            raise ValueError("associated resources apply requires at least one resource or view config operation")
+        if not self.upsert_resources and not self.patch_resources and not self.remove_associated_item_ids and not self.reorder_associated_item_ids and not self.view_configs:
+            raise ValueError("associated resources apply requires at least one upsert, patch, remove, reorder, or view config operation")
         return self
 
 
@@ -1533,8 +1672,8 @@ class ViewButtonBindingPatch(StrictModel):
                 payload["config_type"] = "TOP"
             elif normalized_config == "detail":
                 payload["config_type"] = "DETAIL"
-            elif normalized_config in {"list", "row", "row_action"}:
-                payload["config_type"] = "LIST"
+            elif normalized_config in {"inside", "list", "row", "row_action"}:
+                payload["config_type"] = "INSIDE"
         raw_limits = payload.get("button_limit", payload.get("buttonLimit"))
         if isinstance(raw_limits, list) and raw_limits and all(isinstance(item, dict) for item in raw_limits):
             payload["button_limit"] = [raw_limits]
@@ -1660,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]
@@ -1676,9 +1823,39 @@ class ChartUpsertPatch(StrictModel):
         return payload
 
 
+class ChartPartialPatch(StrictModel):
+    chart_id: str | None = None
+    name: str | None = None
+    set: dict[str, Any] = Field(default_factory=dict, validation_alias=AliasChoices("set", "update", "values"))
+    unset: list[str] = Field(default_factory=list, validation_alias=AliasChoices("unset", "clear", "remove"))
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_aliases(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        payload = dict(value)
+        if "id" in payload and "chart_id" not in payload:
+            payload["chart_id"] = str(payload.pop("id"))
+        if "chart_name" in payload and "name" not in payload:
+            payload["name"] = payload.pop("chart_name")
+        if "chartName" in payload and "name" not in payload:
+            payload["name"] = payload.pop("chartName")
+        return payload
+
+    @model_validator(mode="after")
+    def validate_shape(self) -> "ChartPartialPatch":
+        if not str(self.chart_id or "").strip() and not str(self.name or "").strip():
+            raise ValueError("patch_charts[] requires chart_id or unique name")
+        if not self.set and not self.unset:
+            raise ValueError("patch_charts[] requires set or unset")
+        return self
+
+
 class ChartApplyRequest(StrictModel):
     app_key: str
     upsert_charts: list[ChartUpsertPatch] = Field(default_factory=list)
+    patch_charts: list[ChartPartialPatch] = Field(default_factory=list)
     remove_chart_ids: list[str] = Field(default_factory=list)
     reorder_chart_ids: list[str] = Field(default_factory=list)
 
@@ -1688,6 +1865,14 @@ class ChartApplyRequest(StrictModel):
         if not isinstance(value, dict):
             return value
         payload = dict(value)
+        if "upsertCharts" in payload and "upsert_charts" not in payload:
+            payload["upsert_charts"] = payload.pop("upsertCharts")
+        if "patchCharts" in payload and "patch_charts" not in payload:
+            payload["patch_charts"] = payload.pop("patchCharts")
+        if "removeChartIds" in payload and "remove_chart_ids" not in payload:
+            payload["remove_chart_ids"] = payload.pop("removeChartIds")
+        if "reorderChartIds" in payload and "reorder_chart_ids" not in payload:
+            payload["reorder_chart_ids"] = payload.pop("reorderChartIds")
         for key in ("remove_chart_ids", "reorder_chart_ids"):
             raw = payload.get(key)
             if isinstance(raw, list):
@@ -1696,8 +1881,8 @@ class ChartApplyRequest(StrictModel):
 
     @model_validator(mode="after")
     def validate_shape(self) -> "ChartApplyRequest":
-        if not self.upsert_charts and not self.remove_chart_ids and not self.reorder_chart_ids:
-            raise ValueError("chart apply requires at least one upsert, remove, or reorder operation")
+        if not self.upsert_charts and not self.patch_charts and not self.remove_chart_ids and not self.reorder_chart_ids:
+            raise ValueError("chart apply requires at least one upsert, patch, remove, or reorder operation")
         return self
 
 
@@ -1757,6 +1942,13 @@ class PortalViewRefPatch(StrictModel):
     view_key: str | None = None
     view_name: str | None = None
 
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_aliases(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        return _normalize_builder_view_key_payload(dict(value))
+
     @model_validator(mode="after")
     def validate_target(self) -> "PortalViewRefPatch":
         if not (self.view_key or self.view_name):
@@ -1944,6 +2136,7 @@ class ViewGetResponse(StrictModel):
     config: dict[str, Any] = Field(default_factory=dict)
     questions: list[dict[str, Any]] = Field(default_factory=list)
     associations: list[dict[str, Any]] = Field(default_factory=list)
+    buttons_config: dict[str, Any] = Field(default_factory=dict)
     associated_resources_config: dict[str, Any] = Field(default_factory=dict)
 
 
@@ -2021,6 +2214,7 @@ class FlowPlanRequest(StrictModel):
 class ViewsPlanRequest(StrictModel):
     app_key: str
     upsert_views: list[ViewUpsertPatch] = Field(default_factory=list)
+    patch_views: list[ViewPartialPatch] = Field(default_factory=list)
     remove_views: list[str] = Field(default_factory=list)
     preset: ViewsPreset | None = None