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

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,
@@ -6890,6 +7003,8 @@ class RecordTools(ToolBase):
             isinstance(payload.get("viewgraphLimit"), list)
             or isinstance(payload.get("viewConfig"), dict)
             or isinstance(payload.get("viewgraphConfig"), dict)
+            or isinstance(payload.get("viewgraphQuestions"), list)
+            or isinstance(payload.get("viewgraphQueIds"), list)
         ):
             config = payload
         else:
@@ -8794,7 +8909,13 @@ class RecordTools(ToolBase):
             except json.JSONDecodeError:
                 parsed = None
             if isinstance(parsed, dict):
-                error_payload["error_code"] = parsed.get("error_code") or cast(JSONObject, parsed.get("details", {})).get("error_code") or error_payload["error_code"]
+                parsed_details = parsed.get("details")
+                details_payload = cast(JSONObject, parsed_details) if isinstance(parsed_details, dict) else None
+                error_payload["error_code"] = (
+                    parsed.get("error_code")
+                    or (details_payload.get("error_code") if details_payload is not None else None)
+                    or error_payload["error_code"]
+                )
                 error_payload["message"] = parsed.get("message") or error_payload["message"]
                 if parsed.get("backend_code") is not None:
                     error_payload["backend_code"] = parsed.get("backend_code")
@@ -8802,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,
@@ -10089,11 +10212,20 @@ class RecordTools(ToolBase):
         """执行内部辅助逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
-        try:
-            normalized_apply_id = normalize_positive_id_int(apply_id, field_name="apply_id")
-        except QingflowApiError:
-            raise_tool_error(QingflowApiError.config_error("apply_id must be positive"))
-        return normalized_apply_id
+        return self._normalize_internal_backend_id(apply_id, field_name="apply_id")
+
+    def _normalize_internal_backend_id(self, value: Any, *, field_name: str) -> int:
+        """Normalize backend/apply ids after the public boundary has already preserved long string ids."""
+        if value in (None, "") or isinstance(value, bool):
+            raise_tool_error(QingflowApiError.config_error(f"{field_name} must be positive"))
+        if isinstance(value, int):
+            if value <= 0:
+                raise_tool_error(QingflowApiError.config_error(f"{field_name} must be positive"))
+            return value
+        text = stringify_backend_id(value)
+        if text is None or not text.isdecimal() or int(text) <= 0:
+            raise_tool_error(QingflowApiError.config_error(f"{field_name} must be positive"))
+        return int(text)
 
     def _validate_record_write(self, app_key: str, answers: list[JSONObject], apply_id: int | None = None) -> None:
         """执行内部辅助逻辑。"""

package/src/qingflow_mcp/tools/resource_read_tools.py

@@ -96,6 +96,9 @@ class ResourceReadTools(ToolBase):
                 )
             )
         if system_view is not None:
+            export_capability = _view_export_capability_payload(
+                supported=_export_supported_for_view_type(system_view["view_type"])
+            )
             return self._run(
                 profile,
                 lambda session_profile, _context: {
@@ -106,11 +109,17 @@ class ResourceReadTools(ToolBase):
                         {
                             "code": "VIEW_APP_KEY_UNRESOLVED",
                             "message": f"view_get could not resolve app_key for system view `{view_id}`; keep using the app_key from the parent app context.",
-                        }
+                        },
+                        {
+                            "code": "VIEW_EXPORT_APP_CONTEXT_REQUIRED",
+                            "message": f"view_get supports exporting `{view_id}`, but the export call still needs the parent app context `app_key`.",
+                        },
                     ],
                     "verification": {
                         "view_exists": True,
                         "descriptor_only": True,
+                        "export_route_supported": export_capability["supported"],
+                        "export_permission_verified": export_capability["permission_verified"],
                     },
                     "data": {
                         "app_key": None,
@@ -120,11 +129,13 @@ class ResourceReadTools(ToolBase):
                         "view_type": system_view["view_type"],
                         "visible_columns": [],
                         "analysis_supported": system_view["analysis_supported"],
+                        "export_capability": export_capability,
                     },
                 },
             )
 
         def runner(session_profile, context):
+            raw_view_type = None
             warnings: list[JSONObject] = []
             verification = {
                 "view_exists": True,
@@ -150,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)
@@ -165,6 +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.",
                     }
                 )
+                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,
@@ -186,6 +209,7 @@ class ResourceReadTools(ToolBase):
                         if str(item.get("queTitle") or item.get("title") or "").strip()
                     ],
                     "analysis_supported": _analysis_supported_for_view_type(raw_view_type or None),
+                    "export_capability": export_capability,
                 },
             }
 
@@ -464,6 +488,21 @@ def _lookup_system_view_descriptor(view_id: str) -> dict[str, Any] | None:
     return None
 
 
+def _view_export_capability_payload(*, supported: bool) -> JSONObject:
+    return {
+        "supported": supported,
+        "tool": "record_export_start",
+        "format": "xlsx",
+        "async": True,
+        "requires_app_key": True,
+        "permission_verified": False,
+    }
+
+
+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:

package/src/qingflow_mcp/tools/task_context_tools.py

@@ -1762,6 +1762,7 @@ class TaskContextTools(ToolBase):
                 "apply_time": record.get("apply_time"),
                 "last_update_time": record.get("last_update_time"),
                 "core_fields": self._task_record_core_fields(record.get("answers") or []),
+                "all_fields": self._task_record_all_fields(record.get("answers") or []),
             },
             "available_actions": available_actions,
             "editable_fields": [
@@ -1921,9 +1922,21 @@ class TaskContextTools(ToolBase):
         return None
 
     def _task_record_core_fields(self, answers: Any, *, limit: int = 12) -> dict[str, Any]:
+        return self._task_record_field_map(answers, limit=limit, truncate_text=160)
+
+    def _task_record_all_fields(self, answers: Any) -> dict[str, Any]:
+        return self._task_record_field_map(answers, limit=None, truncate_text=None)
+
+    def _task_record_field_map(
+        self,
+        answers: Any,
+        *,
+        limit: int | None,
+        truncate_text: int | None,
+    ) -> dict[str, Any]:
         if not isinstance(answers, list):
             return {}
-        core_fields: dict[str, Any] = {}
+        field_map: dict[str, Any] = {}
         for answer in answers:
             if not isinstance(answer, dict):
                 continue
@@ -1943,19 +1956,24 @@ class TaskContextTools(ToolBase):
                 value = values[0] if len(values) == 1 else values
             if value in (None, "", []):
                 continue
-            core_fields[str(title)] = self._compact_task_value(value)
-            if len(core_fields) >= limit:
+            field_map[str(title)] = self._compact_task_value(value, truncate_text=truncate_text)
+            if limit is not None and len(field_map) >= limit:
                 break
-        return core_fields
+        return field_map
 
-    def _compact_task_value(self, value: Any) -> Any:
+    def _compact_task_value(self, value: Any, *, truncate_text: int | None = 160) -> Any:
         if isinstance(value, list):
-            return [self._compact_task_value(item) for item in value[:8]]
+            items = [self._compact_task_value(item, truncate_text=truncate_text) for item in value]
+            if truncate_text is not None:
+                return items[:8]
+            return items
         text = re.sub(r"<[^>]+>", " ", str(value))
         text = re.sub(r"\s+", " ", text).strip()
-        if len(text) <= 160:
+        if truncate_text is None or len(text) <= truncate_text:
             return text
-        return text[:157].rstrip() + "..."
+        if truncate_text <= 3:
+            return text[:truncate_text]
+        return text[: truncate_text - 3].rstrip() + "..."
 
     def _compact_task_editable_field(self, field: dict[str, Any], update_schema: dict[str, Any]) -> dict[str, Any]:
         payload_template = update_schema.get("payload_template") if isinstance(update_schema.get("payload_template"), dict) else {}