@josephyan/qingflow-app-user-mcp 0.2.0-beta.20 → 0.2.0-beta.21

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,
@@ -270,9 +313,27 @@ class DirectoryTools(ToolBase):
                 "/contact/deptByPage",
                 params={"keyword": 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": keyword},
+        )
 
     def directory_list_all_departments(
         self,
@@ -304,18 +365,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 +391,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 +429,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,