@qingflow-tech/qingflow-app-user-mcp 1.0.4 → 1.0.6

package/src/qingflow_mcp/server_app_user.py

@@ -33,7 +33,7 @@ def build_user_server() -> FastMCP:
 
 If `app_key` is unknown, use `app_list` or `app_search` first.
 If the app is known but the data range is not, use `app_get` first and choose from `accessible_views`.
-If an accessible view has `analysis_supported=false`, do not use it for `record_list` or `record_analyze`. `boardView` and `ganttView` are special UI views, not list/analyze targets.
+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.
 
 ## Shared Helper
@@ -49,7 +49,7 @@ If an accessible view has `analysis_supported=false`, do not use it for `record_
 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_list`, `record_get`, or `record_analyze`.
+Call `app_get` first when the data range is unclear, then use `record_browse_schema_get(view_id=...)` before `record_access`, `record_list`, or `record_get`.
 Call `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.
@@ -60,7 +60,9 @@ 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_browse_schema_get(view_id=...)` returns browse-schema fields for the selected accessible 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_import_schema_get` returns import-ready column metadata.
 
@@ -70,16 +72,19 @@ Inside `optional_fields`, any field with `may_become_required=true` is still wri
 
 ## Analytics Path
 
-`app_get -> record_browse_schema_get(view_id=...) -> record_analyze`
+`app_get -> record_browse_schema_get(view_id=...) -> record_access -> Python`
 
 Prefer `view_id` entries from `accessible_views` where `analysis_supported=true`.
 
-Use this DSL shape:
+Use `record_access` to write local CSV shard files, then use Python to compute counts, rankings, ratios, trends, and final conclusions. `record_access` does not return bulk `items`; read `files[].local_path`. CSV columns are readable and field-id anchored, such as `项目状态__field_343283094`, and `fields[]` is the compact metadata source.
+For analysis-style tasks, prefer an explicit time range or business filter. If `record_access.status == "needs_scope"`, do not treat it as a failure; ask for a time/business scope or retry with a user-provided period using `scope.suggested_time_fields` / `scope.recommended_where_examples`. If `record_access.status == "partial"`, read the returned files only as a limited subset and do not give a final full-population conclusion.
+Use `chart_get` only when the user provides a report URL / chart_id or explicitly asks to read an existing report. Do not use QingBI as the default analysis route.
 
-- `dimensions`: `{{field_id, alias, bucket}}`
-- `metrics`: `{{op, field_id, alias}}`
-- `filters`: `{{field_id, op, value}}`
-- `sort`: `{{by, order}}`
+Use this data-access DSL shape:
+
+- `columns`: `[{{field_id}}]`
+- `where`: `[{{field_id, op, value}}]`
+- `order_by`: `[{{field_id, direction}}]`
 
 Important key rules:
 
@@ -89,12 +94,16 @@ Important key rules:
 - Do **not** use `aggregation`
 - Do **not** use `operator`
 
+`record_list` is for browsing and sample checks, not final analysis conclusions.
+For fuzzy single-record lookup, use `record_list(query=..., query_fields=[{{field_id}}])` to find candidates, read `lookup.next_action`, and only call `record_get` after one candidate is clear.
+`record_list.query_fields` maps to backend full-text search scope (`searchQueIds`); `record_list.columns` only controls displayed fields.
+
 Analysis answers must include concrete numbers. When applicable, include percentages based on the returned totals.
 
 ## Record CRUD Path
 
 `app_get -> record_browse_schema_get(view_id=...) -> record_list / record_get`
-`record_insert_schema_get -> record_insert`
+`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`
@@ -102,11 +111,12 @@ Analysis answers must include concrete numbers. When applicable, include percent
 `portal_get -> view_get -> record_list`
 
 - Use `columns` as `[{{field_id}}]`
+- Use `query` plus optional `query_fields` when the user provides fuzzy record-identifying text
 - Use `where` items as `{{field_id, op, value}}`
 - Use `order_by` items as `{{field_id, direction}}`
 - 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` uses an applicant-node `fields` map keyed by field title.
+- `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.
 - 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.
@@ -115,10 +125,14 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - `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`.
-- When readback shape matters after insert or update, prefer `record_get(..., output_profile="normalized")` or `record_list(..., output_profile="normalized")`.
+- `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`.
+- 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.
 
 - Read relation targets from `record_insert_schema_get` / `record_update_schema_get` relation metadata before preparing relation writes.
-- Member and department fields may be written with natural strings directly on `record_insert` / `record_update`; only fall back to `record_member_candidates` or `record_department_candidates` when the user wants explicit candidate browsing or the write returns ambiguity that needs confirmation.
+- Member, department, and relation fields may be written with natural strings directly on `record_insert` / `record_update`; only fall back to candidate tools when the user wants explicit candidate browsing or the write returns ambiguity that needs confirmation.
+- For batch insert `partial_success`, read `created_record_ids`, failed `items[].row_number`, and `failed_fields`; repair only failed rows and never retry the whole batch after any row has `write_executed=true`.
 - When candidate browsing must match a real update/write scope, pass `record_id`, `workflow_node_id`, and any pending `fields` context to the candidate tool; otherwise the candidate result is only a static applicant-node preview.
 - If explicit candidate browsing is needed for default-all member or department fields, prefer those field candidate tools instead of starting with `directory_*`.
 
@@ -146,9 +160,12 @@ Use `record_code_block_run` when the user wants to execute a form code-block fie
 
 ## Export Path
 
+Use export only when the user explicitly asks to export/download/generate an Excel or export file.
+
 `view_get -> record_export_start -> record_export_status_get -> record_export_get`
 
 - `record_export_direct` is the one-shot path that starts export, waits, downloads locally, and still returns remote download links.
+- Do not use `record_export_direct` as the default analysis path; use `record_access -> Python` instead.
 - Export v1 supports record views only and follows the same public `view_id` semantics as `record_list`.
 - `record_export_start` / `record_export_direct` support frontend-like row selection:
   - omit `record_ids` to export all rows in the selected view