@josephyan/qingflow-app-builder-mcp 1.1.24 → 1.1.26

package/src/qingflow_mcp/server.py

@@ -50,7 +50,6 @@ All resource tools operate with the logged-in user's Qingflow permissions.
 
 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.
 
@@ -58,7 +57,7 @@ If an accessible view has `analysis_supported=false`, do not use it for `record_
 
 Call `record_insert_schema_get` before `record_insert`.
 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 `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`, `record_get`, or `record_logs_get`.
 Call `record_import_schema_get` when the import field mapping is unclear before template download or verify.
 
@@ -68,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 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_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.
@@ -107,8 +106,8 @@ Analysis answers must include concrete numbers. When applicable, include percent
 `app_get -> record_browse_schema_get(view_id=...) -> record_list / record_get / record_logs_get`
 `record_insert_schema_get -> record_insert(items)`
 `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`
+`record_list / record_get -> record_delete`
+`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.
@@ -117,14 +116,14 @@ 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. 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.
+- `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 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_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.
@@ -141,8 +140,7 @@ 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.
 
-- 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.
+- Always resolve the exact code-block field from `record_code_block_schema_get` first.
 - 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.
@@ -184,12 +182,12 @@ Use `record_code_block_run` when the user wants to execute a form code-block fie
 `task_list -> task_get -> task_action_execute`
 
 - `task_list` returns task-card summaries keyed by `task_id`.
-- For detail reads and actions, pass the exact `task_id` from `task_list.data.items[].task_id`.
-- `task_id` is not a row number, list index, record id, or workflow node id.
-- `task_action_execute` only uses `task_id`; do not reconstruct or pass `app_key + record_id + workflow_node_id` for actions.
+- Prefer `task_get(task_id=...)` for detail reads; MCP resolves the current todo locator internally.
+- `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 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`.
+- 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

@@ -37,22 +37,21 @@ def build_builder_server() -> FastMCP:
             "Use solution_install when the user explicitly wants to install a packaged solution/template by solution_key, optionally copying bundled demo data. "
             "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, "
+            "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_flow_get/app_flow_get_schema/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/portal_delete to execute normalized patches; these apply/delete tools perform basic validation, normalization, writes, and readback verification 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 delete separates DELETE execution from readback verification, 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. "
+            "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 sections should use chart for QingBI blocks so portal_apply can inline create/update app-source charts before saving the portal, 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. 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 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 portal BI blocks, prefer portal_apply sections[].chart so the portal write can inline create/update app-source QingBI charts and attach the resulting chart_id. Use app_charts_apply for advanced standalone report maintenance such as batch edits, deletes, or reordering; 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. "
             "Use package_apply to manage package metadata, visibility, grouping, and ordering, and app_publish_verify for explicit final publish verification. "
-            "For workflow edits, keep the public builder surface on stable linear flows only: start/approve/fill/copy/webhook/end. Branch and condition nodes are intentionally disabled because the backend workflow route is not front-end stable for those node types. Declare node assignees and editable fields explicitly. "
+            "For workflow edits, use app_flow_get_schema and app_flow_get (GET-first), author a complete WorkflowSpecDTO in spec, then app_flow_apply; CLI equivalent is qingflow builder flow schema|get|apply --spec-file. Do not use general-server legacy workflow config reads (auditNodes list/detail, global settings, qsource config reads); they are removed. "
             "If builder writes are blocked by the current user's own edit lock, use app_release_edit_lock_if_mine with the lock owner details from the failed result. "
             "Do not handcraft internal solution payloads or rely on build_id/stage/repair. "
             "If the current MCP capability is unsupported, the workflow is awkward, or the user's need still cannot be satisfied after reasonable use, first summarize the gap, ask whether to submit feedback, and call feedback_submit only after explicit user confirmation."
@@ -197,6 +196,7 @@ def build_builder_server() -> FastMCP:
         profile: str = DEFAULT_PROFILE,
         package_id: int | None = None,
         package_name: str | None = None,
+        create_if_missing: bool = False,
         icon: str | None = None,
         color: str | None = None,
         visibility: dict | None = None,
@@ -207,6 +207,7 @@ def build_builder_server() -> FastMCP:
             profile=profile,
             package_id=package_id,
             package_name=package_name,
+            create_if_missing=create_if_missing,
             icon=icon,
             color=color,
             visibility=visibility,
@@ -319,7 +320,6 @@ def build_builder_server() -> FastMCP:
         patch_buttons: list[dict] | None = None,
         remove_buttons: list[dict] | None = None,
         view_configs: list[dict] | None = None,
-        apps: list[dict] | None = None,
     ) -> dict:
         return ai_builder.app_custom_buttons_apply(
             profile=profile,
@@ -328,7 +328,6 @@ def build_builder_server() -> FastMCP:
             patch_buttons=patch_buttons or [],
             remove_buttons=remove_buttons or [],
             view_configs=view_configs or [],
-            apps=apps,
         )
 
     @server.tool()
@@ -340,7 +339,6 @@ def build_builder_server() -> FastMCP:
         remove_associated_item_ids: list[int] | None = None,
         reorder_associated_item_ids: list[int] | None = None,
         view_configs: list[dict] | None = None,
-        apps: list[dict] | None = None,
     ) -> dict:
         return ai_builder.app_associated_resources_apply(
             profile=profile,
@@ -350,16 +348,15 @@ def build_builder_server() -> FastMCP:
             remove_associated_item_ids=remove_associated_item_ids or [],
             reorder_associated_item_ids=reorder_associated_item_ids or [],
             view_configs=view_configs or [],
-            apps=apps,
         )
 
     @server.tool()
-    def app_get(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> dict:
-        return ai_builder.app_get(profile=profile, app_key=app_key, app_keys=app_keys)
+    def app_get(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:
+        return ai_builder.app_get(profile=profile, app_key=app_key)
 
     @server.tool()
-    def app_get_fields(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> dict:
-        return ai_builder.app_get_fields(profile=profile, app_key=app_key, app_keys=app_keys)
+    def app_get_fields(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:
+        return ai_builder.app_get_fields(profile=profile, app_key=app_key)
 
     @server.tool()
     def app_repair_code_blocks(
@@ -371,28 +368,20 @@ def build_builder_server() -> FastMCP:
         return ai_builder.app_repair_code_blocks(profile=profile, app_key=app_key, field=field, apply=apply)
 
     @server.tool()
-    def app_get_layout(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> dict:
-        return ai_builder.app_get_layout(profile=profile, app_key=app_key, app_keys=app_keys)
-
-    @server.tool()
-    def app_get_views(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> dict:
-        return ai_builder.app_get_views(profile=profile, app_key=app_key, app_keys=app_keys)
-
-    @server.tool()
-    def app_get_flow(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> dict:
-        return ai_builder.app_get_flow(profile=profile, app_key=app_key, app_keys=app_keys)
+    def app_get_layout(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:
+        return ai_builder.app_get_layout(profile=profile, app_key=app_key)
 
     @server.tool()
-    def app_get_charts(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> dict:
-        return ai_builder.app_get_charts(profile=profile, app_key=app_key, app_keys=app_keys)
+    def app_get_views(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:
+        return ai_builder.app_get_views(profile=profile, app_key=app_key)
 
     @server.tool()
-    def app_get_buttons(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> dict:
-        return ai_builder.app_get_buttons(profile=profile, app_key=app_key, app_keys=app_keys)
+    def app_get_flow(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:
+        return ai_builder.app_get_flow(profile=profile, app_key=app_key)
 
     @server.tool()
-    def app_get_associated_resources(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> dict:
-        return ai_builder.app_get_associated_resources(profile=profile, app_key=app_key, app_keys=app_keys)
+    def app_get_charts(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:
+        return ai_builder.app_get_charts(profile=profile, app_key=app_key)
 
     @server.tool()
     def portal_list(profile: str = DEFAULT_PROFILE) -> dict:
@@ -424,18 +413,18 @@ def build_builder_server() -> FastMCP:
         icon: str = "",
         color: str = "",
         visibility: dict | None = None,
+        create_if_missing: bool = False,
         publish: bool = True,
-        form: list[dict] | None = None,
         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 form or add_fields or update_fields or remove_fields:
+            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 plus apps only.",
-                    fix_hint="Use apps[].form for batch mode, or use the single-app arguments without apps.",
+                    "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(
@@ -446,8 +435,8 @@ def build_builder_server() -> FastMCP:
                 profile=profile,
                 package_id=package_id,
                 visibility=visibility,
+                create_if_missing=create_if_missing,
                 publish=publish,
-                form=None,
                 add_fields=[],
                 update_fields=[],
                 remove_fields=[],
@@ -457,17 +446,16 @@ def build_builder_server() -> FastMCP:
         has_app_name = bool((app_name or "").strip())
         has_app_title = bool((app_title or "").strip())
         has_package_id = package_id is not None
-        create_by_shape = has_package_id and (has_app_name or has_app_title)
         if has_app_key:
-            if has_package_id:
+            if create_if_missing or has_package_id:
                 return _config_failure(
                     "app_schema_apply edit mode accepts app_key and optional app_name rename only.",
-                    fix_hint="For existing apps, use `app_key` and optionally `app_name`. For create mode, use `package_id + app_name`.",
+                    fix_hint="For existing apps, use `app_key` and optionally `app_name`. For create mode, use `package_id + app_name + create_if_missing=true`.",
                 )
-        elif not create_by_shape:
+        elif not (create_if_missing and has_package_id and (has_app_name or has_app_title)):
             return _config_failure(
-                "app_schema_apply create mode requires package_id and app_name.",
-                fix_hint="Use `app_key` for existing apps, or pass `package_id + app_name` to create a new app.",
+                "app_schema_apply create mode requires package_id, app_name, and create_if_missing=true.",
+                fix_hint="Use `app_key` for existing apps, or pass `package_id + app_name + create_if_missing=true` to create a new app.",
             )
         return ai_builder.app_schema_apply(
             profile=profile,
@@ -478,12 +466,12 @@ def build_builder_server() -> FastMCP:
             icon=icon,
             color=color,
             visibility=visibility,
+            create_if_missing=create_if_missing,
             publish=publish,
-            form=form or [],
             add_fields=add_fields or [],
             update_fields=update_fields or [],
             remove_fields=remove_fields or [],
-            apps=None,
+            apps=[],
         )
 
     @server.tool()
@@ -493,17 +481,12 @@ def build_builder_server() -> FastMCP:
         mode: str = "merge",
         publish: bool = True,
         sections: list[dict] | None = None,
-        apps: list[dict] | None = None,
     ) -> dict:
-        return ai_builder.app_layout_apply(profile=profile, app_key=app_key, mode=mode, publish=publish, sections=sections or [], apps=apps)
+        return ai_builder.app_layout_apply(profile=profile, app_key=app_key, mode=mode, publish=publish, sections=sections or [])
 
     @server.tool()
-    def app_flow_get(
-        profile: str = DEFAULT_PROFILE,
-        app_key: str = "",
-        version_id: str = "",
-    ) -> dict:
-        return ai_builder.app_flow_get(profile=profile, app_key=app_key, version_id=version_id or None)
+    def app_flow_get(profile: str = DEFAULT_PROFILE, app_key: str = "", version_id: str = "") -> dict:
+        return ai_builder.app_get_flow(profile=profile, app_key=app_key, version_id=version_id or None)
 
     @server.tool()
     def app_flow_get_schema(profile: str = DEFAULT_PROFILE, schema_version: str = "") -> dict:
@@ -513,26 +496,18 @@ def build_builder_server() -> FastMCP:
     def app_flow_apply(
         profile: str = DEFAULT_PROFILE,
         app_key: str = "",
-        mode: str = "replace",
         publish: bool = True,
-        nodes: list[dict] | None = None,
-        transitions: list[dict] | None = None,
         spec: dict | None = None,
         idempotency_key: str = "",
         schema_version: str = "",
-        patch_nodes: list[dict] | None = None,
     ) -> dict:
         return ai_builder.app_flow_apply(
             profile=profile,
             app_key=app_key,
-            mode=mode,
             publish=publish,
-            nodes=nodes or [],
-            transitions=transitions or [],
-            spec=spec,
+            spec=spec or {},
             idempotency_key=idempotency_key or None,
             schema_version=schema_version or None,
-            patch_nodes=patch_nodes,
         )
 
     @server.tool()
@@ -543,7 +518,6 @@ def build_builder_server() -> FastMCP:
         upsert_views: list[dict] | None = None,
         patch_views: list[dict] | None = None,
         remove_views: list[str] | None = None,
-        apps: list[dict] | None = None,
     ) -> dict:
         return ai_builder.app_views_apply(
             profile=profile,
@@ -552,7 +526,6 @@ def build_builder_server() -> FastMCP:
             upsert_views=upsert_views or [],
             patch_views=patch_views or [],
             remove_views=remove_views or [],
-            apps=apps,
         )
 
     @server.tool()
@@ -563,7 +536,6 @@ def build_builder_server() -> FastMCP:
         patch_charts: list[dict] | None = None,
         remove_chart_ids: list[str] | None = None,
         reorder_chart_ids: list[str] | None = None,
-        apps: list[dict] | None = None,
     ) -> dict:
         return ai_builder.app_charts_apply(
             profile=profile,
@@ -572,7 +544,6 @@ def build_builder_server() -> FastMCP:
             patch_charts=patch_charts or [],
             remove_chart_ids=remove_chart_ids or [],
             reorder_chart_ids=reorder_chart_ids or [],
-            apps=apps,
         )
 
     @server.tool()
@@ -594,7 +565,6 @@ def build_builder_server() -> FastMCP:
         dash_global_config: dict | None = None,
         config: dict | None = None,
         payload: dict | None = None,
-        patch_sections: list[dict] | None = None,
     ) -> dict:
         payload = payload if isinstance(payload, dict) else {}
         has_dash_key = bool((dash_key or "").strip())
@@ -630,30 +600,17 @@ def build_builder_server() -> FastMCP:
             dash_global_config=dash_global_config,
             config=config or {},
             payload=payload,
-            patch_sections=patch_sections,
-        )
-
-    @server.tool()
-    def portal_delete(
-        profile: str = DEFAULT_PROFILE,
-        dash_key: str = "",
-    ) -> dict:
-        return ai_builder.portal_delete(
-            profile=profile,
-            dash_key=dash_key,
         )
 
     @server.tool()
     def app_publish_verify(
         profile: str = DEFAULT_PROFILE,
         app_key: str = "",
-        app_keys: list[str] | None = None,
         expected_package_id: int | None = None,
     ) -> dict:
         return ai_builder.app_publish_verify(
             profile=profile,
             app_key=app_key,
-            app_keys=app_keys,
             expected_package_id=expected_package_id,
         )
 

package/src/qingflow_mcp/server_app_user.py

@@ -33,7 +33,6 @@ def build_user_server() -> FastMCP:
 
 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.
 
@@ -49,7 +48,7 @@ If an accessible view has `analysis_supported=false`, do not use it for `record_
 
 Call `record_insert_schema_get` before `record_insert`.
 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 `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`, `record_get`, or `record_logs_get`.
 Call `record_import_schema_get` when the import field mapping is unclear before template download or verify.
 
@@ -60,11 +59,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 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_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.
-`record_code_block_schema_get` returns code-block-ready schema for exact code block field selection when the applicant schema is readable.
+`record_code_block_schema_get` returns code-block-ready schema for exact code block field selection.
 `record_import_schema_get` returns import-ready column metadata.
 
 - Hidden fields are omitted.
@@ -106,8 +105,8 @@ Analysis answers must include concrete numbers. When applicable, include percent
 `app_get -> record_browse_schema_get(view_id=...) -> record_list / record_get / record_logs_get`
 `record_insert_schema_get -> record_insert(items)`
 `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`
+`record_list / record_get -> record_delete`
+`record_code_block_schema_get -> record_code_block_run`
 `portal_list -> portal_get -> chart_get / view_get`
 `portal_get -> view_get -> record_list`
 
@@ -118,14 +117,14 @@ 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. 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.
+- `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 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_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.
@@ -143,8 +142,7 @@ 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.
 
-- 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.
+- Always resolve the exact code-block field from `record_code_block_schema_get` first.
 - 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.
@@ -189,12 +187,12 @@ Use export only when the user explicitly asks to export/download/generate an Exc
 `task_list -> task_get -> task_action_execute`
 
 - `task_list` returns task-card summaries keyed by `task_id`.
-- For detail reads and actions, pass the exact `task_id` from `task_list.data.items[].task_id`.
-- `task_id` is not a row number, list index, record id, or workflow node id.
-- `task_action_execute` only uses `task_id`; do not reconstruct or pass `app_key + record_id + workflow_node_id` for actions.
+- Prefer `task_get(task_id=...)` for detail reads; MCP resolves the current todo locator internally.
+- `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 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`.
+- 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.
 - `save_only` is exposed only when the backend current-node `editableQueIds` signal returns a non-empty result; MCP no longer infers `save_only` from local schema reconstruction.
@@ -265,11 +263,10 @@ 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 = "",
+        view_id: str = "system:all",
         columns: list[dict | int] | None = None,
         where: list[dict] | None = None,
         order_by: list[dict] | None = None,
-        record_id: str | int | None = None,
         record_ids: list[str | int] | None = None,
         include_workflow_log: bool = False,
     ) -> dict:
@@ -280,7 +277,6 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
             columns=columns or [],
             where=where or [],
             order_by=order_by or [],
-            record_id=record_id,
             record_ids=record_ids or [],
             include_workflow_log=include_workflow_log,
         )
@@ -308,11 +304,10 @@ 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 = "",
+        view_id: str = "system:all",
         columns: list[dict | int] | None = None,
         where: list[dict] | None = None,
         order_by: list[dict] | None = None,
-        record_id: str | int | None = None,
         record_ids: list[str | int] | None = None,
         include_workflow_log: bool = False,
         download_to_path: str | None = None,
@@ -325,7 +320,6 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
             columns=columns or [],
             where=where or [],
             order_by=order_by or [],
-            record_id=record_id,
             record_ids=record_ids or [],
             include_workflow_log=include_workflow_log,
             download_to_path=download_to_path,
@@ -480,7 +474,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_frontend_search(server)
+    directory_tools.register(server)
 
     return server
 

package/src/qingflow_mcp/session_store.py

@@ -176,21 +176,17 @@ class SessionStore:
             return memory_session
         if not session_profile:
             return None
-        token = session_profile.token
-        if not token and session_profile.persisted:
-            token = self._get_secret(self._token_key(profile))
+        token = self._get_secret(self._token_key(profile)) if session_profile.persisted else None
+        if not token:
+            token = session_profile.token
         if not token:
             return None
-        login_token = session_profile.login_token
-        if not login_token and session_profile.persisted:
-            login_token = self._get_secret(self._login_token_key(profile))
-        credential = session_profile.credential
-        if not credential and session_profile.persisted:
-            credential = self._get_secret(self._credential_key(profile))
+        login_token = self._get_secret(self._login_token_key(profile)) if session_profile.persisted else None
+        credential = self._get_secret(self._credential_key(profile)) if session_profile.persisted else None
         backend_session = BackendSession(
             token=token,
-            login_token=login_token,
-            credential=credential,
+            login_token=login_token or session_profile.login_token,
+            credential=credential or session_profile.credential,
             profile=profile,
             base_url=session_profile.base_url,
             qf_version=session_profile.qf_version,

package/src/qingflow_mcp/solution/compiler/__init__.py

@@ -10,8 +10,6 @@ from .navigation_compiler import compile_navigation
 from .package_compiler import compile_package
 from .portal_compiler import compile_portal
 from .view_compiler import compile_views
-from .workflow_compiler import compile_workflow
-
 
 @dataclass(slots=True)
 class ExecutionStep:
@@ -101,7 +99,7 @@ def compile_solution(spec: SolutionSpec) -> CompiledSolution:
 
 def compile_entity(entity: EntitySpec, *, include_package: bool) -> CompiledEntity:
     app_create_payload, form_base_payload, form_relation_payload, field_specs, field_labels = compile_entity_form(entity, include_package=include_package)
-    workflow_plan = compile_workflow(entity)
+    workflow_plan = None
     view_plans = compile_views(entity)
     chart_plans = compile_charts(entity)
     return CompiledEntity(