@qingflow-tech/qingflow-app-user-mcp 1.0.10 → 1.0.12

package/src/qingflow_mcp/response_trim.py

@@ -47,7 +47,6 @@ COMMON_ERROR_DROP_TOP = {
     "allowed_values",
     "missing_fields",
     "noop",
-    "ok",
 }
 
 SUCCESS_POLICY_BY_TOOL: dict[str, TransformFn] = {}
@@ -58,11 +57,18 @@ 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", "user:record_delete"} and status in {
-            "blocked",
-            "needs_confirmation",
-            "partial_success",
-        }:
+        if _is_executed_nonfatal_payload(payload) or (
+            tool_name in {"user:record_insert", "user:record_update", "user:record_delete"}
+            and status in {
+                "blocked",
+                "needs_confirmation",
+                "partial_success",
+            }
+        ) or (
+            tool_name == "user:record_import_verify"
+            and status == "failed"
+            and "can_import" in payload
+        ):
             return trim_success_response(tool_name, payload)
         return _trim_returned_failure(payload)
     return trim_success_response(tool_name, payload)
@@ -73,7 +79,7 @@ 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"}
@@ -151,12 +157,25 @@ def _parse_runtime_error_payload(exc: RuntimeError) -> dict[str, Any] | None:
 
 
 def _looks_like_failure_payload(payload: dict[str, Any]) -> bool:
+    if _is_executed_nonfatal_payload(payload):
+        return False
     if payload.get("ok") is False:
         return True
     status = str(payload.get("status") or "").lower()
     return status in {"failed", "blocked"}
 
 
+def _is_executed_nonfatal_payload(payload: dict[str, Any]) -> bool:
+    status = str(payload.get("status") or "").lower()
+    executed = bool(
+        payload.get("write_executed")
+        or payload.get("delete_executed")
+        or payload.get("action_executed")
+        or payload.get("export_executed")
+    )
+    return executed and status in {"partial_success", "verification_failed", "running", "queued", "unknown"}
+
+
 def _trim_returned_failure(payload: dict[str, Any]) -> dict[str, Any]:
     trimmed = deepcopy(payload)
     _drop_top_keys(trimmed, COMMON_ERROR_DROP_TOP)
@@ -294,7 +313,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"))
 
@@ -325,15 +344,22 @@ def _trim_import_schema(payload: JSONObject) -> None:
         columns = [item for item in payload.get("expected_columns", []) if isinstance(item, dict)]
     if columns is not None:
         payload["columns"] = [_compact_import_column(item) for item in columns]
+    import_capability = payload.get("import_capability") if isinstance(payload.get("import_capability"), dict) else {}
+    if import_capability:
+        verification = payload.get("verification") if isinstance(payload.get("verification"), dict) else {}
+        if not isinstance(payload.get("verification"), dict):
+            payload["verification"] = verification
+        verification.setdefault("import_auth_source", import_capability.get("auth_source"))
+        verification.setdefault("import_capability_can_import", import_capability.get("can_import"))
     payload.pop("expected_columns", None)
     payload.pop("schema_fingerprint", None)
     payload.pop("import_capability", None)
     payload.pop("request_route", None)
-    payload.pop("verification", None)
 
     if _looks_like_import_verify(payload):
         _trim_import_verify_payload(payload)
         return
+    payload.pop("verification", None)
     if "applied_repairs" in payload or "repaired_file_path" in payload:
         _trim_import_repair_payload(payload)
         return
@@ -394,6 +420,14 @@ def _trim_record_write(payload: JSONObject) -> None:
     data.pop("normalized_payload", None)
     data.pop("human_review", None)
     data.pop("action", None)
+    if payload.get("status") == "success":
+        data.pop("tried_routes", None)
+    update_route = payload.get("update_route")
+    if update_route not in (None, [], {}, ""):
+        data["update_route"] = update_route
+    tried_routes = payload.get("tried_routes")
+    if payload.get("status") != "success" and tried_routes not in (None, [], {}, ""):
+        data["tried_routes"] = tried_routes
     resource = _compact_record_resource(data.get("resource"))
     if resource:
         data["resource"] = resource
@@ -437,8 +471,11 @@ def _trim_record_write_batch(payload: JSONObject, data: JSONObject) -> None:
                     "record_id",
                     "apply_id",
                     "write_executed",
+                    "write_succeeded",
                     "verification_status",
                     "safe_to_retry",
+                    "update_route",
+                    "tried_routes",
                     "failed_fields",
                     "confirmation_requests",
                     "blockers",
@@ -668,6 +705,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")
@@ -853,13 +933,37 @@ def _compact_import_column(item: dict[str, Any]) -> dict[str, Any]:
 
 
 def _looks_like_import_verify(payload: JSONObject) -> bool:
-    return "verification_id" in payload and "can_import" in payload
+    if "verification_id" in payload and "can_import" in payload:
+        return True
+    return "can_import" in payload and (
+        "error_code" in payload
+        or "issues" in payload
+        or "file_path" in payload
+    )
 
 
 def _trim_import_verify_payload(payload: JSONObject) -> None:
     issues = payload.get("issues") if isinstance(payload.get("issues"), list) else []
     issue_summary = _summarize_import_issues(issues)
     payload["issue_summary"] = issue_summary
+    verification = payload.get("verification") if isinstance(payload.get("verification"), dict) else {}
+    compact_verification = {
+        key: verification.get(key)
+        for key in (
+            "import_auth_prechecked",
+            "import_auth_precheck_passed",
+            "import_auth_source",
+            "import_capability_can_import",
+            "local_precheck_passed",
+            "backend_verification_passed",
+            "auto_normalized",
+        )
+        if key in verification
+    }
+    if compact_verification:
+        payload["verification"] = compact_verification
+    else:
+        payload.pop("verification", None)
     columns = payload.get("columns")
     if "expected_columns" not in payload and isinstance(columns, list):
         payload["expected_columns"] = columns
@@ -955,7 +1059,7 @@ def _trim_feedback(payload: JSONObject) -> None:
 
 
 def _trim_builder_envelope(payload: JSONObject) -> None:
-    if str(payload.get("status") or "").lower() == "success":
+    if str(payload.get("status") or "").lower() in {"success", "partial_success", "verification_failed"}:
         details = payload.get("details")
         if isinstance(details, dict):
             _drop_deep_keys(details, {"request_route", "base_url", "normalized_args", "suggested_next_call", "transport", "response", "body", "raw"})
@@ -984,7 +1088,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)
@@ -1027,6 +1131,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)
@@ -1067,6 +1172,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,17 +48,18 @@ 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`.
+Treat an explicit `view_id` as the exact frontend view context. If `system:all` fails, do not silently switch to `system:initiated`, `system:todo`, or another system view unless the user, frontend URL, or `app_get.accessible_views` explicitly selects that view.
 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.
 
 ## Schema-First Rule
 
 Call `record_insert_schema_get` before `record_insert`.
-Call `record_update_schema_get` before `record_update`.
-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`.
+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.
+Prefer `record_code_block_schema_get` before `record_code_block_run` when field selection or binding diagnostics are unclear; if the exact code-block field id is already known from record/task detail, run directly.
+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 +68,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 update-ready writable field set and route diagnostics. When `view_id` is explicit, it is the exact frontend view context and must not be silently replaced by another view.
 `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,11 +104,11 @@ 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_list / record_get -> record_delete`
-`record_code_block_schema_get -> record_code_block_run`
+`record_update` for simple updates; `record_update_schema_get -> record_update` when the writable field scope is unclear.
+`record_list / record_get -> record_delete(system view_id)`
+`record_code_block_run` directly when the exact code-block field is known; otherwise `record_code_block_schema_get -> record_code_block_run`
 
 - Use `columns` as `[{{field_id}}]`
 - Use `record_list(query=..., query_fields=[{{field_id}}])` for fuzzy single-record lookup, then follow `lookup.next_action`; `query_fields` is search scope and `columns` is display shape.
@@ -116,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. On success, read `status`, `update_route`, and `verification_status`; on failure, read the failure reason and route diagnostics.
 - 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_delete` deletes by `record_id` or `record_ids`.
+- `record_update_schema_get` exposes the writable field set and route candidates for the record; with an explicit `view_id`, diagnostics stay scoped to that selected frontend view. 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`, and requires an accessible system `view_id`; use custom views only to locate records, not as the delete route.
 - `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.
@@ -139,7 +141,8 @@ Analysis answers must include concrete numbers. When applicable, include percent
 
 Use `record_code_block_run` when the user wants to execute a form code-block field against an existing record.
 
-- Always resolve the exact code-block field from `record_code_block_schema_get` first.
+- Prefer resolving the exact code-block field from `record_code_block_schema_get`, but do not treat applicant-schema 40002 as final denial when record/task detail already exposes the code-block field id.
+- `record_code_block_run` uses the record/task detail answers for the execution context; when applicant schema is unavailable it can still execute with a numeric code-block field id, but schema-bound relation writeback may be skipped.
 - Treat code-block execution as write-capable, not read-only.
 - If the code block is bound to relation outputs, Qingflow may calculate target answers and write them back automatically.
 - For safe debugging, pass `apply_writeback=false` and inspect the parsed alias results plus `relation.calculated_answers_preview` before allowing any writeback.
@@ -185,7 +188,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, first choose an accessible view with `app_get`, then call `record_logs_get(app_key, record_id, view_id)` with that same explicit `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,16 +35,19 @@ 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 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 builder write/apply results, separate write execution from final readback verification: status=partial_success with write_executed=true and safe_to_retry=false means the write was sent or succeeded, while final readback, publish verification, or metadata confirmation is pending or permission-restricted. Report it as written but unverified; do not repeat the same write blindly. "
             "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 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. View writes use ViewManagementAuth (beingViewManageStatus), falling back to DataManageAuth when advanced app permissions are not enabled. "
+            "For custom button body create/update/delete and view placement, use app_custom_buttons_apply. Button body writes require EditAppAuth; view_configs placement writes require ViewManagementAuth, matching the backend viewConfig route. 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; 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. "
@@ -177,6 +180,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)
@@ -533,9 +544,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,
@@ -543,10 +557,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.",
@@ -561,9 +579,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,
@@ -571,6 +592,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,8 +31,9 @@ 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`.
+Treat an explicit `view_id` as the exact frontend view context. If `system:all` fails, do not silently switch to `system:initiated`, `system:todo`, or another system view unless the user, frontend URL, or `app_get.accessible_views` explicitly selects that view.
 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 +48,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`.
-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`.
+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.
+Prefer `record_code_block_schema_get` before `record_code_block_run` when field selection or binding diagnostics are unclear; if the exact code-block field id is already known from record/task detail, run directly.
+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,11 +60,11 @@ 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 update-ready writable field set and route diagnostics. When `view_id` is explicit, it is the exact frontend view context and must not be silently replaced by another view.
 `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.
-`record_code_block_schema_get` returns code-block-ready schema for exact code block field selection.
+`record_code_block_schema_get` returns code-block-ready schema for exact code block field selection when the applicant schema is readable.
 `record_import_schema_get` returns import-ready column metadata.
 
 - Hidden fields are omitted.
@@ -102,11 +103,11 @@ 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_list / record_get -> record_delete`
-`record_code_block_schema_get -> record_code_block_run`
+`record_update` for simple updates; `record_update_schema_get -> record_update` when the writable field scope is unclear.
+`record_list / record_get -> record_delete(system view_id)`
+`record_code_block_run` directly when the exact code-block field is known; otherwise `record_code_block_schema_get -> record_code_block_run`
 `portal_list -> portal_get -> chart_get / view_get`
 `portal_get -> view_get -> record_list`
 
@@ -117,15 +118,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. On success, read `status`, `update_route`, and `verification_status`; on failure, read the failure reason and route diagnostics.
 - 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_delete` deletes by `record_id` or `record_ids`.
+- `record_update_schema_get` exposes the writable field set and update route candidates for the record; with an explicit `view_id`, diagnostics stay scoped to that selected frontend view. 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`, and requires an accessible system `view_id`; use custom views only to locate records, not as the delete route.
 - `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.
@@ -141,7 +143,8 @@ Analysis answers must include concrete numbers. When applicable, include percent
 
 Use `record_code_block_run` when the user wants to execute a form code-block field against an existing record.
 
-- Always resolve the exact code-block field from `record_code_block_schema_get` first.
+- Prefer resolving the exact code-block field from `record_code_block_schema_get`, but do not treat applicant-schema 40002 as final denial when record/task detail already exposes the code-block field id.
+- `record_code_block_run` uses the record/task detail answers for the execution context; when applicant schema is unavailable it can still execute with a numeric code-block field id, but schema-bound relation writeback may be skipped.
 - Treat code-block execution as write-capable, not read-only.
 - If the code block is bound to relation outputs, Qingflow may calculate target answers and write them back automatically.
 - For safe debugging, pass `apply_writeback=false` and inspect the parsed alias results plus `relation.calculated_answers_preview` before allowing any writeback.
@@ -190,7 +193,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, first choose an accessible view with `app_get`, then call `record_logs_get(app_key, record_id, view_id)` with that same explicit `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.
@@ -262,7 +265,7 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
     def record_export_start(
         profile: str = DEFAULT_PROFILE,
         app_key: str = "",
-        view_id: str = "system:all",
+        view_id: str = "",
         columns: list[dict | int] | None = None,
         where: list[dict] | None = None,
         order_by: list[dict] | None = None,
@@ -303,7 +306,7 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
     def record_export_direct(
         profile: str = DEFAULT_PROFILE,
         app_key: str = "",
-        view_id: str = "system:all",
+        view_id: str = "",
         columns: list[dict | int] | None = None,
         where: list[dict] | None = None,
         order_by: list[dict] | None = None,
@@ -360,12 +363,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:
@@ -477,7 +476,7 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
 
     code_block_tools.register(server)
     task_context_tools.register(server)
-    directory_tools.register(server)
+    directory_tools.register_frontend_search(server)
 
     return server