@josephyan/qingflow-cli 1.1.3 → 1.1.5

package/src/qingflow_mcp/tools/task_tools.py

@@ -1,11 +1,12 @@
 from __future__ import annotations
 
+import json
 from typing import Any
 
 from mcp.server.fastmcp import FastMCP
 
 from ..config import DEFAULT_PROFILE
-from ..errors import QingflowApiError, raise_tool_error
+from ..errors import QingflowApiError, backend_code_value_int, message_looks_like_invalid_token, raise_tool_error
 from ..list_type_labels import get_record_list_type_label, get_task_type_label
 from .base import ToolBase, tool_cn_name
 
@@ -150,7 +151,17 @@ class TaskTools(ToolBase):
         app_key: str | None,
     ) -> dict[str, Any]:
         """执行任务相关逻辑。"""
-        raw = self.task_statistics(profile=profile, app_key=app_key)
+        try:
+            raw = self.task_statistics(profile=profile, app_key=app_key)
+        except RuntimeError as exc:
+            if not _is_optional_task_runtime_error(exc):
+                raise
+            return self._runtime_error_as_auxiliary_result(
+                exc,
+                error_code="TASK_SUMMARY_UNAVAILABLE",
+                selection={"app_key": app_key},
+                fallback_hint="Use task list/get directly; task summary is an auxiliary statistics entrypoint.",
+            )
         statistics = raw.get("statistics", {})
         summary = self._normalize_task_summary_payload(statistics)
         return {
@@ -243,34 +254,51 @@ class TaskTools(ToolBase):
         if limit <= 0:
             raise_tool_error(QingflowApiError.config_error("limit must be positive"))
 
-        if dimension == "worksheet":
-            raw = self.task_worksheet_statistics(
-                profile=profile,
-                type=normalized_type,
-                worksheet_name=query,
-                page_num=1,
-                page_size=max(limit, 20),
-            )
-            source = raw.get("page", {})
-        elif app_key:
-            raw = self.task_node_statistics(
-                profile=profile,
-                app_key=app_key,
-                type=normalized_type,
-                search_key=query,
-            )
-            source = raw.get("nodes", {})
-        else:
-            raw = self.task_workflow_nodes(
-                profile=profile,
-                type=normalized_type,
-                status=str(normalized_status),
-                app_key_list=None,
-                search_key=query,
-                page_num=1,
-                page_size=max(limit, 20),
+        try:
+            if dimension == "worksheet":
+                raw = self.task_worksheet_statistics(
+                    profile=profile,
+                    type=normalized_type,
+                    worksheet_name=query,
+                    page_num=1,
+                    page_size=max(limit, 20),
+                )
+                source = raw.get("page", {})
+            elif app_key:
+                raw = self.task_node_statistics(
+                    profile=profile,
+                    app_key=app_key,
+                    type=normalized_type,
+                    search_key=query,
+                )
+                source = raw.get("nodes", {})
+            else:
+                raw = self.task_workflow_nodes(
+                    profile=profile,
+                    type=normalized_type,
+                    status=str(normalized_status),
+                    app_key_list=None,
+                    search_key=query,
+                    page_num=1,
+                    page_size=max(limit, 20),
+                )
+                source = raw.get("page", {})
+        except RuntimeError as exc:
+            if not _is_optional_task_runtime_error(exc):
+                raise
+            return self._runtime_error_as_auxiliary_result(
+                exc,
+                error_code="TASK_FACETS_UNAVAILABLE",
+                selection={
+                    "task_box": task_box,
+                    "flow_status": flow_status,
+                    "dimension": dimension,
+                    "app_key": app_key,
+                    "query": query,
+                    "limit": limit,
+                },
+                fallback_hint="Use task list/get directly; task facets are an auxiliary grouping entrypoint.",
             )
-            source = raw.get("page", {})
 
         groups = self._normalize_task_facets(source)
         rows_truncated = len(groups) > limit
@@ -824,6 +852,46 @@ class TaskTools(ToolBase):
             groups.append({"key": key if key is not None else label, "label": label, "count": count})
         return groups
 
+    def _runtime_error_as_auxiliary_result(
+        self,
+        error: RuntimeError,
+        *,
+        error_code: str,
+        selection: dict[str, Any],
+        fallback_hint: str,
+    ) -> dict[str, Any]:
+        """Return a structured failure for optional task discovery helpers."""
+        try:
+            payload = json.loads(str(error))
+        except json.JSONDecodeError:
+            payload = {"message": str(error)}
+        details = payload.get("details") if isinstance(payload.get("details"), dict) else {}
+        warning: dict[str, Any] = {
+            "code": error_code,
+            "message": fallback_hint,
+        }
+        for key in ("category", "backend_code", "request_id", "http_status"):
+            if payload.get(key) is not None:
+                warning[key] = payload.get(key)
+        response: dict[str, Any] = {
+            "ok": False,
+            "status": "failed",
+            "error_code": details.get("error_code") or error_code,
+            "message": payload.get("message") or str(error),
+            "warnings": [warning],
+            "output_profile": "normal",
+            "data": {
+                "selection": selection,
+                "fallback_hint": fallback_hint,
+            },
+        }
+        for key in ("category", "backend_code", "request_id", "http_status"):
+            if payload.get(key) is not None:
+                response[key] = payload.get(key)
+        if details:
+            response["details"] = details
+        return response
+
     def _public_task_action_response(
         self,
         raw: dict[str, Any],
@@ -859,6 +927,22 @@ class TaskTools(ToolBase):
         }
 
 
+def _is_optional_task_runtime_error(error: RuntimeError) -> bool:
+    try:
+        payload = json.loads(str(error))
+    except json.JSONDecodeError:
+        return False
+    if not isinstance(payload, dict):
+        return False
+    if str(payload.get("category") or "").strip().lower() == "auth":
+        return False
+    if message_looks_like_invalid_token(payload.get("message")):
+        return False
+    if backend_code_value_int(payload.get("http_status")) == 401:
+        return False
+    return backend_code_value_int(payload.get("backend_code")) in {40002, 40027, 404} or backend_code_value_int(payload.get("http_status")) == 404
+
+
 def _task_page_items(payload: Any) -> list[Any]:
     if isinstance(payload, list):
         return payload

package/src/qingflow_mcp/tools/view_tools.py

@@ -3,8 +3,9 @@ from __future__ import annotations
 from mcp.server.fastmcp import FastMCP
 
 from ..config import DEFAULT_PROFILE
-from ..errors import QingflowApiError, raise_tool_error
+from ..errors import QingflowApiError, backend_code_int, is_auth_like_error, raise_tool_error
 from ..json_types import JSONObject, JSONValue
+from ..list_type_labels import SYSTEM_VIEW_DEFINITIONS
 from .base import ToolBase, tool_cn_name
 
 
@@ -60,7 +61,31 @@ class ViewTools(ToolBase):
     def view_list(self, *, profile: str, app_key: str) -> JSONObject:
         """执行视图相关逻辑。"""
         self._require_app_key(app_key)
-        return self._request(profile, "GET", f"/app/{app_key}/view/viewList", app_key=app_key)
+
+        def runner(session_profile, context):
+            warnings: list[JSONObject] = []
+            verification: JSONObject = {"custom_views_loaded": True, "system_view_fallback_used": False}
+            try:
+                result = self.backend.request("GET", context, f"/app/{app_key}/view/viewList")
+                return {"profile": profile, "ws_id": session_profile.selected_ws_id, "app_key": app_key, "result": result}
+            except QingflowApiError as exc:
+                if not _is_optional_view_list_error(exc):
+                    raise
+                items, probe_warnings = self._resolve_accessible_system_views(context, app_key)
+                warnings.extend(probe_warnings)
+                warnings.append(_view_list_fallback_warning("VIEW_LIST_UNAVAILABLE", exc))
+                verification = {"custom_views_loaded": False, "system_view_fallback_used": True}
+                return {
+                    "profile": profile,
+                    "ws_id": session_profile.selected_ws_id,
+                    "app_key": app_key,
+                    "result": items,
+                    "items": items,
+                    "warnings": warnings,
+                    "verification": verification,
+                }
+
+        return self._run(profile, runner)
 
     @tool_cn_name("视图列表（扁平）")
     def view_list_flat(self, *, profile: str, app_key: str) -> JSONObject:
@@ -107,7 +132,40 @@ class ViewTools(ToolBase):
         """执行视图相关逻辑。"""
         self._require_viewgraph_key(viewgraph_key)
         params = {"pass": passcode} if passcode else None
-        return self._request(profile, "GET", f"/view/{viewgraph_key}/viewConfig/baseInfo", viewgraph_key=viewgraph_key, params=params)
+        def runner(session_profile, context):
+            warnings: list[JSONObject] = []
+            verification: JSONObject = {"base_info_verified": True, "fallback_config_used": False}
+            try:
+                result = self.backend.request("GET", context, f"/view/{viewgraph_key}/viewConfig/baseInfo", params=params)
+            except QingflowApiError as error:
+                if not _is_optional_view_list_error(error):
+                    raise
+                result = self.backend.request("GET", context, f"/view/{viewgraph_key}/viewConfig")
+                verification["base_info_verified"] = False
+                verification["fallback_config_used"] = True
+                warning: JSONObject = {
+                    "code": "VIEW_BASE_INFO_UNAVAILABLE",
+                    "message": "view_get_base_info used viewConfig because view baseInfo is unavailable in this permission context.",
+                }
+                if error.backend_code is not None:
+                    warning["backend_code"] = error.backend_code
+                if error.http_status is not None:
+                    warning["http_status"] = error.http_status
+                if error.request_id is not None:
+                    warning["request_id"] = error.request_id
+                if error.details:
+                    warning["details"] = error.details
+                warnings.append(warning)
+            return {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "viewgraph_key": viewgraph_key,
+                "result": result,
+                "warnings": warnings,
+                "verification": verification,
+            }
+
+        return self._run(profile, runner)
 
     @tool_cn_name("更新视图配置")
     def view_update(self, *, profile: str, viewgraph_key: str, payload: JSONObject) -> JSONObject:
@@ -303,6 +361,34 @@ class ViewTools(ToolBase):
         if value <= 0:
             raise_tool_error(QingflowApiError.config_error(f"{field_name} must be positive"))
 
+    def _resolve_accessible_system_views(self, context, app_key: str) -> tuple[list[JSONObject], list[JSONObject]]:
+        items: list[JSONObject] = []
+        warnings: list[JSONObject] = []
+        for view_id, list_type, name in SYSTEM_VIEW_DEFINITIONS:
+            try:
+                self.backend.request(
+                    "POST",
+                    context,
+                    f"/app/{app_key}/apply/filter",
+                    json_body={"type": list_type, "pageNum": 1, "pageSize": 1},
+                )
+            except QingflowApiError as exc:
+                if _is_optional_view_list_error(exc):
+                    continue
+                raise
+            items.append(
+                {
+                    "view_id": view_id,
+                    "viewId": view_id,
+                    "viewName": name,
+                    "name": name,
+                    "kind": "system",
+                    "list_type": list_type,
+                    "analysis_supported": True,
+                }
+            )
+        return items, warnings
+
     def _normalize_reorder_payload(self, payload: list[JSONObject]) -> list[JSONObject]:
         """执行内部辅助逻辑。"""
         first_item = payload[0]
@@ -333,3 +419,20 @@ class ViewTools(ToolBase):
         if not view_keys:
             raise_tool_error(QingflowApiError.config_error("payload must include viewgraphKey/viewKey or ordinalType/viewKeyList"))
         return [{"ordinalType": "FIXED_VIEW_LIST", "viewKeyList": view_keys}]
+
+
+def _is_optional_view_list_error(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    backend_code = backend_code_int(error)
+    return backend_code in {40002, 40027, 404} or error.http_status == 404
+
+
+def _view_list_fallback_warning(code: str, error: QingflowApiError) -> JSONObject:
+    return {
+        "code": code,
+        "message": "custom view list is unavailable; returned accessible system views instead",
+        "backend_code": error.backend_code,
+        "http_status": error.http_status,
+        "request_id": error.request_id,
+    }

package/src/qingflow_mcp/tools/workflow_tools.py

@@ -14,13 +14,25 @@ class WorkflowTools(ToolBase):
 
     类型：流程配置工具。
     主要职责：
-    1. 支持流程运行时校验与调试辅助能力；
-    2. 保留 legacy 节点写路径供内部/测试直接调用（非 MCP 公开）。
-    设计期流程配置读取统一走 WorkflowSpec（app_flow_get / GET /api/workflow/spec）。
+    1. 查询流程节点与流程图配置；
+    2. 读取与更新流程规则；
+    3. 支持流程发布与流程调试辅助能力。
     """
 
     def register(self, mcp: FastMCP) -> None:
         """注册当前工具到 MCP 服务。"""
+        @mcp.tool()
+        def workflow_list_nodes(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
+            return self.workflow_list_nodes(profile=profile, app_key=app_key)
+
+        @mcp.tool()
+        def workflow_get_node_detail(profile: str = DEFAULT_PROFILE, app_key: str = "", audit_node_id: int = 0) -> JSONObject:
+            return self.workflow_get_node_detail(profile=profile, app_key=app_key, audit_node_id=audit_node_id)
+
+        @mcp.tool()
+        def workflow_get_global_settings(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
+            return self.workflow_get_global_settings(profile=profile, app_key=app_key)
+
         @mcp.tool()
         def workflow_get_future_nodes(profile: str = DEFAULT_PROFILE, app_key: str = "", apply_id: int = 0) -> JSONObject:
             return self.workflow_get_future_nodes(profile=profile, app_key=app_key, apply_id=apply_id)
@@ -41,6 +53,22 @@ class WorkflowTools(ToolBase):
                 audit_node_id=audit_node_id,
             )
 
+        @mcp.tool()
+        def workflow_get_qsource_active(profile: str = DEFAULT_PROFILE, app_key: str = "", qsource_id: int = 0) -> JSONObject:
+            return self.workflow_get_qsource_active(profile=profile, app_key=app_key, qsource_id=qsource_id)
+
+        @mcp.tool()
+        def workflow_get_qsource_passive(profile: str = DEFAULT_PROFILE, app_key: str = "", qsource_id: int = 0) -> JSONObject:
+            return self.workflow_get_qsource_passive(profile=profile, app_key=app_key, qsource_id=qsource_id)
+
+        @mcp.tool()
+        def workflow_get_editable_question_ids(profile: str = DEFAULT_PROFILE, app_key: str = "", audit_node_id: int = 0) -> JSONObject:
+            return self.workflow_get_editable_question_ids(profile=profile, app_key=app_key, audit_node_id=audit_node_id)
+
+        @mcp.tool()
+        def workflow_get_print_nodes(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
+            return self.workflow_get_print_nodes(profile=profile, app_key=app_key)
+
     @tool_cn_name("流程节点列表")
     def workflow_list_nodes(self, *, profile: str, app_key: str) -> JSONObject:
         """执行流程相关逻辑。"""
@@ -323,7 +351,23 @@ class WorkflowTools(ToolBase):
                 for candidate_path in paths:
                     try:
                         result = self.backend.request("POST", call_context, candidate_path, json_body=json_body)
-                        response: JSONObject = {"profile": profile, "ws_id": session_profile.selected_ws_id, "result": result}
+                        fallback_applied = candidate_path != path or call_context is not context
+                        response: JSONObject = {
+                            "profile": profile,
+                            "ws_id": session_profile.selected_ws_id,
+                            "result": result,
+                            "request_path": candidate_path,
+                            "requested_path": path,
+                            "fallback_applied": fallback_applied,
+                            "qf_version_source": (
+                                call_context.qf_version_source
+                                or ("context" if call_context.qf_version else "unset")
+                            ),
+                            "verification": {
+                                "primary_path_used": candidate_path == path,
+                                "qf_version_used": call_context.qf_version is not None,
+                            },
+                        }
                         response.update(extra)
                         if risk_operation and risk_target:
                             return self._attach_human_review_notice(response, operation=risk_operation, target=risk_target)

package/src/qingflow_mcp/tools/workspace_tools.py

@@ -6,10 +6,13 @@ from mcp.server.fastmcp import FastMCP
 
 from ..backend_client import BackendRequestContext
 from ..config import DEFAULT_PROFILE
-from ..errors import QingflowApiError, raise_tool_error
+from ..errors import QingflowApiError, backend_code_int, is_auth_like_error, raise_tool_error
 from .base import ToolBase, tool_cn_name
 
 
+_WORKSPACE_DETAIL_WARNING_KEY = "_qingflow_workspace_detail_warning"
+
+
 class WorkspaceTools(ToolBase):
     """工作区工具（中文名：工作区与插件管理）。
 
@@ -91,10 +94,14 @@ class WorkspaceTools(ToolBase):
             normalized = result if isinstance(result, dict) else {"list": result if isinstance(result, list) else []}
             workspace_list = normalized.get("list") if isinstance(normalized.get("list"), list) else []
             selected_ws_id = _.selected_ws_id if _ is not None else None
+            warnings: list[dict[str, Any]] = []
             if selected_ws_id and not any(isinstance(item, dict) and item.get("wsId") == selected_ws_id for item in workspace_list):
                 try:
                     selected_workspace = self.backend.request("GET", context, f"/user/workspace/{selected_ws_id}")
-                except QingflowApiError:
+                except QingflowApiError as exc:
+                    if not _is_optional_workspace_detail_error(exc):
+                        raise
+                    warnings.append(_workspace_detail_fallback_warning(exc, ws_id=selected_ws_id))
                     selected_workspace = {
                         "wsId": selected_ws_id,
                         "workspaceName": _.selected_ws_name if _ is not None else None,
@@ -109,6 +116,14 @@ class WorkspaceTools(ToolBase):
                 "profile": profile,
                 "include_external": include_external,
                 "page": normalized,
+                "warnings": warnings,
+                "verification": {
+                    "selected_workspace_detail_verified": not warnings,
+                    "selected_workspace_included": bool(
+                        selected_ws_id
+                        and any(isinstance(item, dict) and item.get("wsId") == selected_ws_id for item in workspace_list)
+                    ),
+                },
             }
 
         return self._run(profile, runner, require_workspace=False)
@@ -127,6 +142,7 @@ class WorkspaceTools(ToolBase):
             if target_ws_id is None or target_ws_id <= 0:
                 raise_tool_error(QingflowApiError.workspace_not_selected(profile))
             workspace = self._fetch_workspace_with_fallback(context, ws_id=target_ws_id)
+            workspace, warnings = _strip_workspace_detail_warning(workspace)
             system_version = self._workspace_system_version(workspace)
             return {
                 "profile": profile,
@@ -134,6 +150,11 @@ class WorkspaceTools(ToolBase):
                 "qf_version": system_version,
                 "qf_version_source": "workspace_system_version" if system_version else "unverified",
                 "workspace": workspace,
+                "warnings": warnings,
+                "verification": {
+                    "workspace_detail_verified": not warnings,
+                    "workspace_list_fallback_used": bool(warnings),
+                },
             }
 
         return self._run(profile, runner, require_workspace=False)
@@ -151,6 +172,7 @@ class WorkspaceTools(ToolBase):
 
         def runner(_, context):
             workspace = self._fetch_workspace_with_fallback(context, ws_id=ws_id)
+            workspace, warnings = _strip_workspace_detail_warning(workspace)
             workspace_name = str(workspace.get("workspaceName") or workspace.get("wsName") or workspace.get("remark") or "").strip() or None
             selected = self.sessions.select_workspace(profile, ws_id=ws_id, ws_name=workspace_name)
             system_version = self._workspace_system_version(workspace)
@@ -171,6 +193,11 @@ class WorkspaceTools(ToolBase):
                     "ws_id": selected.selected_ws_id,
                     "workspace_name": selected.selected_ws_name,
                 },
+                "warnings": warnings,
+                "verification": {
+                    "workspace_detail_verified": not warnings,
+                    "workspace_list_fallback_used": bool(warnings),
+                },
             }
 
         return self._run(profile, runner, require_workspace=False)
@@ -212,7 +239,15 @@ class WorkspaceTools(ToolBase):
         *,
         ws_id: int,
     ) -> dict[str, Any]:
-        workspace = self.backend.request("GET", context, f"/user/workspace/{ws_id}")
+        try:
+            workspace = self.backend.request("GET", context, f"/user/workspace/{ws_id}")
+        except QingflowApiError as error:
+            if not _is_optional_workspace_detail_error(error):
+                raise
+            fallback = self._fetch_workspace_from_list(context, ws_id=ws_id)
+            if isinstance(fallback, dict):
+                return _with_workspace_detail_warning(fallback, error, ws_id=ws_id)
+            raise
         if not isinstance(workspace, dict):
             raise_tool_error(QingflowApiError(category="workspace", message=f"Workspace {ws_id} is not accessible"))
         if self._workspace_needs_list_fallback(workspace):
@@ -264,3 +299,36 @@ class WorkspaceTools(ToolBase):
             return None
         normalized = str(value).strip()
         return normalized or None
+
+
+def _is_optional_workspace_detail_error(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    backend_code = backend_code_int(error)
+    return backend_code in {40002, 40027, 404, 59004} or error.http_status == 404
+
+
+def _with_workspace_detail_warning(workspace: dict[str, Any], error: QingflowApiError, *, ws_id: int) -> dict[str, Any]:
+    enriched = dict(workspace)
+    enriched[_WORKSPACE_DETAIL_WARNING_KEY] = _workspace_detail_fallback_warning(error, ws_id=ws_id)
+    return enriched
+
+
+def _strip_workspace_detail_warning(workspace: dict[str, Any]) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    public_workspace = dict(workspace)
+    warning = public_workspace.pop(_WORKSPACE_DETAIL_WARNING_KEY, None)
+    warnings = [warning] if isinstance(warning, dict) else []
+    return public_workspace, warnings
+
+
+def _workspace_detail_fallback_warning(error: QingflowApiError, *, ws_id: int) -> dict[str, Any]:
+    return {
+        "code": "WORKSPACE_DETAIL_UNAVAILABLE",
+        "message": (
+            f"workspace detail route for ws_id {ws_id} was unavailable; "
+            "the tool used the visible workspace list as fallback."
+        ),
+        "backend_code": error.backend_code,
+        "http_status": error.http_status,
+        "request_id": error.request_id,
+    }