@josephyan/qingflow-cli 0.2.0-beta.1015 → 0.2.0-beta.1017

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-cli@0.2.0-beta.1015
+npm install @josephyan/qingflow-cli@0.2.0-beta.1017
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-cli@0.2.0-beta.1015 qingflow
+npx -y -p @josephyan/qingflow-cli@0.2.0-beta.1017 qingflow
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-cli",
-  "version": "0.2.0-beta.1015",
+  "version": "0.2.0-beta.1017",
   "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "0.2.0b1015"
+version = "0.2.0b1017"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/src/qingflow_mcp/__init__.py

@@ -5,7 +5,7 @@ from pathlib import Path
 
 __all__ = ["__version__"]
 
-_FALLBACK_VERSION = "0.2.0b1015"
+_FALLBACK_VERSION = "0.2.0b1017"
 
 
 def _resolve_local_pyproject_version() -> str | None:

package/src/qingflow_mcp/cli/formatters.py

@@ -407,6 +407,13 @@ def _format_import_status(result: dict[str, Any]) -> str:
         f"Failed Rows: {result.get('failed') or 0}",
         f"Progress: {result.get('progress') or '-'}",
     ]
+    if result.get("process_status") not in (None, ""):
+        lines.append(f"Process Status: {result.get('process_status')}")
+    error_file_urls = result.get("error_file_urls") if isinstance(result.get("error_file_urls"), list) else []
+    if error_file_urls:
+        lines.append("Error Files:")
+        for url in error_file_urls:
+            lines.append(f"- {url}")
     _append_warnings(lines, result.get("warnings"))
     _append_verification(lines, result.get("verification"))
     return "\n".join(lines) + "\n"

package/src/qingflow_mcp/response_trim.py

@@ -666,7 +666,6 @@ def _trim_import_status_payload(payload: JSONObject) -> None:
         "total_rows",
         "success_rows",
         "failed_rows",
-        "error_file_urls",
         "operate_time",
         "operate_user",
         "verification",

package/src/qingflow_mcp/tools/export_tools.py

@@ -11,6 +11,7 @@ from uuid import uuid4
 
 from mcp.server.fastmcp import FastMCP
 
+from ..backend_client import BackendRequestContext
 from ..config import DEFAULT_PROFILE, DEFAULT_RECORD_LIST_TYPE
 from ..errors import QingflowApiError
 from ..export_store import ExportJobStore
@@ -192,6 +193,8 @@ class ExportTools(ToolBase):
             filter_bean = self._build_export_filter_bean(
                 resolved_view,
                 selected_record_ids=effective_record_ids,
+                order_by=normalized_order_by,
+                row_scope=row_scope,
                 include_workflow_log=include_workflow_log,
             )
             started_at = _utc_now().replace(microsecond=0).isoformat()
@@ -211,6 +214,10 @@ class ExportTools(ToolBase):
                 {
                     "created_at": started_at,
                     "profile": profile,
+                    "base_url": context.base_url,
+                    "ws_id": context.ws_id,
+                    "qf_version": context.qf_version,
+                    "qf_version_source": context.qf_version_source,
                     "app_key": normalized_app_key,
                     "view_id": resolved_view.view_id,
                     "backend_export_id": str(socket_result.get("backend_export_id") or ""),
@@ -278,7 +285,7 @@ class ExportTools(ToolBase):
                 extra={"status": "failed"},
             )
 
-        def runner(_session_profile, context):
+        def runner(session_profile, context):
             local_job = self._job_store.get(normalized_handle)
             if local_job is None:
                 return self._failed_export_result(
@@ -286,7 +293,13 @@ class ExportTools(ToolBase):
                     message="export_handle is missing or expired",
                     extra={"export_handle": normalized_handle, "status": "failed"},
                 )
-            snapshot = self._resolve_export_snapshot(context, local_job)
+            lookup_context = self._build_export_lookup_context(
+                profile=profile,
+                session_profile=session_profile,
+                current_context=context,
+                local_job=local_job,
+            )
+            snapshot = self._resolve_export_snapshot(lookup_context, local_job)
             return self._status_payload_from_snapshot(local_job, normalized_handle, snapshot)
 
         try:
@@ -314,7 +327,7 @@ class ExportTools(ToolBase):
                 extra={"status": "failed"},
             )
 
-        def runner(_session_profile, context):
+        def runner(session_profile, context):
             local_job = self._job_store.get(normalized_handle)
             if local_job is None:
                 return self._failed_export_result(
@@ -322,7 +335,13 @@ class ExportTools(ToolBase):
                     message="export_handle is missing or expired",
                     extra={"export_handle": normalized_handle, "status": "failed"},
                 )
-            snapshot = self._resolve_export_snapshot(context, local_job)
+            lookup_context = self._build_export_lookup_context(
+                profile=profile,
+                session_profile=session_profile,
+                current_context=context,
+                local_job=local_job,
+            )
+            snapshot = self._resolve_export_snapshot(lookup_context, local_job)
             normalized_status = str(snapshot.get("status") or "unknown")
             if normalized_status not in {"succeeded", "failed"}:
                 return self._failed_export_result(
@@ -412,7 +431,7 @@ class ExportTools(ToolBase):
                 "downloaded_files": downloaded_files,
                 "warnings": snapshot.get("warnings") or [],
                 "verification": snapshot.get("verification") or {},
-                "request_route": self.backend.describe_route(context),
+                "request_route": self.backend.describe_route(lookup_context),
             }
 
         try:
@@ -449,7 +468,7 @@ class ExportTools(ToolBase):
             )
         timeout_seconds = self._normalize_timeout_seconds(wait_timeout_seconds)
 
-        def runner(_session_profile, context):
+        def runner(session_profile, context):
             start_result = self.record_export_start(
                 profile=profile,
                 app_key=normalized_app_key,
@@ -473,7 +492,13 @@ class ExportTools(ToolBase):
                         message="export_handle is missing or expired",
                         extra={"status": "failed", "export_handle": export_handle},
                     )
-                snapshot = self._resolve_export_snapshot(context, local_job)
+                lookup_context = self._build_export_lookup_context(
+                    profile=profile,
+                    session_profile=session_profile,
+                    current_context=context,
+                    local_job=local_job,
+                )
+                snapshot = self._resolve_export_snapshot(lookup_context, local_job)
                 last_snapshot = snapshot
                 normalized_status = str(snapshot.get("status") or "unknown")
                 if normalized_status == "succeeded":
@@ -581,6 +606,49 @@ class ExportTools(ToolBase):
                 extra={"app_key": normalized_app_key, "view_id": normalized_view_id},
             )
 
+    def _build_export_lookup_context(
+        self,
+        *,
+        profile: str,
+        session_profile,
+        current_context: BackendRequestContext,
+        local_job: dict[str, Any],
+    ) -> BackendRequestContext:
+        stored_profile = str(local_job.get("profile") or "").strip()
+        if stored_profile and stored_profile != profile:
+            raise QingflowApiError.config_error(
+                "export_handle was created under a different profile",
+                details={
+                    "error_code": "EXPORT_HANDLE_PROFILE_MISMATCH",
+                    "expected_profile": stored_profile,
+                    "received_profile": profile,
+                },
+            )
+        stored_uid = _coerce_positive_int(local_job.get("uid"))
+        if stored_uid is not None and stored_uid != session_profile.uid:
+            raise QingflowApiError.config_error(
+                "export_handle belongs to a different authenticated user",
+                details={
+                    "error_code": "EXPORT_HANDLE_OWNER_MISMATCH",
+                    "expected_uid": stored_uid,
+                    "current_uid": session_profile.uid,
+                },
+            )
+        stored_base_url = str(local_job.get("base_url") or "").strip() or current_context.base_url
+        stored_ws_id = _coerce_positive_int(local_job.get("ws_id"))
+        stored_qf_version = str(local_job.get("qf_version") or "").strip() or current_context.qf_version
+        stored_qf_version_source = (
+            str(local_job.get("qf_version_source") or "").strip() or current_context.qf_version_source
+        )
+        return BackendRequestContext(
+            base_url=stored_base_url,
+            token=current_context.token,
+            ws_id=stored_ws_id if stored_ws_id is not None else current_context.ws_id,
+            qf_request_id=current_context.qf_request_id,
+            qf_version=stored_qf_version,
+            qf_version_source=stored_qf_version_source,
+        )
+
     def _resolve_export_record_scope(
         self,
         *,
@@ -732,6 +800,8 @@ class ExportTools(ToolBase):
         resolved_view: AccessibleViewRoute,
         *,
         selected_record_ids: list[int],
+        order_by: list[JSONObject],
+        row_scope: str,
         include_workflow_log: bool,
     ) -> JSONObject:
         filter_payload: JSONObject = {}
@@ -744,6 +814,17 @@ class ExportTools(ToolBase):
             filter_payload["type"] = DEFAULT_RECORD_LIST_TYPE
         if selected_record_ids:
             filter_payload["applyIds"] = selected_record_ids
+        if row_scope == "queried" and order_by:
+            normalized_sorts = [
+                {
+                    "queId": field_id,
+                    "isAscend": str(item.get("direction") or "asc").strip().lower() != "desc",
+                }
+                for item in order_by
+                if isinstance(item, dict) and (field_id := _coerce_int(item.get("field_id"))) is not None
+            ]
+            if normalized_sorts:
+                filter_payload["sorts"] = normalized_sorts
         return {
             "filter": filter_payload,
             # Backend export code later auto-unboxes this field to primitive boolean.

package/src/qingflow_mcp/tools/import_tools.py

@@ -37,6 +37,13 @@ SAFE_REPAIRS = {
     "normalize_url_cells",
 }
 EMAIL_PATTERN = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
+IMPORT_STATUS_BY_PROCESS_STATUS = {
+    1: "queued",
+    2: "running",
+    3: "succeeded",
+    4: "failed",
+    5: "partially_failed",
+}
 
 
 class ImportTools(ToolBase):
@@ -866,13 +873,26 @@ class ImportTools(ToolBase):
                         "process_id_str": normalized_process,
                     },
                 )
+            raw_process_status = matched_record.get("processStatus")
             total_rows = _coerce_int(matched_record.get("totalNumber") or matched_record.get("total_rows"))
             success_rows = _coerce_int(matched_record.get("successNum") or matched_record.get("success_rows"))
             failed_rows = _coerce_int(matched_record.get("errorNum") or matched_record.get("failed_rows"))
             progress = _coerce_int(matched_record.get("importPercentage") or matched_record.get("progress"))
+            normalized_status = _normalize_import_status(raw_process_status)
+            warnings: list[dict[str, str]] = []
+            if normalized_status in {"succeeded", "failed", "partially_failed"} and all(
+                value is None for value in (total_rows, success_rows, failed_rows)
+            ):
+                warnings.append(
+                    {
+                        "code": "IMPORT_STATUS_COUNTERS_MISSING",
+                        "message": "backend import history returned a terminal process status without row counters",
+                    }
+                )
             return {
                 "ok": True,
-                "status": _normalize_optional_text(matched_record.get("processStatus")) or "unknown",
+                "status": normalized_status,
+                "process_status": _coerce_int(raw_process_status),
                 "app_key": resolved_app_key,
                 "import_id": normalized_import_id or (local_job.get("import_id") if isinstance(local_job, dict) else None),
                 "process_id_str": normalized_process,
@@ -885,7 +905,7 @@ class ImportTools(ToolBase):
                 "error_file_urls": _normalize_error_file_urls(matched_record.get("errorFileUrls")),
                 "operate_time": matched_record.get("operateTime"),
                 "operate_user": matched_record.get("operateUser"),
-                "warnings": [],
+                "warnings": warnings,
                 "verification": {
                     "status_lookup_completed": True,
                     "matched_by": matched_by,
@@ -2217,6 +2237,26 @@ def _coerce_int(value: Any) -> int | None:
         return None
 
 
+def _normalize_import_status(value: Any) -> str:
+    status_code = _coerce_int(value)
+    if status_code is not None:
+        return IMPORT_STATUS_BY_PROCESS_STATUS.get(status_code, "unknown")
+    text = str(value or "").strip().lower()
+    if text in {"queued", "running", "succeeded", "failed", "partially_failed", "unknown"}:
+        return text
+    if text in {"line_up", "lineup"}:
+        return "queued"
+    if text in {"execute", "executing", "processing"}:
+        return "running"
+    if text in {"success", "completed"}:
+        return "succeeded"
+    if text in {"partly_fail", "partial_fail", "partially_fail", "partial_failed"}:
+        return "partially_failed"
+    if text in {"fail", "error"}:
+        return "failed"
+    return "unknown"
+
+
 def _normalize_error_file_urls(value: Any) -> list[str]:
     if isinstance(value, list):
         return [str(item).strip() for item in value if str(item).strip()]

package/src/qingflow_mcp/tools/record_tools.py

@@ -2920,12 +2920,14 @@ class RecordTools(ToolBase):
             payload["category"] = error.category
         if error.backend_code is not None:
             payload["backend_code"] = error.backend_code
+        if error.request_id is not None:
+            payload["request_id"] = error.request_id
         if error.http_status is not None:
             payload["http_status"] = error.http_status
         return payload
 
     def _is_record_context_route_miss(self, error: QingflowApiError) -> bool:
-        if error.backend_code in {40002, 40027, 40038, 404}:
+        if error.backend_code in {40002, 40023, 40027, 40038, 404}:
             return True
         if error.http_status == 404:
             return True
@@ -3059,6 +3061,107 @@ class RecordTools(ToolBase):
             f"({get_record_list_type_label(used_list_type)})."
         ]
 
+    def _looks_like_generic_record_update_backend_failure(self, exc: QingflowApiError) -> bool:
+        if exc.backend_code == 500:
+            return True
+        if exc.http_status is not None and exc.http_status >= 500:
+            return True
+        normalized_message = exc.message.strip().lower()
+        return normalized_message in {"unknown error", "internal server error"}
+
+    def _remap_record_update_target_context_error(
+        self,
+        profile: str,
+        context,  # type: ignore[no-untyped-def]
+        *,
+        app_key: str,
+        apply_id: int,
+        exc: QingflowApiError,
+    ) -> None:
+        if not self._looks_like_generic_record_update_backend_failure(exc):
+            return
+        try:
+            candidate_routes = self._candidate_update_views(profile, context, app_key)
+            probes = self._probe_candidate_record_contexts(
+                context,
+                app_key=app_key,
+                apply_id=apply_id,
+                candidate_routes=candidate_routes,
+            )
+        except (QingflowApiError, RuntimeError):
+            return
+        if not probes or any(probe.readable for probe in probes):
+            return
+
+        blocker = (
+            "CURRENT_RECORD_CONTEXT_UNAVAILABLE"
+            if all(probe.transport_error for probe in probes)
+            else "NO_MATCHING_ACCESSIBLE_VIEW_FOR_RECORD"
+        )
+        recommended_next_actions = (
+            [
+                "Retry after the record becomes readable in the current workspace/profile context.",
+                "If the issue persists, verify that the current profile still has read access to this record.",
+            ]
+            if blocker == "CURRENT_RECORD_CONTEXT_UNAVAILABLE"
+            else [
+                "Use record_get or record_list to confirm the record still exists in the current workspace.",
+                "Call record_update_schema_get to inspect whether any accessible view still matches this record.",
+            ]
+        )
+        first_error_payload = next(
+            (
+                cast(JSONObject, probe.error_payload)
+                for probe in probes
+                if isinstance(probe.error_payload, dict)
+            ),
+            None,
+        )
+        backend_code = (
+            cast(int, first_error_payload.get("backend_code"))
+            if isinstance(first_error_payload, dict) and isinstance(first_error_payload.get("backend_code"), int)
+            else exc.backend_code
+        )
+        request_id = (
+            _normalize_optional_text(first_error_payload.get("request_id"))
+            if isinstance(first_error_payload, dict)
+            else None
+        ) or exc.request_id
+        http_status = (
+            cast(int, first_error_payload.get("http_status"))
+            if isinstance(first_error_payload, dict) and isinstance(first_error_payload.get("http_status"), int)
+            else exc.http_status
+        )
+        raise_tool_error(
+            QingflowApiError(
+                category="backend",
+                message=(
+                    "Direct record edit was blocked because the current record context could not be loaded from any candidate route."
+                    if blocker == "CURRENT_RECORD_CONTEXT_UNAVAILABLE"
+                    else "Direct record edit was blocked because the target record is no longer accessible in any readable view for the current profile."
+                ),
+                backend_code=backend_code,
+                request_id=request_id,
+                http_status=http_status,
+                details={
+                    "error_code": blocker,
+                    "operation": "update",
+                    "app_key": app_key,
+                    "record_id": apply_id,
+                    "blockers": [blocker],
+                    "request_route": self._request_route_payload(context),
+                    "view_probe_summary": [
+                        self._record_context_probe_summary_payload(probe)
+                        for probe in probes
+                    ],
+                    "recommended_next_actions": recommended_next_actions,
+                    "fix_hint": (
+                        "Confirm the target record still exists and remains visible in at least one accessible view before retrying the update."
+                    ),
+                },
+            )
+        )
+
     def _record_matches_accessible_view(
         self,
         context,  # type: ignore[no-untyped-def]
@@ -6355,12 +6458,22 @@ class RecordTools(ToolBase):
                 force_refresh_form=force_refresh_form,
             )
             self._validate_record_write(app_key, normalized_answers, apply_id=normalized_apply_id)
-            result = self.backend.request(
-                "POST",
-                context,
-                f"/app/{app_key}/apply/{normalized_apply_id}",
-                json_body={"role": role, "answers": normalized_answers},
-            )
+            try:
+                result = self.backend.request(
+                    "POST",
+                    context,
+                    f"/app/{app_key}/apply/{normalized_apply_id}",
+                    json_body={"role": role, "answers": normalized_answers},
+                )
+            except QingflowApiError as exc:
+                self._remap_record_update_target_context_error(
+                    profile,
+                    context,
+                    app_key=app_key,
+                    apply_id=normalized_apply_id,
+                    exc=exc,
+                )
+                raise
             verification = self._verify_record_write_result(
                 context,
                 app_key=app_key,
@@ -8810,6 +8923,8 @@ class RecordTools(ToolBase):
                     error_payload["request_id"] = parsed.get("request_id")
                 if isinstance(parsed.get("request_route"), dict):
                     request_route = cast(JSONObject, parsed.get("request_route"))
+                elif details_payload is not None and isinstance(details_payload.get("request_route"), dict):
+                    request_route = cast(JSONObject, details_payload.get("request_route"))
         response: JSONObject = {
             "profile": profile,
             "ws_id": None,

package/src/qingflow_mcp/tools/resource_read_tools.py

@@ -96,7 +96,9 @@ class ResourceReadTools(ToolBase):
                 )
             )
         if system_view is not None:
-            export_capability = _view_export_capability_payload(supported=True)
+            export_capability = _view_export_capability_payload(
+                supported=_export_supported_for_view_type(system_view["view_type"])
+            )
             return self._run(
                 profile,
                 lambda session_profile, _context: {
@@ -133,13 +135,11 @@ class ResourceReadTools(ToolBase):
             )
 
         def runner(session_profile, context):
-            export_capability = _view_export_capability_payload(supported=True)
+            raw_view_type = None
             warnings: list[JSONObject] = []
             verification = {
                 "view_exists": True,
                 "questions_verified": True,
-                "export_route_supported": export_capability["supported"],
-                "export_permission_verified": export_capability["permission_verified"],
             }
             config = self.backend.request("GET", context, f"/view/{view_key}/viewConfig")
             base_info = self.backend.request("GET", context, f"/view/{view_key}/viewConfig/baseInfo")
@@ -161,6 +161,11 @@ class ResourceReadTools(ToolBase):
                 str(base_info.get("viewgraphType") or "").strip()
                 or str(config.get("viewgraphType") or config.get("viewType") or "").strip()
             )
+            export_capability = _view_export_capability_payload(
+                supported=_export_supported_for_view_type(raw_view_type or None)
+            )
+            verification["export_route_supported"] = export_capability["supported"]
+            verification["export_permission_verified"] = export_capability["permission_verified"]
             resolved_app_key = str(base_info.get("appKey") or config.get("appKey") or "").strip() or None
             if not resolved_app_key:
                 resolved_app_key = self._resolve_app_key_from_view_form(context=context, view_key=view_key)
@@ -176,12 +181,13 @@ class ResourceReadTools(ToolBase):
                         "message": f"view_get could not resolve app_key for `{view_id}` from view metadata; keep using the app_key from the parent app or portal context.",
                     }
                 )
-                warnings.append(
-                    {
-                        "code": "VIEW_EXPORT_APP_CONTEXT_REQUIRED",
-                        "message": f"view_get supports exporting `{view_id}`, but the export call still needs an explicit `app_key` from the parent app context.",
-                    }
-                )
+                if export_capability["supported"]:
+                    warnings.append(
+                        {
+                            "code": "VIEW_EXPORT_APP_CONTEXT_REQUIRED",
+                            "message": f"view_get supports exporting `{view_id}`, but the export call still needs an explicit `app_key` from the parent app context.",
+                        }
+                    )
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
@@ -493,6 +499,10 @@ def _view_export_capability_payload(*, supported: bool) -> JSONObject:
     }
 
 
+def _export_supported_for_view_type(view_type: str | None) -> bool:
+    return _analysis_supported_for_view_type(view_type)
+
+
 def _normalize_view_type(view_type: Any) -> str | None:
     value = str(view_type or "").strip()
     if not value: