@josephyan/qingflow-app-builder-mcp 1.1.25 → 1.1.26

package/src/qingflow_mcp/tools/resource_read_tools.py

@@ -3,13 +3,13 @@ from __future__ import annotations
 from copy import deepcopy
 from typing import Any
 
-from ..errors import QingflowApiError, backend_code_int, is_auth_like_error, raise_tool_error
+from ..errors import QingflowApiError, raise_tool_error
 from ..json_types import JSONObject
 from ..list_type_labels import SYSTEM_VIEW_DEFINITIONS
 from ..solution.compiler.icon_utils import workspace_icon_config
 from .app_tools import _analysis_supported_for_view_type
 from .base import ToolBase, tool_cn_name
-from .qingbi_report_tools import QingbiReportTools, _coerce_tool_error
+from .qingbi_report_tools import QingbiReportTools
 
 
 class ResourceReadTools(ToolBase):
@@ -141,60 +141,21 @@ class ResourceReadTools(ToolBase):
             warnings: list[JSONObject] = []
             verification = {
                 "view_exists": True,
-                "config_verified": True,
-                "base_info_verified": True,
                 "questions_verified": True,
             }
-            try:
-                config = self.backend.request("GET", context, f"/view/{view_key}/viewConfig")
-                if not isinstance(config, dict):
-                    config = {}
-            except QingflowApiError as error:
-                if not _is_optional_view_config_error(error):
-                    raise
-                config = {}
-                verification["config_verified"] = False
-                warnings.append(
-                    {
-                        "code": "VIEW_CONFIG_UNAVAILABLE",
-                        "message": "view_get used baseInfo because viewConfig is unavailable for this user.",
-                        "backend_code": error.backend_code,
-                        "http_status": error.http_status,
-                        "request_id": error.request_id,
-                    }
-                )
-            try:
-                base_info = self.backend.request("GET", context, f"/view/{view_key}/viewConfig/baseInfo")
-            except QingflowApiError as error:
-                if not _is_optional_view_base_error(error):
-                    raise
-                base_info = {}
-                verification["base_info_verified"] = False
-                warnings.append(
-                    {
-                        "code": "VIEW_BASE_INFO_UNAVAILABLE",
-                        "message": "view_get used viewConfig because view baseInfo is unavailable for this user.",
-                        "backend_code": error.backend_code,
-                        "http_status": error.http_status,
-                        "request_id": error.request_id,
-                    }
-                )
+            config = self.backend.request("GET", context, f"/view/{view_key}/viewConfig")
+            base_info = self.backend.request("GET", context, f"/view/{view_key}/viewConfig/baseInfo")
             questions: list[dict[str, Any]] = []
             try:
                 questions_payload = self.backend.request("GET", context, f"/view/{view_key}/question")
                 if isinstance(questions_payload, list):
                     questions = [deepcopy(item) for item in questions_payload if isinstance(item, dict)]
-            except QingflowApiError as error:
-                if not _is_optional_view_question_error(error):
-                    raise
+            except QingflowApiError:
                 verification["questions_verified"] = False
                 warnings.append(
                     {
                         "code": "VIEW_QUESTIONS_UNAVAILABLE",
                         "message": "view_get could not load visible columns because question readback is unavailable.",
-                        "backend_code": error.backend_code,
-                        "http_status": error.http_status,
-                        "request_id": error.request_id,
                     }
                 )
 
@@ -262,32 +223,13 @@ class ResourceReadTools(ToolBase):
         self._require_chart_id(chart_id)
 
         def runner(session_profile, _context):
+            base = self.charts.qingbi_report_get_base(profile=profile, chart_id=chart_id).get("result") or {}
             warnings: list[JSONObject] = []
             verification = {
                 "chart_exists": True,
-                "chart_base_loaded": False,
                 "chart_data_loaded": False,
                 "chart_config_loaded": False,
             }
-            transport_errors: list[JSONObject] = []
-            base: dict[str, Any] = {}
-            try:
-                base_result = self.charts.qingbi_report_get_base(profile=profile, chart_id=chart_id).get("result") or {}
-                if isinstance(base_result, dict):
-                    base = deepcopy(base_result)
-                    verification["chart_base_loaded"] = True
-            except (QingflowApiError, RuntimeError) as error:
-                api_error = _coerce_tool_error(error)
-                if api_error is None or not _is_optional_chart_base_error(api_error):
-                    raise
-                transport_errors.append(_transport_error_payload(stage="base_info", error=api_error))
-                warnings.append(
-                    {
-                        "code": "CHART_BASE_INFO_UNAVAILABLE",
-                        "message": "chart_get could not load chart base info; continuing with chart data when available.",
-                        **_transport_warning_fields(api_error),
-                    }
-                )
             data: Any = None
             data_config: dict[str, Any] = {}
             try:
@@ -297,54 +239,23 @@ class ResourceReadTools(ToolBase):
                     data_config = deepcopy(data.get("config"))
                     verification["chart_config_loaded"] = True
             except (QingflowApiError, RuntimeError) as error:
-                api_error = _coerce_tool_error(error)
-                if api_error is None or not _is_optional_chart_data_error(api_error):
-                    raise
-                transport_errors.append(_transport_error_payload(stage="data", error=api_error))
+                api_error = error if isinstance(error, QingflowApiError) else None
                 warnings.append(
                     {
                         "code": "CHART_DATA_UNAVAILABLE",
                         "message": "chart_get could not load chart data; returning chart metadata and config when available.",
-                        **_transport_warning_fields(api_error),
+                        "backend_code": api_error.backend_code if api_error is not None else None,
+                        "http_status": api_error.http_status if api_error is not None else None,
                     }
                 )
             if not data_config:
                 try:
                     config_result = self.charts.qingbi_report_get_config(profile=profile, chart_id=chart_id).get("result") or {}
-                except (QingflowApiError, RuntimeError) as error:
-                    api_error = _coerce_tool_error(error)
-                    if api_error is None or not _is_optional_chart_config_error(api_error):
-                        raise
-                    transport_errors.append(_transport_error_payload(stage="config", error=api_error))
-                    warnings.append(
-                        {
-                            "code": "CHART_CONFIG_UNAVAILABLE",
-                            "message": "chart_get could not load chart config; returning chart base info or data when available.",
-                            **_transport_warning_fields(api_error),
-                        }
-                    )
+                except (QingflowApiError, RuntimeError):
                     config_result = {}
                 if isinstance(config_result, dict) and config_result:
                     data_config = deepcopy(config_result)
                     verification["chart_config_loaded"] = True
-            if not any(
-                bool(verification[key])
-                for key in ("chart_base_loaded", "chart_data_loaded", "chart_config_loaded")
-            ):
-                return {
-                    "profile": profile,
-                    "ws_id": session_profile.selected_ws_id,
-                    "ok": False,
-                    "status": "failed",
-                    "error_code": "CHART_READ_UNAVAILABLE",
-                    "message": "chart_get could not load chart base info, data, or config in this permission context.",
-                    "warnings": warnings,
-                    "verification": verification,
-                    "details": {
-                        "chart_id": chart_id,
-                        "transport_errors": transport_errors,
-                    },
-                }
             data_payload: dict[str, Any] = {
                 "chart_id": chart_id,
                 "chart_name": str(base.get("chartName") or base.get("name") or chart_id).strip() or chart_id,
@@ -385,9 +296,7 @@ class ResourceReadTools(ToolBase):
     def _resolve_app_key_from_view_form(self, *, context: Any, view_key: str) -> str | None:
         try:
             form_payload = self.backend.request("GET", context, f"/view/{view_key}/form")
-        except QingflowApiError as exc:
-            if not _is_optional_view_metadata_resolution_error(exc):
-                raise
+        except QingflowApiError:
             return None
         if not isinstance(form_payload, dict):
             return None
@@ -400,13 +309,38 @@ class ResourceReadTools(ToolBase):
             return None
         try:
             payload = self.backend.request("GET", context, "/tag/apps")
-        except QingflowApiError as exc:
-            if not _is_optional_view_metadata_resolution_error(exc):
-                raise
+        except QingflowApiError:
             payload = None
         app_key = _find_visible_app_key_by_form_id(payload, form_id=form_id)
         if app_key:
             return app_key
+        page_num = 1
+        page_size = 200
+        while page_num <= 20:
+            try:
+                page = self.backend.request(
+                    "GET",
+                    context,
+                    "/app/item",
+                    params={"pageNum": page_num, "pageSize": page_size},
+                )
+            except QingflowApiError:
+                return None
+            items = page.get("list") if isinstance(page, dict) else []
+            if not isinstance(items, list) or not items:
+                return None
+            for item in items:
+                if not isinstance(item, dict):
+                    continue
+                if _coerce_positive_int(item.get("formId") or item.get("form_id")) != form_id:
+                    continue
+                app_key = str(item.get("appKey") or item.get("app_key") or "").strip()
+                if app_key:
+                    return app_key
+            total = _coerce_positive_int(page.get("total")) if isinstance(page, dict) else None
+            if total is not None and page_num * page_size >= total:
+                break
+            page_num += 1
         return None
 
 
@@ -489,89 +423,6 @@ def _normalize_user_portal_components(components: Any) -> list[dict[str, Any]]:
     return items
 
 
-def _is_optional_chart_base_error(error: QingflowApiError) -> bool:
-    if is_auth_like_error(error):
-        return False
-    backend_code = _coerce_backend_code(error)
-    return backend_code in {40002, 40027, 404, 81007} or error.http_status == 404
-
-
-def _is_optional_chart_data_error(error: QingflowApiError) -> bool:
-    if is_auth_like_error(error):
-        return False
-    backend_code = _coerce_backend_code(error)
-    return backend_code in {40002, 40027, 404, 44011, 81007, 81011} or error.http_status == 404
-
-
-def _is_optional_chart_config_error(error: QingflowApiError) -> bool:
-    if is_auth_like_error(error):
-        return False
-    backend_code = _coerce_backend_code(error)
-    return backend_code in {40002, 40027, 404, 44011, 81007, 81011} or error.http_status == 404
-
-
-def _is_optional_view_base_error(error: QingflowApiError) -> bool:
-    if is_auth_like_error(error):
-        return False
-    backend_code = _coerce_backend_code(error)
-    return backend_code in {40002, 40027, 404} or error.http_status == 404
-
-
-def _is_optional_view_config_error(error: QingflowApiError) -> bool:
-    if is_auth_like_error(error):
-        return False
-    backend_code = _coerce_backend_code(error)
-    return backend_code in {40002, 40027, 404} or error.http_status == 404
-
-
-def _is_optional_view_question_error(error: QingflowApiError) -> bool:
-    if is_auth_like_error(error):
-        return False
-    backend_code = _coerce_backend_code(error)
-    return backend_code in {40002, 40027, 404} or error.http_status == 404
-
-
-def _is_optional_view_metadata_resolution_error(error: QingflowApiError) -> bool:
-    if is_auth_like_error(error):
-        return False
-    backend_code = _coerce_backend_code(error)
-    return backend_code in {40002, 40027, 404} or error.http_status == 404
-
-
-def _coerce_backend_code(error: QingflowApiError) -> int | None:
-    return backend_code_int(error)
-
-
-def _transport_error_payload(*, stage: str, error: QingflowApiError) -> JSONObject:
-    payload: JSONObject = {
-        "stage": stage,
-        "category": error.category,
-        "message": error.message,
-    }
-    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
-    if error.request_id:
-        payload["request_id"] = error.request_id
-    if error.details:
-        payload["details"] = deepcopy(error.details)
-    return payload
-
-
-def _transport_warning_fields(error: QingflowApiError) -> JSONObject:
-    payload: JSONObject = {}
-    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
-    if error.request_id:
-        payload["request_id"] = error.request_id
-    if error.details:
-        payload["details"] = deepcopy(error.details)
-    return payload
-
-
 def _normalize_portal_component_source_type(value: Any) -> str:
     raw = str(value or "").strip()
     mapping = {

package/src/qingflow_mcp/tools/role_tools.py

@@ -1,11 +1,9 @@
 from __future__ import annotations
 
-from typing import Any
-
 from mcp.server.fastmcp import FastMCP
 
 from ..config import DEFAULT_PROFILE
-from ..errors import QingflowApiError, backend_code_int, is_auth_like_error, raise_tool_error
+from ..errors import QingflowApiError, raise_tool_error
 from ..json_types import JSONObject
 from .base import ToolBase, tool_cn_name
 
@@ -22,7 +20,7 @@ class RoleTools(ToolBase):
 
     def register(self, mcp: FastMCP) -> None:
         """注册当前工具到 MCP 服务。"""
-        @mcp.tool(description="Search workspace roles for builder permission and workflow configuration. Requires contact/role management permission and a non-empty keyword; do not use for record member/department field candidates.")
+        @mcp.tool()
         def role_search(
             profile: str = DEFAULT_PROFILE,
             keyword: str = "",
@@ -52,36 +50,18 @@ class RoleTools(ToolBase):
         """执行角色相关逻辑。"""
         if page_num <= 0 or page_size <= 0:
             raise_tool_error(QingflowApiError.config_error("page_num and page_size must be positive"))
-        normalized_keyword = keyword.strip()
-        if not normalized_keyword:
-            raise_tool_error(
-                QingflowApiError.config_error(
-                    "keyword is required for role_search; role lookup is a contact-management path, not a record candidate fallback"
-                )
-            )
 
         def runner(session_profile, context):
-            try:
-                result = self.backend.request(
-                    "GET",
-                    context,
-                    "/contact/roleByPage",
-                    params={"keyword": normalized_keyword, "pageNum": page_num, "pageSize": page_size},
-                )
-            except QingflowApiError as exc:
-                if _is_role_permission_denied(exc):
-                    return _contact_role_permission_denied_payload(
-                        profile=profile,
-                        ws_id=session_profile.selected_ws_id,
-                        error=exc,
-                        operation="role_search",
-                        selection={"keyword": normalized_keyword, "page_num": page_num, "page_size": page_size},
-                    )
-                raise
+            result = self.backend.request(
+                "GET",
+                context,
+                "/contact/roleByPage",
+                params={"keyword": keyword, "pageNum": page_num, "pageSize": page_size},
+            )
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
-                "keyword": normalized_keyword,
+                "keyword": keyword,
                 "page": result,
             }
 
@@ -130,54 +110,3 @@ class RoleTools(ToolBase):
             )
 
         return self._run(profile, runner)
-
-
-def _is_role_permission_denied(error: QingflowApiError) -> bool:
-    if is_auth_like_error(error):
-        return False
-    return backend_code_int(error) in {40002, 40027}
-
-
-def _contact_role_permission_denied_payload(
-    *,
-    profile: str,
-    ws_id: Any,
-    error: QingflowApiError,
-    operation: str,
-    selection: JSONObject,
-) -> JSONObject:
-    return {
-        "profile": profile,
-        "ws_id": ws_id,
-        "ok": False,
-        "status": "failed",
-        "error_code": "CONTACT_ROLE_PERMISSION_DENIED",
-        "message": (
-            "Contact role-management data is not readable for the current user. "
-            "This is a role/contact-management permission boundary, not proof that record "
-            "member or department field candidates are unavailable."
-        ),
-        "backend_code": error.backend_code,
-        "request_id": error.request_id,
-        "http_status": error.http_status,
-        "keyword": selection.get("keyword"),
-        "page": {"list": [], "total": 0, "pageAmount": 0},
-        "data": {
-            "items": [],
-            "pagination": {
-                "page": selection.get("page_num"),
-                "page_size": selection.get("page_size"),
-                "returned_items": 0,
-                "reported_total": 0,
-                "page_amount": 0,
-            },
-            "selection": selection,
-        },
-        "warnings": [
-            {
-                "code": "CONTACT_ROLE_PERMISSION_DENIED",
-                "message": "This is a role/contact-management permission boundary, not a record field candidate failure.",
-                "operation": operation,
-            }
-        ],
-    }

package/src/qingflow_mcp/tools/solution_tools.py

@@ -9,7 +9,7 @@ from mcp.server.fastmcp import FastMCP
 from pydantic import BaseModel, ValidationError
 
 from ..config import DEFAULT_PROFILE
-from ..errors import QingflowApiError, backend_code_int, is_auth_like_error, raise_tool_error
+from ..errors import QingflowApiError
 from ..list_type_labels import get_record_list_type_label
 from ..solution.build_assembly_store import BuildAssemblyStore, default_manifest
 from ..solution.compiler import CompiledSolution, ExecutionPlan, ExecutionStep, build_execution_plan, compile_solution
@@ -38,7 +38,6 @@ from .qingbi_report_tools import QingbiReportTools
 from .record_tools import RecordTools
 from .role_tools import RoleTools
 from .view_tools import ViewTools
-from .workflow_tools import WorkflowTools
 from .workspace_tools import WorkspaceTools
 
 STAGED_BUILD_MODES = {"preflight", "plan", "apply", "repair"}
@@ -737,6 +736,36 @@ class SolutionTools(ToolBase):
     ) -> dict[str, Any]:
         """执行方案相关逻辑。"""
         mode = _normalize_staged_build_mode(mode)
+        app_key = str(flow_spec.get("app_key") or "").strip()
+        spec_payload = flow_spec.get("spec")
+        if app_key and isinstance(spec_payload, dict) and spec_payload:
+            from .ai_builder_tools import AiBuilderTools
+
+            builder = AiBuilderTools(self.sessions, self.backend)
+            if mode in {"preflight", "plan"}:
+                return {
+                    "build_id": build_id or _generate_build_id(run_label=run_label, stage_name="flow"),
+                    "mode": mode,
+                    "stage": "flow",
+                    "status": "planned" if mode == "plan" else "preflighted",
+                    "normalized_args": {"app_key": app_key, "spec": spec_payload},
+                    "tool_name": "solution_build_flow",
+                }
+            result = builder.app_flow_apply(
+                profile=profile,
+                app_key=app_key,
+                spec=spec_payload,
+                publish=publish,
+                schema_version=flow_spec.get("schema_version") or flow_spec.get("schemaVersion"),
+            )
+            return {
+                "build_id": build_id,
+                "mode": mode,
+                "stage": "flow",
+                "status": result.get("status"),
+                "result": result,
+                "tool_name": "solution_build_flow",
+            }
         return self._stage_build(
             profile=profile,
             mode=mode,
@@ -1409,7 +1438,6 @@ class SolutionTools(ToolBase):
             role_tools=RoleTools(self.sessions, self.backend),
             app_tools=AppTools(self.sessions, self.backend),
             record_tools=RecordTools(self.sessions, self.backend),
-            workflow_tools=WorkflowTools(self.sessions, self.backend),
             view_tools=ViewTools(self.sessions, self.backend),
             chart_tools=QingbiReportTools(self.sessions, self.backend),
             portal_tools=PortalTools(self.sessions, self.backend),
@@ -1615,15 +1643,14 @@ class SolutionTools(ToolBase):
                 )
             except Exception as exc:  # noqa: BLE001
                 verification["status"] = "partial"
-                error_payload = _verification_error_payload(exc)
-                error_payload.update(
+                verification["errors"].append(
                     {
                         "category": "verification",
+                        "detail": str(exc),
                         "entity_id": entity_id,
                         "app_key": app_key,
                     }
                 )
-                verification["errors"].append(error_payload)
         if verification["views_created"]:
             verification["views_strategy"] = "created"
         else:
@@ -1909,9 +1936,7 @@ class SolutionTools(ToolBase):
                 result = packages.package_get(profile=profile, tag_id=package_tag_id, include_raw=False)
             except (QingflowApiError, RuntimeError) as exc:
                 error = _coerce_solution_api_error(exc)
-                if is_auth_like_error(error):
-                    raise_tool_error(error)
-                if backend_code_int(error) in {40002, 40027}:
+                if error.backend_code in {40002, 40027}:
                     return {
                         "status": "resolved",
                         "matched_via": "tag_id",
@@ -1937,33 +1962,13 @@ class SolutionTools(ToolBase):
                     retried=False,
                 )
             summary = result.get("result") if isinstance(result.get("result"), dict) else {}
-            resolution: dict[str, Any] = {
+            return {
                 "status": "resolved",
                 "matched_via": "tag_id",
                 "tag_id": package_tag_id,
                 "tag_name": summary.get("tagName"),
                 "candidates": [],
             }
-            warnings = result.get("warnings")
-            if isinstance(warnings, list):
-                for warning in warnings:
-                    if not isinstance(warning, dict):
-                        continue
-                    if warning.get("code") not in {"PACKAGE_BASE_INFO_UNAVAILABLE", "PACKAGE_DETAIL_READ_DEGRADED"}:
-                        continue
-                    resolution["metadata_unverified"] = True
-                    resolution["lookup_permission_blocked"] = {
-                        "scope": "package",
-                        "target": {"tag_id": package_tag_id},
-                        "transport_error": {
-                            "http_status": warning.get("http_status"),
-                            "backend_code": warning.get("backend_code"),
-                            "category": "backend",
-                            "request_id": warning.get("request_id"),
-                        },
-                    }
-                    break
-            return resolution
         if not normalized_name:
             return {
                 "status": "new_package",
@@ -3113,30 +3118,24 @@ def _builder_package_resolution_failed(
     error: QingflowApiError,
     retried: bool,
 ) -> dict[str, Any]:
-    permission_restricted_listing = (
-        package_tag_id <= 0
-        and not is_auth_like_error(error)
-        and backend_code_int(error) in {40002, 40027}
-    )
     if package_tag_id > 0:
         detail = f"failed to resolve package_tag_id '{package_tag_id}': {error.message}"
-    elif permission_restricted_listing:
+    elif error.backend_code in {40002, 40027}:
         detail = (
             f"failed to resolve package '{package_name}' because package listing is permission-restricted; "
             "provide package_tag_id explicitly or use an account that can list packages"
         )
     else:
         detail = f"failed to resolve package '{package_name}': {error.message}"
-    category = "config" if permission_restricted_listing else str(error.category or "backend")
-    error_fields = _solution_error_fields(category=category, detail=detail, suggested_next_call=None, stage="app")
-    error_fields["error_code"] = "AUTH_REQUIRED" if is_auth_like_error(error) else "PACKAGE_RESOLVE_FAILED"
+    error_fields = _solution_error_fields(category="config", detail=detail, suggested_next_call=None, stage="app")
+    error_fields["error_code"] = "PACKAGE_RESOLVE_FAILED"
     return {
         "status": "failed",
         "response": {
             "status": "failed",
             "mode": "plan",
             "stage": "app",
-            "errors": [{"category": category, "detail": detail}],
+            "errors": [{"category": "config", "detail": detail}],
             "package_resolution": {
                 "status": "failed",
                 "requested_name": package_name or None,
@@ -3438,28 +3437,15 @@ def _stage_skip_reason(stage_name: str) -> str:
     return reasons.get(stage_name, "Stage skipped because no applicable payload was provided.")
 
 
-def _verification_error_payload(exc: Exception) -> dict[str, Any]:
-    payload: dict[str, Any] = {"detail": str(exc)}
-    if isinstance(exc, QingflowApiError):
-        payload["transport_error"] = {
-            "http_status": exc.http_status,
-            "backend_code": exc.backend_code,
-            "category": exc.category,
-            "request_id": exc.request_id,
-        }
-        payload["request_id"] = exc.request_id
-        payload["backend_code"] = exc.backend_code
-        payload["http_status"] = exc.http_status
-    return payload
-
-
 def _append_verification_error(verification: dict[str, Any], scope: str, exc: Exception) -> None:
     errors = verification.setdefault("errors", [])
     if isinstance(errors, list):
-        error_payload = _verification_error_payload(exc)
-        error_payload["scope"] = scope
-        error_payload["message"] = str(exc)
-        errors.append(error_payload)
+        errors.append(
+            {
+                "scope": scope,
+                "message": str(exc),
+            }
+        )
 
 
 PREFERRED_RECORD_TITLE_LABELS = (