@josephyan/qingflow-app-builder-mcp 0.2.0-beta.7 → 0.2.0-beta.71

package/src/qingflow_mcp/tools/custom_button_tools.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+from copy import deepcopy
+
+from ..config import DEFAULT_PROFILE
+from ..errors import QingflowApiError, raise_tool_error
+from ..json_types import JSONObject
+from .base import ToolBase
+
+
+class CustomButtonTools(ToolBase):
+    def custom_button_list(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        being_draft: bool = True,
+        include_raw: bool = False,
+    ) -> JSONObject:
+        self._require_app_key(app_key)
+
+        def runner(session_profile, context):
+            result = self.backend.request(
+                "GET",
+                context,
+                f"/app/{app_key}/customButton",
+                params={"beingDraft": being_draft},
+            )
+            items = []
+            raw_items = result.get("result") if isinstance(result, dict) and isinstance(result.get("result"), list) else []
+            for item in raw_items:
+                if not isinstance(item, dict):
+                    continue
+                items.append(self._compact_button_base_info(item))
+            response = {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "app_key": app_key,
+                "being_draft": being_draft,
+                "items": result if include_raw else items,
+                "count": len(items),
+                "compact": not include_raw,
+            }
+            if include_raw:
+                response["summary"] = items
+            return response
+
+        return self._run(profile, runner)
+
+    def custom_button_get(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        button_id: int,
+        being_draft: bool = True,
+        include_raw: bool = False,
+    ) -> JSONObject:
+        self._require_app_key(app_key)
+        self._require_button_id(button_id)
+
+        def runner(session_profile, context):
+            params = {"beingDraft": being_draft}
+            result = self.backend.request("GET", context, f"/app/{app_key}/customButton/{button_id}", params=params)
+            response = {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "app_key": app_key,
+                "button_id": button_id,
+                "being_draft": being_draft,
+                "result": result if include_raw else self._compact_button_detail(result if isinstance(result, dict) else {}),
+                "compact": not include_raw,
+            }
+            if include_raw:
+                response["summary"] = self._compact_button_detail(result if isinstance(result, dict) else {})
+            return response
+
+        return self._run(profile, runner)
+
+    def custom_button_create(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        self._require_app_key(app_key)
+        body = self._require_dict(payload)
+
+        def runner(session_profile, context):
+            result = self.backend.request("POST", context, f"/app/{app_key}/customButton", json_body=deepcopy(body))
+            return {"profile": profile, "ws_id": session_profile.selected_ws_id, "app_key": app_key, "result": result}
+
+        return self._run(profile, runner)
+
+    def custom_button_update(self, *, profile: str, app_key: str, button_id: int, payload: JSONObject) -> JSONObject:
+        self._require_app_key(app_key)
+        self._require_button_id(button_id)
+        body = self._require_dict(payload)
+
+        def runner(session_profile, context):
+            result = self.backend.request(
+                "POST",
+                context,
+                f"/app/{app_key}/customButton/{button_id}",
+                json_body=deepcopy(body),
+            )
+            return self._attach_human_review_notice(
+                {
+                    "profile": profile,
+                    "ws_id": session_profile.selected_ws_id,
+                    "app_key": app_key,
+                    "button_id": button_id,
+                    "result": result,
+                },
+                operation="update",
+                target="custom button configuration",
+            )
+
+        return self._run(profile, runner)
+
+    def custom_button_delete(self, *, profile: str, app_key: str, button_id: int) -> JSONObject:
+        self._require_app_key(app_key)
+        self._require_button_id(button_id)
+
+        def runner(session_profile, context):
+            result = self.backend.request("DELETE", context, f"/app/{app_key}/customButton/{button_id}")
+            return self._attach_human_review_notice(
+                {
+                    "profile": profile,
+                    "ws_id": session_profile.selected_ws_id,
+                    "app_key": app_key,
+                    "button_id": button_id,
+                    "result": result,
+                },
+                operation="delete",
+                target="custom button configuration",
+            )
+
+        return self._run(profile, runner)
+
+    def _require_app_key(self, app_key: str) -> None:
+        if not str(app_key or "").strip():
+            raise_tool_error(QingflowApiError.config_error("app_key is required"))
+
+    def _require_button_id(self, button_id: int) -> None:
+        if not isinstance(button_id, int) or isinstance(button_id, bool) or button_id <= 0:
+            raise_tool_error(QingflowApiError.config_error("button_id must be a positive integer"))
+
+    def _compact_button_base_info(self, item: dict[str, object]) -> JSONObject:
+        creator = item.get("creatorUserInfo") if isinstance(item.get("creatorUserInfo"), dict) else {}
+        return {
+            "button_id": item.get("buttonId"),
+            "button_text": item.get("buttonText"),
+            "button_icon": item.get("buttonIcon"),
+            "icon_color": item.get("iconColor"),
+            "background_color": item.get("backgroundColor"),
+            "text_color": item.get("textColor"),
+            "creator_user_info": {
+                "uid": creator.get("uid"),
+                "name": creator.get("name"),
+                "email": creator.get("email"),
+            }
+            if creator
+            else None,
+            "used_in_chart_count": item.get("userInChartCount"),
+            "being_effective_external_qrobot": item.get("beingEffectiveExternalQRobot"),
+        }
+
+    def _compact_button_detail(self, item: dict[str, object]) -> JSONObject:
+        return {
+            "button_id": item.get("buttonId"),
+            "button_text": item.get("buttonText"),
+            "button_icon": item.get("buttonIcon"),
+            "icon_color": item.get("iconColor"),
+            "background_color": item.get("backgroundColor"),
+            "text_color": item.get("textColor"),
+            "trigger_action": item.get("triggerAction"),
+            "trigger_link_url": item.get("triggerLinkUrl"),
+            "trigger_add_data_config": deepcopy(item.get("triggerAddDataConfig")) if isinstance(item.get("triggerAddDataConfig"), dict) else None,
+            "external_qrobot_config": deepcopy(item.get("customButtonExternalQRobotRelationVO"))
+            if isinstance(item.get("customButtonExternalQRobotRelationVO"), dict)
+            else None,
+            "trigger_wings_config": deepcopy(item.get("triggerWingsConfig")) if isinstance(item.get("triggerWingsConfig"), dict) else None,
+        }

package/src/qingflow_mcp/tools/directory_tools.py

@@ -35,39 +35,39 @@ class DirectoryTools(ToolBase):
         def directory_list_internal_users(
             profile: str = DEFAULT_PROFILE,
             keyword: str | None = None,
-            dept_id: int | None = None,
+            department_id: int | None = None,
             role_id: int | None = None,
             page_num: int = 1,
             page_size: int = 20,
-            contain_disable: bool = False,
+            include_disabled: bool = False,
         ) -> dict[str, Any]:
             return self.directory_list_internal_users(
                 profile=profile,
                 keyword=keyword,
-                dept_id=dept_id,
+                dept_id=department_id,
                 role_id=role_id,
                 page_num=page_num,
                 page_size=page_size,
-                contain_disable=contain_disable,
+                contain_disable=include_disabled,
             )
 
         @mcp.tool()
         def directory_list_all_internal_users(
             profile: str = DEFAULT_PROFILE,
             keyword: str | None = None,
-            dept_id: int | None = None,
+            department_id: int | None = None,
             role_id: int | None = None,
             page_size: int = 200,
-            contain_disable: bool = False,
+            include_disabled: bool = False,
             max_pages: int = 100,
         ) -> dict[str, Any]:
             return self.directory_list_all_internal_users(
                 profile=profile,
                 keyword=keyword,
-                dept_id=dept_id,
+                dept_id=department_id,
                 role_id=role_id,
                 page_size=page_size,
-                contain_disable=contain_disable,
+                contain_disable=include_disabled,
                 max_pages=max_pages,
             )
 
@@ -88,13 +88,13 @@ class DirectoryTools(ToolBase):
         @mcp.tool()
         def directory_list_all_departments(
             profile: str = DEFAULT_PROFILE,
-            parent_dept_id: int | None = None,
+            parent_department_id: int | None = None,
             max_depth: int = 20,
             max_items: int = 2000,
         ) -> dict[str, Any]:
             return self.directory_list_all_departments(
                 profile=profile,
-                parent_dept_id=parent_dept_id,
+                parent_dept_id=parent_department_id,
                 max_depth=max_depth,
                 max_items=max_items,
             )
@@ -102,9 +102,9 @@ class DirectoryTools(ToolBase):
         @mcp.tool()
         def directory_list_sub_departments(
             profile: str = DEFAULT_PROFILE,
-            parent_dept_id: int | None = None,
+            parent_department_id: int | None = None,
         ) -> dict[str, Any]:
-            return self.directory_list_sub_departments(profile=profile, parent_dept_id=parent_dept_id)
+            return self.directory_list_sub_departments(profile=profile, parent_dept_id=parent_department_id)
 
         @mcp.tool()
         def directory_list_external_members(
@@ -150,9 +150,27 @@ class DirectoryTools(ToolBase):
                     "pageSize": page_size,
                 },
             )
-            return {"profile": profile, "ws_id": session_profile.selected_ws_id, "result": result}
+            return {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "request_route": self._request_route_payload(context),
+                "result": result,
+            }
 
-        return self._run(profile, runner)
+        raw = self._run(profile, runner)
+        items = [item for item in _directory_items(raw.get("result")) if isinstance(item, dict)]
+        return self._public_directory_response(
+            raw,
+            items=items,
+            pagination={
+                "page": page_num,
+                "page_size": page_size,
+                "returned_items": len(items),
+                "reported_total": _coerce_int(_payload_value(raw.get("result"), "total")),
+                "page_amount": _coerce_int(_payload_value(raw.get("result"), "pageAmount")),
+            },
+            selection={"query": query, "scopes": normalized_scopes},
+        )
 
     def directory_list_internal_users(
         self,
@@ -178,9 +196,27 @@ class DirectoryTools(ToolBase):
             if role_id is not None:
                 params["roleId"] = role_id
             result = self.backend.request("GET", context, "/contact", params=params)
-            return {"profile": profile, "ws_id": session_profile.selected_ws_id, "result": result}
+            return {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "request_route": self._request_route_payload(context),
+                "result": result,
+            }
 
-        return self._run(profile, runner)
+        raw = self._run(profile, runner)
+        items = [item for item in _directory_items(raw.get("result")) if isinstance(item, dict)]
+        return self._public_directory_response(
+            raw,
+            items=items,
+            pagination={
+                "page": page_num,
+                "page_size": page_size,
+                "returned_items": len(items),
+                "reported_total": _coerce_int(_payload_value(raw.get("result"), "total")),
+                "page_amount": _coerce_int(_payload_value(raw.get("result"), "pageAmount")),
+            },
+            selection={"keyword": keyword, "department_id": dept_id, "role_id": role_id, "include_disabled": contain_disable},
+        )
 
     def directory_list_all_internal_users(
         self,
@@ -237,6 +273,7 @@ class DirectoryTools(ToolBase):
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
+                "request_route": self._request_route_payload(context),
                 "items": items,
                 "pagination": {
                     "page_size": page_size,
@@ -250,7 +287,13 @@ class DirectoryTools(ToolBase):
                 },
             }
 
-        return self._run(profile, runner)
+        raw = self._run(profile, runner)
+        return self._public_directory_response(
+            raw,
+            items=[item for item in raw.get("items", []) if isinstance(item, dict)],
+            pagination=raw.get("pagination", {}),
+            selection={"keyword": keyword, "department_id": dept_id, "role_id": role_id, "include_disabled": contain_disable},
+        )
 
     def directory_list_internal_departments(
         self,
@@ -260,19 +303,79 @@ class DirectoryTools(ToolBase):
         page_num: int,
         page_size: int,
     ) -> dict[str, Any]:
-        if not keyword:
-            raise_tool_error(QingflowApiError.config_error("keyword is required"))
+        if page_num <= 0:
+            raise_tool_error(QingflowApiError.config_error("page_num must be positive"))
+        if page_size <= 0:
+            raise_tool_error(QingflowApiError.config_error("page_size must be positive"))
+        normalized_keyword = keyword.strip()
+
+        if not normalized_keyword:
+            def runner(session_profile, context):
+                fetch_limit = max((page_num + 1) * page_size + 1, page_size + 1)
+                items, truncated, deepest_depth = self._walk_department_tree(
+                    context,
+                    parent_dept_id=None,
+                    max_depth=20,
+                    max_items=fetch_limit,
+                )
+                start = (page_num - 1) * page_size
+                page_items = items[start : start + page_size]
+                reported_total = None if truncated else len(items)
+                page_amount = None if truncated else ((len(items) + page_size - 1) // page_size if items else 0)
+                if truncated and page_items:
+                    page_amount = max(page_num + 1, (start + len(page_items) + page_size - 1) // page_size)
+                return {
+                    "profile": profile,
+                    "ws_id": session_profile.selected_ws_id,
+                    "request_route": self._request_route_payload(context),
+                    "items": page_items,
+                    "pagination": {
+                        "page": page_num,
+                        "page_size": page_size,
+                        "returned_items": len(page_items),
+                        "reported_total": reported_total,
+                        "page_amount": page_amount,
+                        "depth_scanned": deepest_depth + 1 if page_items else 0,
+                    },
+                }
+
+            raw = self._run(profile, runner)
+            items = [item for item in raw.get("items", []) if isinstance(item, dict)]
+            return self._public_directory_response(
+                raw,
+                items=items,
+                pagination=raw.get("pagination", {}),
+                selection={"keyword": None},
+            )
 
         def runner(session_profile, context):
             result = self.backend.request(
                 "GET",
                 context,
                 "/contact/deptByPage",
-                params={"keyword": keyword, "pageNum": page_num, "pageSize": page_size},
+                params={"keyword": normalized_keyword, "pageNum": page_num, "pageSize": page_size},
             )
-            return {"profile": profile, "ws_id": session_profile.selected_ws_id, "page": result}
+            return {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "request_route": self._request_route_payload(context),
+                "page": result,
+            }
 
-        return self._run(profile, runner)
+        raw = self._run(profile, runner)
+        items = [item for item in _directory_items(raw.get("page")) if isinstance(item, dict)]
+        return self._public_directory_response(
+            raw,
+            items=items,
+            pagination={
+                "page": page_num,
+                "page_size": page_size,
+                "returned_items": len(items),
+                "reported_total": _coerce_int(_payload_value(raw.get("page"), "total")),
+                "page_amount": _coerce_int(_payload_value(raw.get("page"), "pageAmount")),
+            },
+            selection={"keyword": normalized_keyword},
+        )
 
     def directory_list_all_departments(
         self,
@@ -304,18 +407,25 @@ class DirectoryTools(ToolBase):
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
+                "request_route": self._request_route_payload(context),
                 "items": items,
-                "traversal": {
-                    "root_parent_dept_id": parent_dept_id,
+                "pagination": {
+                    "root_parent_department_id": parent_dept_id,
                     "returned_items": len(items),
-                    "max_depth": deepest_depth,
-                    "truncated": truncated,
+                    "fetched_pages": deepest_depth + 1 if items else 0,
                     "is_complete": not truncated,
+                    "has_more": truncated,
                     "max_items": max_items,
                 },
             }
 
-        return self._run(profile, runner)
+        raw = self._run(profile, runner)
+        return self._public_directory_response(
+            raw,
+            items=[item for item in raw.get("items", []) if isinstance(item, dict)],
+            pagination=raw.get("pagination", {}),
+            selection={"parent_department_id": parent_dept_id, "max_depth": max_depth, "max_items": max_items},
+        )
 
     def directory_list_sub_departments(self, *, profile: str, parent_dept_id: int | None) -> dict[str, Any]:
         def runner(session_profile, context):
@@ -323,9 +433,21 @@ class DirectoryTools(ToolBase):
             if parent_dept_id is not None:
                 params["parentDeptId"] = parent_dept_id
             result = self.backend.request("GET", context, "/contact/subDeptList", params=params)
-            return {"profile": profile, "ws_id": session_profile.selected_ws_id, "items": result}
+            return {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "request_route": self._request_route_payload(context),
+                "items": result,
+            }
 
-        return self._run(profile, runner)
+        raw = self._run(profile, runner)
+        items = [item for item in raw.get("items", []) if isinstance(item, dict)]
+        return self._public_directory_response(
+            raw,
+            items=items,
+            pagination={"returned_items": len(items)},
+            selection={"parent_department_id": parent_dept_id},
+        )
 
     def directory_list_external_members(
         self,
@@ -349,9 +471,59 @@ class DirectoryTools(ToolBase):
                 if keyword:
                     params["keyword"] = keyword
                 result = self.backend.request("GET", context, "/external/member/pageList", params=params)
-            return {"profile": profile, "ws_id": session_profile.selected_ws_id, "page": result, "simple": simple}
+            return {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "request_route": self._request_route_payload(context),
+                "page": result,
+                "simple": simple,
+            }
 
-        return self._run(profile, runner)
+        raw = self._run(profile, runner)
+        items = [item for item in _directory_items(raw.get("page")) if isinstance(item, dict)]
+        return self._public_directory_response(
+            raw,
+            items=items,
+            pagination={
+                "page": page_num,
+                "page_size": page_size,
+                "returned_items": len(items),
+                "reported_total": _coerce_int(_payload_value(raw.get("page"), "total")),
+                "page_amount": _coerce_int(_payload_value(raw.get("page"), "pageAmount")),
+            },
+            selection={"keyword": keyword, "simple": simple},
+        )
+
+    def _request_route_payload(self, context) -> dict[str, Any]:  # type: ignore[no-untyped-def]
+        describe_route = getattr(self.backend, "describe_route", None)
+        if callable(describe_route):
+            payload = describe_route(context)
+            if isinstance(payload, dict):
+                return payload
+        return {
+            "base_url": getattr(context, "base_url", None),
+            "qf_version": getattr(context, "qf_version", None),
+            "qf_version_source": getattr(context, "qf_version_source", None) or ("context" if getattr(context, "qf_version", None) else "unknown"),
+        }
+
+    def _public_directory_response(
+        self,
+        raw: dict[str, Any],
+        *,
+        items: list[dict[str, Any]],
+        pagination: dict[str, Any],
+        selection: dict[str, Any],
+    ) -> dict[str, Any]:
+        response = dict(raw)
+        response["ok"] = bool(raw.get("ok", True))
+        response["warnings"] = []
+        response["output_profile"] = "normal"
+        response["data"] = {
+            "items": items,
+            "pagination": pagination,
+            "selection": selection,
+        }
+        return response
 
     def _walk_department_tree(
         self,