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

package/src/qingflow_mcp/server_app_user.py

@@ -13,6 +13,7 @@ from .tools.app_tools import AppTools
 from .tools.auth_tools import AuthTools
 from .tools.code_block_tools import CodeBlockTools
 from .tools.directory_tools import DirectoryTools
+from .tools.export_tools import ExportTools
 from .tools.feedback_tools import FeedbackTools
 from .tools.file_tools import FileTools
 from .tools.import_tools import ImportTools
@@ -33,6 +34,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.
+`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
 
@@ -142,10 +144,33 @@ Use `record_code_block_run` when the user wants to execute a form code-block fie
 - Do not modify user-uploaded files unless the user explicitly authorizes repair.
 - If repair is authorized, keep the original file and repair a copy, then run `record_import_verify` again before `record_import_start`.
 
+## Export Path
+
+`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.
+- 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
+  - pass `record_ids` to export selected rows only
+- `record_export_start` / `record_export_direct` also support internal query selection:
+  - pass `where` to resolve matching `record_id` values first
+  - pass `order_by` to keep the internal query and export row order aligned with `record_list`
+  - then run native export as selected rows
+  - `where/order_by` and `record_ids` are mutually exclusive
+- `record_export_start` / `record_export_direct` also support frontend-like column selection:
+  - omit `columns` to export all current-view fields
+  - pass `columns` to export only selected fields, preserving the provided order
+- `include_workflow_log=true` maps to the native workflow-log export switch.
+
 ## Task Workflow Path
 
 `task_list -> task_get -> task_action_execute`
 
+- `task_list` returns task-card summaries keyed by `task_id`.
+- 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 full workflow log history.
 - Task actions operate on `app_key + record_id + workflow_node_id`, not `task_id`.
@@ -184,6 +209,7 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
     workspace = wrap_trimmed_methods(WorkspaceTools(sessions, backend), USER_SERVER_METHOD_MAP)
     file_tools = wrap_trimmed_methods(FileTools(sessions, backend), USER_SERVER_METHOD_MAP)
     imports = wrap_trimmed_methods(ImportTools(sessions, backend), USER_SERVER_METHOD_MAP)
+    exports = wrap_trimmed_methods(ExportTools(sessions, backend), USER_SERVER_METHOD_MAP)
     resources = wrap_trimmed_methods(ResourceReadTools(sessions, backend), USER_SERVER_METHOD_MAP)
     feedback = FeedbackTools(backend, mcp_side="App User MCP")
     code_block_tools = wrap_trimmed_methods(CodeBlockTools(sessions, backend), USER_SERVER_METHOD_MAP)
@@ -214,6 +240,73 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
     def auth_logout(profile: str = DEFAULT_PROFILE, forget_persisted: bool = False) -> dict:
         return auth.auth_logout(profile=profile, forget_persisted=forget_persisted)
 
+    @server.tool()
+    def record_export_start(
+        profile: str = DEFAULT_PROFILE,
+        app_key: str = "",
+        view_id: str = "system:all",
+        columns: list[dict | int] | None = None,
+        where: list[dict] | None = None,
+        order_by: list[dict] | None = None,
+        record_ids: list[str | int] | None = None,
+        include_workflow_log: bool = False,
+    ) -> dict:
+        return exports.record_export_start(
+            profile=profile,
+            app_key=app_key,
+            view_id=view_id,
+            columns=columns or [],
+            where=where or [],
+            order_by=order_by or [],
+            record_ids=record_ids or [],
+            include_workflow_log=include_workflow_log,
+        )
+
+    @server.tool()
+    def record_export_status_get(
+        profile: str = DEFAULT_PROFILE,
+        export_handle: str = "",
+    ) -> dict:
+        return exports.record_export_status_get(profile=profile, export_handle=export_handle)
+
+    @server.tool()
+    def record_export_get(
+        profile: str = DEFAULT_PROFILE,
+        export_handle: str = "",
+        download_to_path: str | None = None,
+    ) -> dict:
+        return exports.record_export_get(
+            profile=profile,
+            export_handle=export_handle,
+            download_to_path=download_to_path,
+        )
+
+    @server.tool()
+    def record_export_direct(
+        profile: str = DEFAULT_PROFILE,
+        app_key: str = "",
+        view_id: str = "system:all",
+        columns: list[dict | int] | None = None,
+        where: list[dict] | None = None,
+        order_by: list[dict] | None = None,
+        record_ids: list[str | int] | None = None,
+        include_workflow_log: bool = False,
+        download_to_path: str | None = None,
+        wait_timeout_seconds: float | None = None,
+    ) -> dict:
+        return exports.record_export_direct(
+            profile=profile,
+            app_key=app_key,
+            view_id=view_id,
+            columns=columns or [],
+            where=where or [],
+            order_by=order_by or [],
+            record_ids=record_ids or [],
+            include_workflow_log=include_workflow_log,
+            download_to_path=download_to_path,
+            wait_timeout_seconds=wait_timeout_seconds,
+        )
+
     @server.tool()
     def workspace_list(
         profile: str = DEFAULT_PROFILE,
@@ -228,6 +321,26 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
             include_external=include_external,
         )
 
+    @server.tool()
+    def workspace_get(
+        profile: str = DEFAULT_PROFILE,
+        ws_id: int | None = None,
+    ) -> dict:
+        return workspace.workspace_get(
+            profile=profile,
+            ws_id=ws_id,
+        )
+
+    @server.tool()
+    def workspace_select(
+        profile: str = DEFAULT_PROFILE,
+        ws_id: int = 0,
+    ) -> dict:
+        return workspace.workspace_select(
+            profile=profile,
+            ws_id=ws_id,
+        )
+
     @server.tool()
     def app_list(profile: str = DEFAULT_PROFILE) -> dict:
         return apps.app_list(profile=profile)

package/src/qingflow_mcp/session_store.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
 import json
+import os
+from collections.abc import Callable
 from dataclasses import asdict, dataclass
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 
 try:
@@ -77,9 +79,15 @@ class SessionStore:
         profiles_path = get_profiles_path() if base_dir is None else Path(base_dir) / "profiles.json"
         self._profiles_path = profiles_path
         self._profiles_path.parent.mkdir(parents=True, exist_ok=True)
+        self._secrets_path = self._profiles_path.parent / "secrets.json"
         self._keyring = keyring_backend if keyring_backend is not None else keyring
         self._memory_sessions: dict[str, BackendSession] = {}
         self._logged_out_profiles: set[str] = set()
+        self._profile_refresher: Callable[[str, SessionProfile | None], bool] | None = None
+        self._refreshing_profiles: set[str] = set()
+
+    def set_profile_refresher(self, refresher: Callable[[str, SessionProfile | None], bool] | None) -> None:
+        self._profile_refresher = refresher
 
     def save_session(
         self,
@@ -146,9 +154,14 @@ class SessionStore:
     def get_profile(self, profile: str) -> SessionProfile | None:
         payload = self._load_profiles()
         raw_profile = payload.get("profiles", {}).get(profile)
-        if not raw_profile:
-            return None
-        return SessionProfile.from_dict(raw_profile)
+        session_profile = SessionProfile.from_dict(raw_profile) if isinstance(raw_profile, dict) else None
+        if profile in self._refreshing_profiles:
+            return session_profile
+        if self._should_refresh_profile(payload, session_profile) and self._refresh_profile(profile, session_profile):
+            payload = self._load_profiles()
+            raw_profile = payload.get("profiles", {}).get(profile)
+            session_profile = SessionProfile.from_dict(raw_profile) if isinstance(raw_profile, dict) else None
+        return session_profile
 
     def get_backend_session(self, profile: str) -> BackendSession | None:
         if profile in self._logged_out_profiles:
@@ -281,8 +294,48 @@ class SessionStore:
     def _load_profiles(self) -> JSONObject:
         if not self._profiles_path.exists():
             return {"profiles": {}}
-        with self._profiles_path.open("r", encoding="utf-8") as handle:
-            return json.load(handle)
+        try:
+            with self._profiles_path.open("r", encoding="utf-8") as handle:
+                payload = json.load(handle)
+        except (OSError, json.JSONDecodeError):
+            return {"profiles": {}}
+        if not isinstance(payload, dict):
+            return {"profiles": {}}
+        profiles = payload.get("profiles")
+        if not isinstance(profiles, dict):
+            payload["profiles"] = {}
+        return payload
+
+    def _should_refresh_profile(self, payload: JSONObject, session_profile: SessionProfile | None) -> bool:
+        if self._profile_refresher is None:
+            return False
+        profiles = payload.get("profiles")
+        if not isinstance(profiles, dict) or not profiles:
+            return True
+        if session_profile is None:
+            return True
+        return self._is_profile_stale(session_profile)
+
+    def _refresh_profile(self, profile: str, session_profile: SessionProfile | None) -> bool:
+        if self._profile_refresher is None:
+            return False
+        self._refreshing_profiles.add(profile)
+        try:
+            return bool(self._profile_refresher(profile, session_profile))
+        except Exception:
+            return False
+        finally:
+            self._refreshing_profiles.discard(profile)
+
+    def _is_profile_stale(self, session_profile: SessionProfile) -> bool:
+        timestamp_text = session_profile.updated_at or session_profile.created_at
+        try:
+            timestamp = datetime.fromisoformat(timestamp_text)
+        except (TypeError, ValueError):
+            return True
+        if timestamp.tzinfo is None:
+            timestamp = timestamp.replace(tzinfo=timezone.utc)
+        return datetime.now(timezone.utc) - timestamp > timedelta(days=7)
 
     def _save_profiles(self, payload: JSONObject) -> None:
         self._profiles_path.parent.mkdir(parents=True, exist_ok=True)
@@ -290,26 +343,78 @@ class SessionStore:
             json.dump(payload, handle, ensure_ascii=False, indent=2)
 
     def _set_secret(self, key: str, value: str) -> bool:
-        if self._keyring is None:
-            return False
+        if self._keyring is not None:
+            try:
+                self._keyring.set_password(KEYRING_SERVICE_NAME, key, value)
+                self._delete_file_secret(key)
+                return True
+            except Exception:
+                pass
+        return self._set_file_secret(key, value)
+
+    def _get_secret(self, key: str) -> str | None:
+        if self._keyring is not None:
+            try:
+                value = self._keyring.get_password(KEYRING_SERVICE_NAME, key)
+            except Exception:
+                value = None
+            if value:
+                return value
+        return self._get_file_secret(key)
+
+    def _delete_secret(self, key: str) -> None:
+        if self._keyring is not None:
+            try:
+                self._keyring.delete_password(KEYRING_SERVICE_NAME, key)
+            except Exception:
+                pass
+        self._delete_file_secret(key)
+
+    def _load_file_secrets(self) -> dict[str, str]:
+        if not self._secrets_path.exists():
+            return {}
+        try:
+            with self._secrets_path.open("r", encoding="utf-8") as handle:
+                payload = json.load(handle)
+        except (OSError, json.JSONDecodeError):
+            return {}
+        if not isinstance(payload, dict):
+            return {}
+        return {str(key): str(value) for key, value in payload.items() if isinstance(value, str)}
+
+    def _save_file_secrets(self, payload: dict[str, str]) -> bool:
+        self._secrets_path.parent.mkdir(parents=True, exist_ok=True)
         try:
-            self._keyring.set_password(KEYRING_SERVICE_NAME, key, value)
+            fd = os.open(self._secrets_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                json.dump(payload, handle, ensure_ascii=False, indent=2)
+            try:
+                os.chmod(self._secrets_path, 0o600)
+            except OSError:
+                pass
             return True
-        except Exception:
+        except OSError:
             return False
 
-    def _get_secret(self, key: str) -> str | None:
-        if self._keyring is None:
-            return None
-        try:
-            return self._keyring.get_password(KEYRING_SERVICE_NAME, key)
-        except Exception:
-            return None
+    def _set_file_secret(self, key: str, value: str) -> bool:
+        payload = self._load_file_secrets()
+        payload[key] = value
+        return self._save_file_secrets(payload)
 
-    def _delete_secret(self, key: str) -> None:
-        if self._keyring is None:
+    def _get_file_secret(self, key: str) -> str | None:
+        return self._load_file_secrets().get(key)
+
+    def _delete_file_secret(self, key: str) -> None:
+        payload = self._load_file_secrets()
+        if key not in payload:
+            return
+        payload.pop(key, None)
+        if payload:
+            self._save_file_secrets(payload)
             return
         try:
-            self._keyring.delete_password(KEYRING_SERVICE_NAME, key)
-        except Exception:
+            self._secrets_path.unlink()
+        except FileNotFoundError:
+            return
+        except OSError:
             return

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

@@ -307,7 +307,7 @@ def build_reference_config(field: dict[str, Any], temp_id: int) -> dict[str, Any
                 "queId": que_id,
                 "queTitle": label,
                 "queType": _normalize_reference_que_type(raw_type) or "2",
-                "queAuth": 1,
+                "queAuth": 3,
                 "ordinal": ordinal,
                 "quoteId": temp_id,
                 "_field_id": field_id,
@@ -320,7 +320,7 @@ def build_reference_config(field: dict[str, Any], temp_id: int) -> dict[str, Any
         auth_ques = []
         for ordinal, field_id in enumerate(auth_field_ids, start=1):
             que_id = auth_field_que_ids[ordinal - 1] if ordinal - 1 < len(auth_field_que_ids) else 0
-            auth_ques.append({"queId": que_id, "queAuth": 1, "_field_id": field_id})
+            auth_ques.append({"queId": que_id, "queAuth": 3, "_field_id": field_id})
     return {
         "referAppKey": "__TARGET_APP_KEY__",
         "referQueId": display_field_que_id,

package/src/qingflow_mcp/solution/executor.py

@@ -857,12 +857,12 @@ class SolutionExecutor:
                 if refer_que_id is None:
                     continue
                 resolved["queId"] = refer_que_id
-                resolved["queAuth"] = int(resolved.get("queAuth", 1))
+                resolved["queAuth"] = int(resolved.get("queAuth", 3))
                 auth_ques.append(resolved)
             if not auth_ques:
                 fallback_que_id = target_meta.get("by_field_id", {}).get(target_field_id)
                 if fallback_que_id is not None:
-                    auth_ques.append({"queId": fallback_que_id, "queAuth": 1})
+                    auth_ques.append({"queId": fallback_que_id, "queAuth": 3})
             reference_config["referAuthQues"] = auth_ques
             reference_config["fieldNameShow"] = bool(reference_config.get("fieldNameShow", True))
             fill_rules = []