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

package/src/qingflow_mcp/response_trim.py

@@ -58,7 +58,7 @@ def trim_public_response(tool_name: str | None, payload: dict[str, Any]) -> dict
         return payload
     if _looks_like_failure_payload(payload):
         status = str(payload.get("status") or "").lower()
-        if tool_name in {"user:record_insert", "user:record_update"} and status in {
+        if tool_name in {"user:record_insert", "user:record_update", "user:record_delete"} and status in {
             "blocked",
             "needs_confirmation",
             "partial_success",
@@ -73,8 +73,10 @@ def trim_success_response(tool_name: str | None, payload: dict[str, Any]) -> dic
         return payload
     trimmed = deepcopy(payload)
     drop_keys = COMMON_SUCCESS_DROP_TOP
-    if tool_name == "user:record_get":
+    if tool_name in {"user:record_get", "user:record_logs_get"}:
         drop_keys = COMMON_SUCCESS_DROP_TOP - {"output_profile"}
+    if tool_name in {"user:record_insert", "user:record_update", "user:record_delete"} and payload.get("ok") is False:
+        drop_keys = drop_keys - {"ok"}
     _drop_top_keys(trimmed, drop_keys)
     transformer = SUCCESS_POLICY_BY_TOOL.get(tool_name or "")
     if transformer is not None:
@@ -292,7 +294,7 @@ def _trim_workspace_get(payload: JSONObject) -> None:
         )
 
 
-def _trim_app_search_like(payload: JSONObject) -> None:
+def _trim_app_list_like(payload: JSONObject) -> None:
     payload.pop("apps", None)
     _trim_item_list(payload, "items", allowed=("app_key", "app_name", "package_name"))
 
@@ -392,6 +394,10 @@ def _trim_record_write(payload: JSONObject) -> None:
     data.pop("normalized_payload", None)
     data.pop("human_review", None)
     data.pop("action", None)
+    for key in ("update_route", "tried_routes"):
+        value = payload.get(key)
+        if value not in (None, [], {}, ""):
+            data[key] = value
     resource = _compact_record_resource(data.get("resource"))
     if resource:
         data["resource"] = resource
@@ -420,7 +426,7 @@ def _trim_record_write(payload: JSONObject) -> None:
 def _trim_record_write_batch(payload: JSONObject, data: JSONObject) -> None:
     data.pop("items", None)
     data.pop("debug", None)
-    for key in ("summary", "created_record_ids", "app_key", "mode"):
+    for key in ("summary", "app_key", "mode"):
         if data.get(key) in (None, [], {}, ""):
             data.pop(key, None)
     items = payload.get("items")
@@ -437,6 +443,8 @@ def _trim_record_write_batch(payload: JSONObject, data: JSONObject) -> None:
                     "write_executed",
                     "verification_status",
                     "safe_to_retry",
+                    "update_route",
+                    "tried_routes",
                     "failed_fields",
                     "confirmation_requests",
                     "blockers",
@@ -449,10 +457,8 @@ def _trim_record_write_batch(payload: JSONObject, data: JSONObject) -> None:
             for item in items
             if isinstance(item, dict)
         ]
-    for key in ("items", "created_record_ids"):
-        value = payload.get(key)
-        if value in (None, [], {}, ""):
-            payload.pop(key, None)
+    if payload.get("items") in (None, [], {}, ""):
+        payload.pop("items", None)
 
 
 def _trim_record_get(payload: JSONObject) -> None:
@@ -668,6 +674,49 @@ def _trim_record_access(payload: JSONObject) -> None:
     payload.update(compact)
 
 
+def _trim_record_logs(payload: JSONObject) -> None:
+    compact: dict[str, Any] = {}
+    for key in (
+        "ok",
+        "status",
+        "output_profile",
+        "app",
+        "view",
+        "record",
+        "local_dir",
+        "summary_path",
+        "warnings",
+        "unavailable_context",
+        "context_integrity",
+    ):
+        value = payload.get(key)
+        if value is not None:
+            compact[key] = value
+    for key in ("data_logs", "workflow_logs"):
+        node = payload.get(key)
+        if isinstance(node, dict):
+            compact[key] = _pick(
+                node,
+                (
+                    "status",
+                    "visible",
+                    "source",
+                    "reason",
+                    "complete",
+                    "items_count",
+                    "pages_fetched",
+                    "page_size",
+                    "reported_total",
+                    "local_path",
+                    "preview_items",
+                    "warnings",
+                    "stopped_reason",
+                ),
+            )
+    payload.clear()
+    payload.update(compact)
+
+
 def _trim_record_analyze(payload: JSONObject) -> None:
     summary: dict[str, Any] = {}
     completeness = payload.get("completeness")
@@ -714,13 +763,18 @@ def _trim_record_delete(payload: JSONObject) -> None:
     if not isinstance(data, dict):
         return
     resource = data.get("resource")
-    deleted_ids: list[str] = []
-    if isinstance(resource, dict):
+    deleted_ids = payload.get("deleted_ids") if isinstance(payload.get("deleted_ids"), list) else data.get("deleted_ids")
+    failed_ids = payload.get("failed_ids") if isinstance(payload.get("failed_ids"), list) else data.get("failed_ids")
+    if not isinstance(deleted_ids, list):
+        deleted_ids = []
+    if not isinstance(failed_ids, list):
+        failed_ids = []
+    if not deleted_ids and isinstance(resource, dict):
         raw_ids = resource.get("record_ids") or resource.get("apply_ids") or resource.get("applyIds")
         if isinstance(raw_ids, list):
             deleted_ids = [str(item) for item in raw_ids if item not in (None, "")]
-    data["deleted_ids"] = deleted_ids
-    data.setdefault("failed_ids", [])
+    data["deleted_ids"] = [str(item) for item in deleted_ids if item not in (None, "")]
+    data["failed_ids"] = [str(item) for item in failed_ids if item not in (None, "")]
     for key in (
         "resource",
         "action",
@@ -979,7 +1033,7 @@ _register_policy((USER_DOMAIN, BUILDER_DOMAIN), ("auth_use_credential", "auth_wh
 _register_policy((USER_DOMAIN, BUILDER_DOMAIN), ("auth_logout",), _trim_auth_logout)
 _register_policy((USER_DOMAIN, BUILDER_DOMAIN), ("workspace_list",), _trim_workspace_list)
 _register_policy((USER_DOMAIN, BUILDER_DOMAIN), ("workspace_get", "workspace_select"), _trim_workspace_get)
-_register_policy((USER_DOMAIN,), ("app_list", "app_search"), _trim_app_search_like)
+_register_policy((USER_DOMAIN,), ("app_list",), _trim_app_list_like)
 _register_policy((USER_DOMAIN, BUILDER_DOMAIN), ("app_get",), _trim_app_get)
 _register_policy((BUILDER_DOMAIN,), ("app_repair_code_blocks",), _trim_builder_list_like)
 _register_policy((USER_DOMAIN, BUILDER_DOMAIN), ("portal_list", "portal_get", "view_get", "chart_get"), _trim_builder_list_like)
@@ -1022,6 +1076,7 @@ _register_policy((USER_DOMAIN,), ("record_insert", "record_update"), _trim_recor
 _register_policy((USER_DOMAIN,), ("record_get",), _trim_record_get)
 _register_policy((USER_DOMAIN,), ("record_list",), _trim_record_list)
 _register_policy((USER_DOMAIN,), ("record_access",), _trim_record_access)
+_register_policy((USER_DOMAIN,), ("record_logs_get",), _trim_record_logs)
 _register_policy((USER_DOMAIN,), ("record_analyze",), _trim_record_analyze)
 _register_policy((USER_DOMAIN,), ("record_code_block_run",), _trim_code_block_run)
 _register_policy((USER_DOMAIN,), ("task_list",), _trim_task_list)
@@ -1062,6 +1117,8 @@ _register_policy(
     (BUILDER_DOMAIN,),
     (
         "builder_tool_contract",
+        "workspace_icon_catalog_get",
+        "package_list",
         "package_get",
         "package_apply",
         "solution_install",

package/src/qingflow_mcp/server.py

@@ -48,7 +48,7 @@ All resource tools operate with the logged-in user's Qingflow permissions.
 
 ## App Discovery
 
-If `app_key` is unknown, use `app_list` or `app_search` first.
+If `app_key` is unknown, use `app_list` first. Pass `query` to filter visible apps by keyword.
 If the app is known but the data range is not, use `app_get` first and choose from `accessible_views`.
 If an accessible view has `analysis_supported=false`, do not use it for `record_access` or `record_list`. `boardView` and `ganttView` are special UI views, not data-access targets.
 `view_get(view_id=...)` also returns `export_capability`; it only means there is a supported export route, not that export permission has been verified.
@@ -56,9 +56,9 @@ If an accessible view has `analysis_supported=false`, do not use it for `record_
 ## Schema-First Rule
 
 Call `record_insert_schema_get` before `record_insert`.
-Call `record_update_schema_get` before `record_update`.
+For simple field changes after the target record is clear, call `record_update` directly. Use `record_update_schema_get` for diagnostics, ambiguous fields, or complex writable-scope inspection.
 Call `record_code_block_schema_get` before `record_code_block_run`.
-Call `app_get` first when the data range is unclear, then use `record_browse_schema_get(view_id=...)` before `record_access`, `record_list`, or `record_get`.
+Call `app_get` first when the data range is unclear, then use `record_browse_schema_get(view_id=...)` before `record_access`, `record_list`, `record_get`, or `record_logs_get`.
 Call `record_import_schema_get` when the import field mapping is unclear before template download or verify.
 
 - All `field_id` values must come from the schema response.
@@ -67,7 +67,7 @@ Call `record_import_schema_get` when the import field mapping is unclear before
 ## Schema Scope
 
 `record_insert_schema_get` returns the current user's insert-ready applicant schema; read `required_fields`, `optional_fields`, `runtime_linked_required_fields`, and `payload_template`.
-`record_update_schema_get` returns the current record's overall update-ready writable field set across matched accessible views; read `writable_fields` and `payload_template`.
+`record_update_schema_get` returns the current record's overall update-ready writable field set and route diagnostics across matched accessible views; read `writable_fields`, `payload_template`, `available_update_routes`, and `recommended_update_route`.
 `record_browse_schema_get(view_id=...)` returns the same readable fields shown in the selected Qingflow table view header.
 `record_access.fields` / CSV columns and `record_list.columns / where / order_by / query_fields` use that exact same view schema.
 `record_code_block_schema_get` returns code-block-ready schema for exact code block field selection.
@@ -103,9 +103,9 @@ Analysis answers must include concrete numbers. When applicable, include percent
 
 ## Record CRUD Path
 
-`app_get -> record_browse_schema_get(view_id=...) -> record_list / record_get`
+`app_get -> record_browse_schema_get(view_id=...) -> record_list / record_get / record_logs_get`
 `record_insert_schema_get -> record_insert(items)`
-`record_update_schema_get -> record_update`
+`record_update` for simple updates; `record_update_schema_get -> record_update` when the writable field scope is unclear.
 `record_list / record_get -> record_delete`
 `record_code_block_schema_get -> record_code_block_run`
 
@@ -116,15 +116,16 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - Legacy forms such as bare integer `field_id`, `fieldId`, `operator`, `values`, or `order` may still parse, but they are compatibility-only and not the canonical DSL
 
 - `record_insert` defaults to an applicant-node `items` array; each item contains a field-title keyed `fields` map. A single insert is one item.
-- `record_update` uses a field-title keyed `fields` map and internally selects the first accessible view that can execute the current payload.
+- `record_update` uses a field-title keyed `fields` map. It first tries the data-manager direct update route, then falls back to the frontend custom-view detail edit route when the selected view can cover the payload; if a unique current-user todo task for the same record exposes editable fields, it can finally use the workflow save-only route. Read `update_route` and `tried_routes` after execution.
 - For insert, `runtime_linked_required_fields` means required-but-not-directly-writable fields that are usually supplied by runtime linkage or upstream context.
 - For insert, fields marked `may_become_required=true` stay in `optional_fields`; they are still directly writable, but linked visibility or option-driven rules can make them required at runtime.
 - Read field-level `linkage` whenever present on `record_insert_schema_get` or `record_update_schema_get`; it is the static hint for linked visibility, reference-driven auto fill, and formula/default auto-fill behavior.
 - `linkage.sources` lists upstream field titles that influence the current field; `linkage.affects_fields` lists downstream fields that may change when the current field changes.
 - `linkage.kind=logic_visibility` means linked visibility or option-driven rules are involved; `linkage.kind=reference_fill` means reference/default matching logic is involved; `linkage.kind=formula_fill` means formula/default auto-fill logic is involved.
-- `record_update_schema_get` exposes the overall writable field set for the record, but not every field combination is guaranteed; `record_update` still needs one single matched accessible view that can cover the payload.
+- `record_update_schema_get` exposes the overall writable field set and route candidates for the record, but not every field combination is guaranteed; `record_update` still needs data-manager permission, one single matched custom view that can cover the payload, or one unique editable current-user todo task.
 - `record_delete` deletes by `record_id` or `record_ids`.
 - `record_get` is the single-record frontend detail context tool. It returns detail-page visible fields, one-level relation targets, first-page data/workflow logs, associated views/reports, local readable image assets, local downloadable file assets, unavailable context, and `semantic_context`.
+- Use `record_logs_get` only when the user needs the full visible data/workflow log history for a specific record. It writes JSONL files locally and returns file paths plus completeness metadata; do not expect full log arrays in the response.
 - Read record images from `record_get.media_assets.items[].local_path` when `readable_by_agent=true`; read attachments/documents/tables from `record_get.file_assets.items[].local_path` and `extraction.text_path` when present. `record_get` follows the frontend storage cookie redirect path for Qingflow attachments, and remote file URLs should not be treated as directly readable.
 - `record_get.columns` are focus hints only; they do not project the detail fields. Read facts from top-level `fields[]`.
 - When readback shape matters after insert or update, prefer `record_get` for human/detail-page context, or `record_list(..., output_profile="normalized")` for batch-shaped normalized rows.
@@ -185,7 +186,7 @@ Use `record_code_block_run` when the user wants to execute a form code-block fie
 - `task_action_execute(task_id=..., action=...)` is also supported; MCP resolves the current todo locator internally before calling the real action route.
 - `task_workflow_log_get(task_id=...)` and `task_associated_report_detail_get(task_id=...)` are also supported for the current todo context.
 - Use `task_associated_report_detail_get` for associated view or report details.
-- Use `task_workflow_log_get` for full workflow log history.
+- Use `task_workflow_log_get` for the current task context workflow log page. For full record-level data/workflow logs, use `record_logs_get(app_key, record_id, view_id?)`.
 - Task actions operate on `app_key + record_id + workflow_node_id`, not `task_id`.
 
 ## Time Handling

package/src/qingflow_mcp/server_app_builder.py

@@ -35,15 +35,18 @@ def build_builder_server() -> FastMCP:
             "Follow the resource path resolve -> summary read -> apply -> publish_verify. "
             "Use builder_tool_contract when you need a machine-readable contract, aliases, allowed enums, or a minimal valid example for a public builder tool. "
             "Use solution_install when the user explicitly wants to install a packaged solution/template by solution_key, optionally copying bundled demo data. "
-            "If creating or updating an app package may be appropriate, use package_apply with explicit user intent; otherwise use package_get and app_resolve to locate resources, "
+            "Use package_list to find visible app packages by keyword and package_get to read package detail before editing; if creating or updating an app package may be appropriate, use package_apply with explicit user intent; otherwise use app_resolve to locate app resources, "
+            "Use workspace_icon_catalog_get before creating app packages, apps, or portals when supported icon/color candidates are needed; new workspace resources require explicit non-template icon + color, and the CLI validates choices without inferring business defaults. "
             "app_get as the default app map read, then app_get_fields/app_repair_code_blocks/app_get_layout/app_get_views/app_get_flow/app_get_charts/portal_list/portal_get/view_get/chart_get for focused configuration reads, "
             "member_search/role_search/role_create when workflow assignees must come from the directory or role catalog, preferring roles over explicit members unless the user explicitly names members, "
-            "then app_schema_apply/app_layout_apply/app_flow_apply/app_views_apply/app_custom_buttons_apply/app_associated_resources_apply/app_charts_apply/portal_apply to execute normalized patches; these apply tools perform planning, normalization, and dependency checks internally where applicable. Schema/layout/views noop requests skip publish, app_custom_buttons_apply and app_associated_resources_apply publish after at least one write succeeds and expose no draft-only parameter, charts are immediate-live without publish and resolve targets by chart_id first then exact unique chart name, portal updates use replace semantics only when sections are supplied and edit-mode base-info-only updates may omit sections, publish=false only guarantees draft/base-info updates for tools that still expose that parameter, and flow should use publish=false whenever you only want draft/precheck behavior. "
+            "then app_schema_apply/app_layout_apply/app_flow_apply/app_views_apply/app_custom_buttons_apply/app_associated_resources_apply/app_charts_apply/portal_apply to execute normalized patches; these apply tools perform planning, normalization, and dependency checks internally where applicable. Schema/layout/views noop requests skip publish, app_custom_buttons_apply and app_associated_resources_apply publish after at least one write succeeds and expose no draft-only parameter, charts are immediate-live without publish and resolve targets by chart_id first then exact unique chart name, portal updates use replace semantics only when sections are supplied and edit-mode base-info-only updates may omit sections, portal pc layout is a 24-column grid and mobile is a 6-column grid so omit position or use layout_preset when unsure, publish=false only guarantees draft/base-info updates for tools that still expose that parameter, and flow should use publish=false whenever you only want draft/precheck behavior. "
+            "Builder apply/write outputs include schema_version, operation, summary, and resources[]; use resources[].id/key/name/ids/parent as the stable UI and agent display entry, and keep legacy fields such as field_diff/views_diff/chart_results only for compatibility or troubleshooting. "
             "For existing object parameter replacement, prefer patch_views, patch_buttons, patch_resources, and patch_charts with set/unset; the tool reads current config and full-saves internally, while upsert_* is for creation or full target configuration and should not be used as an incomplete partial update. "
-            "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 builder delete/remove apply results, separate delete execution from readback verification: after DELETE is sent, resources expose delete_executed, readback_status, and safe_to_retry_delete=false. If readback_status is unavailable or still_exists, do not blindly repeat the delete; confirm later with app_get/view_get/chart_get or the relevant apply readback. Views/buttons use single-item readback; associated resources use one app-level resource-pool readback because there is no confirmed single-item GET. "
+            "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 multi-app creation, pass apps[]/--apps-file on app_schema_apply; each item may have client_key, and relation fields may use target_app_ref to point at another same-call client_key. "
+            "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. New views default associated report/view display to visible with limit_type=all; existing views preserve their current associated display unless associated_resources is explicitly patched. "
             "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 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; chart dimension/metric/filter/query fields must come from app_get_fields.chart_fields, not record schema or form-only fields; 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, 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. "
@@ -176,6 +179,14 @@ def build_builder_server() -> FastMCP:
     def builder_tool_contract(tool_name: str = "") -> dict:
         return ai_builder.builder_tool_contract(tool_name=tool_name)
 
+    @server.tool()
+    def workspace_icon_catalog_get(profile: str = DEFAULT_PROFILE) -> dict:
+        return ai_builder.workspace_icon_catalog_get(profile=profile)
+
+    @server.tool()
+    def package_list(profile: str = DEFAULT_PROFILE, trial_status: str = "all", query: str = "") -> dict:
+        return ai_builder.package_list(profile=profile, trial_status=trial_status, query=query)
+
     @server.tool()
     def package_get(profile: str = DEFAULT_PROFILE, package_id: int = 0) -> dict:
         return ai_builder.package_get(profile=profile, package_id=package_id)
@@ -407,7 +418,30 @@ def build_builder_server() -> FastMCP:
         add_fields: list[dict] | None = None,
         update_fields: list[dict] | None = None,
         remove_fields: list[dict] | None = None,
+        apps: list[dict] | None = None,
     ) -> dict:
+        if apps:
+            if app_key or app_name or app_title or add_fields or update_fields or remove_fields:
+                return _config_failure(
+                    "app_schema_apply multi-app mode accepts package_id/create_if_missing plus apps only.",
+                    fix_hint="Use `apps` for batch mode, or use the single-app arguments without `apps`.",
+                )
+            if package_id is None:
+                return _config_failure(
+                    "app_schema_apply multi-app mode requires package_id.",
+                    fix_hint="Pass `package_id` and `apps[].app_name` for new apps, or `apps[].app_key` for existing apps.",
+                )
+            return ai_builder.app_schema_apply(
+                profile=profile,
+                package_id=package_id,
+                visibility=visibility,
+                create_if_missing=create_if_missing,
+                publish=publish,
+                add_fields=[],
+                update_fields=[],
+                remove_fields=[],
+                apps=apps,
+            )
         has_app_key = bool((app_key or "").strip())
         has_app_name = bool((app_name or "").strip())
         has_app_title = bool((app_title or "").strip())
@@ -437,6 +471,7 @@ def build_builder_server() -> FastMCP:
             add_fields=add_fields or [],
             update_fields=update_fields or [],
             remove_fields=remove_fields or [],
+            apps=[],
         )
 
     @server.tool()
@@ -508,9 +543,12 @@ def build_builder_server() -> FastMCP:
         profile: str = DEFAULT_PROFILE,
         dash_key: str = "",
         dash_name: str = "",
+        name: str = "",
         package_id: int | None = None,
         publish: bool = True,
         sections: list[dict] | None = None,
+        pages: list[dict] | None = None,
+        layout_preset: str = "",
         visibility: dict | None = None,
         auth: dict | None = None,
         icon: str | None = None,
@@ -518,10 +556,14 @@ def build_builder_server() -> FastMCP:
         hide_copyright: bool | None = None,
         dash_global_config: dict | None = None,
         config: dict | None = None,
+        payload: dict | None = None,
     ) -> dict:
+        payload = payload if isinstance(payload, dict) else {}
         has_dash_key = bool((dash_key or "").strip())
-        has_dash_name = bool((dash_name or "").strip())
-        has_package_id = package_id is not None
+        effective_dash_name = (dash_name or name or str(payload.get("dash_name") or payload.get("dashName") or payload.get("name") or "")).strip()
+        has_dash_name = bool(effective_dash_name)
+        effective_package_id = package_id if package_id is not None else payload.get("package_id") or payload.get("packageId") or payload.get("package_tag_id")
+        has_package_id = effective_package_id is not None
         if has_dash_key and has_package_id:
             return _config_failure(
                 "portal_apply accepts exactly one selector mode.",
@@ -536,9 +578,12 @@ def build_builder_server() -> FastMCP:
             profile=profile,
             dash_key=dash_key,
             dash_name=dash_name,
+            name=name,
             package_id=package_id,
             publish=publish,
             sections=sections or [],
+            pages=pages or [],
+            layout_preset=layout_preset,
             visibility=visibility,
             auth=auth,
             icon=icon,
@@ -546,6 +591,7 @@ def build_builder_server() -> FastMCP:
             hide_copyright=hide_copyright,
             dash_global_config=dash_global_config,
             config=config or {},
+            payload=payload,
         )
 
     @server.tool()

package/src/qingflow_mcp/server_app_user.py

@@ -31,7 +31,7 @@ def build_user_server() -> FastMCP:
 
 ## App Discovery
 
-If `app_key` is unknown, use `app_list` or `app_search` first.
+If `app_key` is unknown, use `app_list` first. Pass `query` to filter visible apps by keyword.
 If the app is known but the data range is not, use `app_get` first and choose from `accessible_views`.
 If an accessible view has `analysis_supported=false`, do not use it for `record_access` or `record_list`. `boardView` and `ganttView` are special UI views, not data-access targets.
 `view_get(view_id=...)` also returns `export_capability`; it only means there is a supported export route, not that export permission has been verified.
@@ -47,9 +47,9 @@ If an accessible view has `analysis_supported=false`, do not use it for `record_
 ## Schema-First Rule
 
 Call `record_insert_schema_get` before `record_insert`.
-Call `record_update_schema_get` before `record_update`.
+For simple field changes after the target record is clear, call `record_update` directly. Use `record_update_schema_get` for diagnostics, ambiguous fields, or complex writable-scope inspection.
 Call `record_code_block_schema_get` before `record_code_block_run`.
-Call `app_get` first when the data range is unclear, then use `record_browse_schema_get(view_id=...)` before `record_access`, `record_list`, or `record_get`.
+Call `app_get` first when the data range is unclear, then use `record_browse_schema_get(view_id=...)` before `record_access`, `record_list`, `record_get`, or `record_logs_get`.
 Call `record_import_schema_get` when the import field mapping is unclear before template download or verify.
 
 - All `field_id` values must come from the schema response.
@@ -59,7 +59,7 @@ Call `record_import_schema_get` when the import field mapping is unclear before
 
 `record_insert_schema_get` returns the current user's insert-ready applicant schema; read `required_fields`, `optional_fields`, `runtime_linked_required_fields`, and `payload_template`.
 Inside `optional_fields`, any field with `may_become_required=true` is still writable, but may become required when linked visibility or option-driven runtime rules activate.
-`record_update_schema_get` returns the current record's overall update-ready writable field set across matched accessible views; read `writable_fields` and `payload_template`.
+`record_update_schema_get` returns the current record's overall update-ready writable field set and route diagnostics across matched accessible views; read `writable_fields`, `payload_template`, `available_update_routes`, and `recommended_update_route`.
 `record_browse_schema_get(view_id=...)` returns the same readable fields shown in the selected Qingflow table view header.
 `record_access.fields` / CSV columns and `record_list.columns / where / order_by / query_fields` use that exact same view schema; a missing field means it is not readable in that view.
 `searchQueIds` is a backend full-text search scope, not an output-column/projection mechanism.
@@ -102,9 +102,9 @@ Analysis answers must include concrete numbers. When applicable, include percent
 
 ## Record CRUD Path
 
-`app_get -> record_browse_schema_get(view_id=...) -> record_list / record_get`
+`app_get -> record_browse_schema_get(view_id=...) -> record_list / record_get / record_logs_get`
 `record_insert_schema_get -> record_insert(items)`
-`record_update_schema_get -> record_update`
+`record_update` for simple updates; `record_update_schema_get -> record_update` when the writable field scope is unclear.
 `record_list / record_get -> record_delete`
 `record_code_block_schema_get -> record_code_block_run`
 `portal_list -> portal_get -> chart_get / view_get`
@@ -117,15 +117,16 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - Legacy forms such as bare integer `field_id`, `fieldId`, `operator`, `values`, or `order` may still parse, but they are compatibility-only and not the canonical DSL
 
 - `record_insert` defaults to an applicant-node `items` array; each item contains a field-title keyed `fields` map. A single insert is one item.
-- `record_update` uses a field-title keyed `fields` map and internally selects the first accessible view that can execute the current payload.
+- `record_update` uses a field-title keyed `fields` map. It first tries the data-manager direct update route, then falls back to the frontend custom-view detail edit route when the selected view can cover the payload; if a unique current-user todo task for the same record exposes editable fields, it can finally use the workflow save-only route. Read `update_route` and `tried_routes` after execution.
 - For insert, `runtime_linked_required_fields` means required-but-not-directly-writable fields that are usually supplied by runtime linkage or upstream context.
 - For insert, fields marked `may_become_required=true` stay in `optional_fields`; they are still directly writable, but linked visibility or option-driven rules can make them required at runtime.
 - Read field-level `linkage` whenever present on `record_insert_schema_get` or `record_update_schema_get`; it is the static hint for linked visibility, reference-driven auto fill, and formula/default auto-fill behavior.
 - `linkage.sources` lists upstream field titles that influence the current field; `linkage.affects_fields` lists downstream fields that may change when the current field changes.
 - `linkage.kind=logic_visibility` means linked visibility or option-driven rules are involved; `linkage.kind=reference_fill` means reference/default matching logic is involved; `linkage.kind=formula_fill` means formula/default auto-fill logic is involved.
-- `record_update_schema_get` exposes the overall writable field set for the record, but not every field combination is guaranteed; `record_update` still needs one single matched accessible view that can cover the payload.
+- `record_update_schema_get` exposes the overall writable field set and update route candidates for the record, but not every field combination is guaranteed; `record_update` still needs data-manager permission, one single matched custom view that can cover the payload, or one unique editable current-user todo task.
 - `record_delete` deletes by `record_id` or `record_ids`.
 - `record_get` is the single-record frontend detail context tool. It returns detail-page visible fields, one-level relation targets, first-page data/workflow logs, associated views/reports, local readable image assets, local downloadable file assets, unavailable context, and `semantic_context`.
+- Use `record_logs_get` only when the user needs the full visible data/workflow log history for a specific record. It writes JSONL files locally and returns file paths plus completeness metadata; do not expect full log arrays in the response.
 - Read record images from `record_get.media_assets.items[].local_path` when `readable_by_agent=true`; read attachments/documents/tables from `record_get.file_assets.items[].local_path` and `extraction.text_path` when present. `record_get` follows the frontend storage cookie redirect path for Qingflow attachments, and remote file URLs should not be treated as directly readable.
 - `record_get.columns` are focus hints only; they do not project the detail fields. Read facts from top-level `fields[]`.
 - When readback shape matters after insert or update, prefer `record_get` for human/detail-page context, or `record_list(..., output_profile="normalized")` for batch-shaped normalized rows.
@@ -190,7 +191,7 @@ Use export only when the user explicitly asks to export/download/generate an Exc
 - `task_action_execute(task_id=..., action=...)` is also supported; MCP resolves the current todo locator internally before calling the real action route.
 - `task_workflow_log_get(task_id=...)` and `task_associated_report_detail_get(task_id=...)` are also supported for the current todo context.
 - Use `task_associated_report_detail_get` for associated view or report details.
-- Use `task_workflow_log_get` for full workflow log history.
+- Use `task_workflow_log_get` for the current task context workflow log page. For full record-level data/workflow logs, use `record_logs_get(app_key, record_id, view_id?)`.
 - Task actions operate on `app_key + record_id + workflow_node_id`, not `task_id`.
 - Treat `task_action_execute` as the tool-level action enum surface; the current task's real actions are only the ones listed in `task_get.capabilities.available_actions`.
 - Use `task_action_execute(action="save_only", fields=...)` when the user wants to save editable field changes on the current node without advancing the workflow.
@@ -360,12 +361,8 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
         )
 
     @server.tool()
-    def app_list(profile: str = DEFAULT_PROFILE) -> dict:
-        return apps.app_list(profile=profile)
-
-    @server.tool()
-    def app_search(profile: str = DEFAULT_PROFILE, keyword: str = "", page_num: int = 1, page_size: int = 50) -> dict:
-        return apps.app_search(profile=profile, keyword=keyword, page_num=page_num, page_size=page_size)
+    def app_list(profile: str = DEFAULT_PROFILE, query: str = "", keyword: str = "") -> dict:
+        return apps.app_list(profile=profile, query=query, keyword=keyword)
 
     @server.tool()
     def app_get(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict: