@josephyan/qingflow-app-user-mcp 0.2.0-beta.89 → 0.2.0-beta.90

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-user-mcp@0.2.0-beta.89
+npm install @josephyan/qingflow-app-user-mcp@0.2.0-beta.90
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-user-mcp@0.2.0-beta.89 qingflow-app-user-mcp
+npx -y -p @josephyan/qingflow-app-user-mcp@0.2.0-beta.90 qingflow-app-user-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.2.0-beta.89",
+  "version": "0.2.0-beta.90",
   "description": "Operational end-user MCP for Qingflow records, tasks, comments, and directory workflows.",
   "license": "MIT",
   "type": "module",

package/src/qingflow_mcp/tools/record_tools.py

@@ -180,6 +180,16 @@ class AccessibleViewRoute:
     view_type: str | None = None
 
 
+@dataclass(slots=True)
+class RecordContextRouteProbe:
+    route: AccessibleViewRoute
+    answer_list: list[JSONObject] | None
+    used_list_type: int | None
+    readable: bool
+    transport_error: bool
+    error_payload: JSONObject | None
+
+
 @dataclass(slots=True)
 class WorkflowNodeRef:
     workflow_node_id: int
@@ -782,55 +792,29 @@ class RecordTools(ToolBase):
                 index=app_index,
                 question_relations=question_relations,
             )
-            try:
-                current_answers = self._load_record_answers_for_preflight(context, app_key=app_key, apply_id=record_id)
-            except QingflowApiError:
-                return self._record_update_schema_blocked_response(
-                    profile=profile,
-                    ws_id=session_profile.selected_ws_id,
-                    request_route=request_route,
-                    app_key=app_key,
-                    record_id=record_id,
-                    blockers=["CURRENT_RECORD_CONTEXT_UNAVAILABLE"],
-                    warnings=[
-                        "update schema could not load the current record; context-sensitive lookup requirements cannot be derived safely."
-                    ],
-                    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.",
-                    ],
-                    output_profile=normalized_output_profile,
-                    view_probe_summary=[],
-                    ambiguous_fields=[],
-                )
-
             candidate_routes = self._candidate_update_views(profile, context, app_key)
+            probes = self._probe_candidate_record_contexts(
+                context,
+                app_key=app_key,
+                apply_id=record_id,
+                candidate_routes=candidate_routes,
+            )
             probe_summary: list[JSONObject] = []
-            matched_any = False
+            matched_probes: list[RecordContextRouteProbe] = []
             ordered_field_ids: list[int] = []
             field_payloads_by_id: dict[int, JSONObject] = {}
             title_to_field_ids: dict[str, list[int]] = {}
             ws_id = session_profile.selected_ws_id
 
-            for candidate in candidate_routes:
-                matched_record = self._record_matches_accessible_view(
-                    context,
-                    current_answers,
-                    resolved_view=candidate,
-                )
-                candidate_summary: JSONObject = {
-                    "view_id": candidate.view_id,
-                    "name": candidate.name,
-                    "kind": candidate.kind,
-                    "matched_record": matched_record,
-                    "context_complete": True,
-                    "writable_field_titles": [],
-                }
-                if not matched_record:
+            for probe in probes:
+                candidate = probe.route
+                candidate_summary = self._record_context_probe_summary_payload(probe)
+                candidate_summary["writable_field_titles"] = []
+                if not probe.readable:
                     probe_summary.append(candidate_summary)
                     continue
 
-                matched_any = True
+                matched_probes.append(probe)
                 browse_scope = self._build_browse_write_scope(
                     profile,
                     context,
@@ -874,19 +858,39 @@ class RecordTools(ToolBase):
                 candidate_summary["writable_field_titles"] = candidate_titles
                 probe_summary.append(candidate_summary)
 
-            if not matched_any:
+            if not matched_probes:
+                blockers = (
+                    ["CURRENT_RECORD_CONTEXT_UNAVAILABLE"]
+                    if probes and all(probe.transport_error for probe in probes)
+                    else ["NO_MATCHING_ACCESSIBLE_VIEW_FOR_RECORD"]
+                )
+                warnings = (
+                    [
+                        "update schema could not load the current record from any candidate route; context-sensitive lookup requirements cannot be derived safely."
+                    ]
+                    if blockers == ["CURRENT_RECORD_CONTEXT_UNAVAILABLE"]
+                    else []
+                )
+                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 blockers == ["CURRENT_RECORD_CONTEXT_UNAVAILABLE"]
+                    else [
+                        "Check whether this record is still visible in any accessible view for the current profile.",
+                        "Use record_get or record_list to confirm the record still exists in the current workspace.",
+                    ]
+                )
                 return self._record_update_schema_blocked_response(
                     profile=profile,
                     ws_id=ws_id,
                     request_route=request_route,
                     app_key=app_key,
                     record_id=record_id,
-                    blockers=["NO_MATCHING_ACCESSIBLE_VIEW_FOR_RECORD"],
-                    warnings=[],
-                    recommended_next_actions=[
-                        "Check whether this record is still visible in any accessible view for the current profile.",
-                        "Use record_get or record_list to confirm the record still exists in the current workspace.",
-                    ],
+                    blockers=blockers,
+                    warnings=warnings,
+                    recommended_next_actions=recommended_next_actions,
                     output_profile=normalized_output_profile,
                     view_probe_summary=probe_summary,
                     ambiguous_fields=[],
@@ -894,7 +898,10 @@ class RecordTools(ToolBase):
 
             ambiguous_field_ids: set[int] = set()
             ambiguous_fields: list[JSONObject] = []
-            warnings: list[JSONObject] = []
+            warnings: list[JSONObject] = [
+                {"code": "RECORD_CONTEXT_ROUTE_FALLBACK", "message": message}
+                for message in self._record_context_probe_fallback_warnings(probes)
+            ]
             for title, field_ids in title_to_field_ids.items():
                 unique_ids = list(dict.fromkeys(field_ids))
                 if len(unique_ids) <= 1:
@@ -953,6 +960,7 @@ class RecordTools(ToolBase):
             }
             if normalized_output_profile == "verbose":
                 response["view_probe_summary"] = probe_summary
+                response["record_context_probe"] = probe_summary
                 response["ambiguous_fields"] = ambiguous_fields
             return response
 
@@ -2286,9 +2294,15 @@ class RecordTools(ToolBase):
         def runner(session_profile, context):
             request_route = self._request_route_payload(context)
             def build_once(*, effective_force_refresh: bool) -> JSONObject:
-                try:
-                    current_answers = self._load_record_answers_for_preflight(context, app_key=app_key, apply_id=record_id)
-                except QingflowApiError:
+                candidate_routes = self._candidate_update_views(profile, context, app_key)
+                probes = self._probe_candidate_record_contexts(
+                    context,
+                    app_key=app_key,
+                    apply_id=record_id,
+                    candidate_routes=candidate_routes,
+                )
+                matched_probes = [probe for probe in probes if probe.readable]
+                if not matched_probes and probes and all(probe.transport_error for probe in probes):
                     return {
                         "profile": profile,
                         "ws_id": session_profile.selected_ws_id,
@@ -2299,46 +2313,40 @@ class RecordTools(ToolBase):
                             record_id=record_id,
                             blockers=["CURRENT_RECORD_CONTEXT_UNAVAILABLE"],
                             warnings=[
-                                "update preflight could not load the current record; automatic view selection was blocked to avoid resolving lookup fields against a partial patch."
+                                "update preflight could not load the current record from any candidate route; automatic view selection was blocked to avoid resolving lookup fields against a partial patch."
                             ],
                             recommended_next_actions=[
                                 "Retry after the record becomes readable in the current workspace/profile context.",
                                 "Call record_update_schema_get to inspect the overall writable field set for this record after context access is restored.",
                             ],
-                            view_probe_summary=[],
+                            view_probe_summary=[
+                                self._record_context_probe_summary_payload(probe)
+                                for probe in probes
+                            ],
                         ),
                     }
 
-                candidate_routes = self._candidate_update_views(profile, context, app_key)
                 probe_summary: list[JSONObject] = []
-                matched_any = False
                 matched_routes: list[AccessibleViewRoute] = []
+                matched_answers_for_union: list[JSONObject] | None = None
                 first_blocked_plan: JSONObject | None = None
                 first_confirmation_plan: JSONObject | None = None
-
-                for candidate in candidate_routes:
-                    matched_record = self._record_matches_accessible_view(
-                        context,
-                        current_answers,
-                        resolved_view=candidate,
-                    )
-                    if not matched_record:
-                        probe_summary.append(
-                            {
-                                "view_id": candidate.view_id,
-                                "name": candidate.name,
-                                "kind": candidate.kind,
-                                "matched_record": False,
-                                "writable_field_titles": [],
-                                "missing_field_titles": [],
-                                "context_complete": True,
-                                "selected": False,
-                            }
-                        )
+                fallback_warning_messages = self._record_context_probe_fallback_warnings(probes)
+
+                for probe in probes:
+                    candidate = probe.route
+                    candidate_summary = self._record_context_probe_summary_payload(probe)
+                    candidate_summary["writable_field_titles"] = []
+                    candidate_summary["missing_field_titles"] = []
+                    candidate_summary["selected"] = False
+                    if not probe.readable:
+                        probe_summary.append(candidate_summary)
                         continue
 
-                    matched_any = True
+                    current_answers = probe.answer_list or []
                     matched_routes.append(candidate)
+                    if matched_answers_for_union is None:
+                        matched_answers_for_union = current_answers
                     browse_scope = self._build_browse_write_scope(
                         profile,
                         context,
@@ -2394,16 +2402,8 @@ class RecordTools(ToolBase):
                             title = _normalize_optional_text(field_payload.get("que_title"))
                             if title and title not in missing_field_titles:
                                 missing_field_titles.append(title)
-                    candidate_summary: JSONObject = {
-                        "view_id": candidate.view_id,
-                        "name": candidate.name,
-                        "kind": candidate.kind,
-                        "matched_record": True,
-                        "writable_field_titles": candidate_titles,
-                        "missing_field_titles": missing_field_titles,
-                        "context_complete": True,
-                        "selected": False,
-                    }
+                    candidate_summary["writable_field_titles"] = candidate_titles
+                    candidate_summary["missing_field_titles"] = missing_field_titles
                     if plan_data.get("blockers"):
                         confirmation_requests = plan_data.get("confirmation_requests")
                         if (
@@ -2422,8 +2422,26 @@ class RecordTools(ToolBase):
                             view_payload["auto_selected"] = True
                             view_payload["selection_source"] = "first_satisfying_accessible_view"
                             candidate_summary["selected"] = True
+                            validation = plan_data.get("validation")
+                            if isinstance(validation, dict):
+                                warnings = validation.get("warnings")
+                                if not isinstance(warnings, list):
+                                    warnings = []
+                                    validation["warnings"] = warnings
+                                for message in fallback_warning_messages:
+                                    if message not in warnings:
+                                        warnings.append(message)
                             first_confirmation_plan = plan_data
                         elif first_blocked_plan is None:
+                            validation = plan_data.get("validation")
+                            if isinstance(validation, dict):
+                                warnings = validation.get("warnings")
+                                if not isinstance(warnings, list):
+                                    warnings = []
+                                    validation["warnings"] = warnings
+                                for message in fallback_warning_messages:
+                                    if message not in warnings:
+                                        warnings.append(message)
                             first_blocked_plan = plan_data
                         probe_summary.append(candidate_summary)
                         continue
@@ -2439,8 +2457,18 @@ class RecordTools(ToolBase):
                     view_payload["auto_selected"] = True
                     view_payload["selection_source"] = "first_satisfying_accessible_view"
                     candidate_summary["selected"] = True
+                    validation = plan_data.get("validation")
+                    if isinstance(validation, dict):
+                        warnings = validation.get("warnings")
+                        if not isinstance(warnings, list):
+                            warnings = []
+                            validation["warnings"] = warnings
+                        for message in fallback_warning_messages:
+                            if message not in warnings:
+                                warnings.append(message)
                     probe_summary.append(candidate_summary)
                     plan_data["view_probe_summary"] = probe_summary
+                    plan_data["record_context_probe"] = probe_summary
                     return {
                         "profile": profile,
                         "ws_id": session_profile.selected_ws_id,
@@ -2449,7 +2477,7 @@ class RecordTools(ToolBase):
                         "data": plan_data,
                     }
 
-                if not matched_any:
+                if not matched_probes:
                     blocked_data = self._build_auto_view_blocked_preflight_data(
                         app_key=app_key,
                         record_id=record_id,
@@ -2471,6 +2499,7 @@ class RecordTools(ToolBase):
 
                 if first_confirmation_plan is not None:
                     first_confirmation_plan["view_probe_summary"] = probe_summary
+                    first_confirmation_plan["record_context_probe"] = probe_summary
                     return {
                         "profile": profile,
                         "ws_id": session_profile.selected_ws_id,
@@ -2485,12 +2514,22 @@ class RecordTools(ToolBase):
                     app_key=app_key,
                     record_id=record_id,
                     fields=fields,
-                    current_answers=current_answers,
+                    current_answers=matched_answers_for_union or [],
                     matched_routes=matched_routes,
                     force_refresh_form=effective_force_refresh,
                 )
                 if union_plan is not None:
+                    validation = union_plan.get("validation")
+                    if isinstance(validation, dict):
+                        warnings = validation.get("warnings")
+                        if not isinstance(warnings, list):
+                            warnings = []
+                            validation["warnings"] = warnings
+                        for message in fallback_warning_messages:
+                            if message not in warnings:
+                                warnings.append(message)
                     union_plan["view_probe_summary"] = probe_summary
+                    union_plan["record_context_probe"] = probe_summary
                     return {
                         "profile": profile,
                         "ws_id": session_profile.selected_ws_id,
@@ -2785,6 +2824,161 @@ class RecordTools(ToolBase):
             )
         return candidates
 
+    def _route_view_key(self, resolved_view: AccessibleViewRoute) -> str | None:
+        if resolved_view.view_selection is not None:
+            view_key = _normalize_optional_text(resolved_view.view_selection.view_key)
+            if view_key:
+                return view_key
+        if resolved_view.kind == "custom" and resolved_view.view_id.startswith("custom:"):
+            view_key = resolved_view.view_id.split(":", 1)[1].strip()
+            return view_key or None
+        return None
+
+    def _record_context_route_error_payload(self, error: QingflowApiError) -> JSONObject:
+        payload: JSONObject = {"message": error.message}
+        if error.category:
+            payload["category"] = error.category
+        if error.backend_code is not None:
+            payload["backend_code"] = error.backend_code
+        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}:
+            return True
+        if error.http_status == 404:
+            return True
+        return False
+
+    def _load_record_answers_for_accessible_route(
+        self,
+        context,  # type: ignore[no-untyped-def]
+        *,
+        app_key: str,
+        apply_id: int,
+        resolved_view: AccessibleViewRoute,
+    ) -> tuple[list[JSONObject], int | None]:
+        if resolved_view.kind == "custom":
+            view_key = self._route_view_key(resolved_view)
+            if not view_key:
+                raise_tool_error(
+                    QingflowApiError.config_error(
+                        f"cannot resolve custom view route for '{resolved_view.view_id}'"
+                    )
+                )
+            record = self.backend.request(
+                "GET",
+                context,
+                f"/view/{view_key}/apply/{apply_id}",
+            )
+            used_list_type = None
+        else:
+            used_list_type = resolved_view.list_type if resolved_view.list_type is not None else DEFAULT_RECORD_LIST_TYPE
+            record = self.backend.request(
+                "GET",
+                context,
+                f"/app/{app_key}/apply/{apply_id}",
+                params={"role": 1, "listType": used_list_type},
+            )
+        answers = record.get("answers") if isinstance(record, dict) else None
+        normalized_answers = [item for item in answers if isinstance(item, dict)] if isinstance(answers, list) else []
+        return normalized_answers, used_list_type
+
+    def _probe_record_context_route(
+        self,
+        context,  # type: ignore[no-untyped-def]
+        *,
+        app_key: str,
+        apply_id: int,
+        resolved_view: AccessibleViewRoute,
+    ) -> RecordContextRouteProbe:
+        try:
+            answer_list, used_list_type = self._load_record_answers_for_accessible_route(
+                context,
+                app_key=app_key,
+                apply_id=apply_id,
+                resolved_view=resolved_view,
+            )
+            return RecordContextRouteProbe(
+                route=resolved_view,
+                answer_list=answer_list,
+                used_list_type=used_list_type,
+                readable=True,
+                transport_error=False,
+                error_payload=None,
+            )
+        except QingflowApiError as exc:
+            return RecordContextRouteProbe(
+                route=resolved_view,
+                answer_list=None,
+                used_list_type=resolved_view.list_type if resolved_view.kind == "system" else None,
+                readable=False,
+                transport_error=not self._is_record_context_route_miss(exc),
+                error_payload=self._record_context_route_error_payload(exc),
+            )
+
+    def _probe_candidate_record_contexts(
+        self,
+        context,  # type: ignore[no-untyped-def]
+        *,
+        app_key: str,
+        apply_id: int,
+        candidate_routes: list[AccessibleViewRoute],
+    ) -> list[RecordContextRouteProbe]:
+        return [
+            self._probe_record_context_route(
+                context,
+                app_key=app_key,
+                apply_id=apply_id,
+                resolved_view=candidate,
+            )
+            for candidate in candidate_routes
+        ]
+
+    def _record_context_probe_summary_payload(self, probe: RecordContextRouteProbe) -> JSONObject:
+        payload: JSONObject = {
+            "view_id": probe.route.view_id,
+            "name": probe.route.name,
+            "kind": probe.route.kind,
+            "matched_record": probe.readable,
+            "readable": probe.readable,
+            "context_complete": probe.readable,
+            "used_list_type": probe.used_list_type,
+        }
+        if probe.error_payload is not None:
+            payload["error"] = probe.error_payload
+            payload["transport_error"] = probe.transport_error
+        return payload
+
+    def _record_context_probe_fallback_warnings(
+        self,
+        probes: list[RecordContextRouteProbe],
+    ) -> list[str]:
+        matched_probes = [probe for probe in probes if probe.readable]
+        if not matched_probes:
+            return []
+        if any(
+            probe.route.kind == "system" and probe.used_list_type == DEFAULT_RECORD_LIST_TYPE
+            for probe in matched_probes
+        ):
+            return []
+        first_probe = matched_probes[0]
+        if first_probe.route.kind == "custom":
+            return [
+                "current record context was not accessible via listType="
+                f"{DEFAULT_RECORD_LIST_TYPE}; preflight resolved it via custom view "
+                f"'{first_probe.route.name}'."
+            ]
+        used_list_type = first_probe.used_list_type
+        if used_list_type is None:
+            return []
+        return [
+            "current record context was not accessible via listType="
+            f"{DEFAULT_RECORD_LIST_TYPE}; preflight resolved it via listType={used_list_type} "
+            f"({get_record_list_type_label(used_list_type)})."
+        ]
+
     def _record_matches_accessible_view(
         self,
         context,  # type: ignore[no-untyped-def]
@@ -5276,7 +5470,19 @@ class RecordTools(ToolBase):
                 existing_answers_loaded = True
             else:
                 try:
-                    existing_answers_for_update = self._load_record_answers_for_preflight(context, app_key=app_key, apply_id=apply_id)
+                    if resolved_view is not None:
+                        existing_answers_for_update, _used_list_type = self._load_record_answers_for_accessible_route(
+                            context,
+                            app_key=app_key,
+                            apply_id=apply_id,
+                            resolved_view=resolved_view,
+                        )
+                    else:
+                        existing_answers_for_update = self._load_record_answers_for_preflight(
+                            context,
+                            app_key=app_key,
+                            apply_id=apply_id,
+                        )
                     existing_answers_loaded = True
                 except QingflowApiError:
                     validation_warnings.append(