@josephyan/qingflow-cli 1.1.3 → 1.1.5

package/src/qingflow_mcp/tools/custom_button_tools.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from copy import deepcopy
 
 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
 from .base import ToolBase, tool_cn_name
 
@@ -31,12 +31,26 @@ class CustomButtonTools(ToolBase):
         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},
-            )
+            effective_being_draft = being_draft
+            fallback_error: QingflowApiError | None = None
+            try:
+                result = self.backend.request(
+                    "GET",
+                    context,
+                    f"/app/{app_key}/customButton",
+                    params={"beingDraft": being_draft},
+                )
+            except QingflowApiError as exc:
+                if not being_draft or not _is_optional_draft_button_read_error(exc):
+                    raise
+                fallback_error = exc
+                effective_being_draft = False
+                result = self.backend.request(
+                    "GET",
+                    context,
+                    f"/app/{app_key}/customButton",
+                    params={"beingDraft": False},
+                )
             items = []
             raw_items = result.get("result") if isinstance(result, dict) and isinstance(result.get("result"), list) else []
             for item in raw_items:
@@ -47,11 +61,23 @@ class CustomButtonTools(ToolBase):
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
                 "app_key": app_key,
-                "being_draft": being_draft,
+                "being_draft": effective_being_draft,
+                "requested_being_draft": being_draft,
                 "items": result if include_raw else items,
                 "count": len(items),
                 "compact": not include_raw,
             }
+            if fallback_error is not None:
+                response["warnings"] = [
+                    {
+                        "code": "CUSTOM_BUTTON_DRAFT_LIST_UNAVAILABLE",
+                        "message": "draft custom button list is unavailable; returned published custom buttons instead",
+                        "backend_code": fallback_error.backend_code,
+                        "http_status": fallback_error.http_status,
+                        "request_id": fallback_error.request_id,
+                    }
+                ]
+                response["verification"] = {"draft_readable": False, "published_fallback_used": True}
             if include_raw:
                 response["summary"] = items
             return response
@@ -74,16 +100,37 @@ class CustomButtonTools(ToolBase):
 
         def runner(session_profile, context):
             params = {"beingDraft": being_draft}
-            result = self.backend.request("GET", context, f"/app/{app_key}/customButton/{button_id}", params=params)
+            effective_being_draft = being_draft
+            fallback_error: QingflowApiError | None = None
+            try:
+                result = self.backend.request("GET", context, f"/app/{app_key}/customButton/{button_id}", params=params)
+            except QingflowApiError as exc:
+                if not being_draft or not _is_optional_draft_button_read_error(exc):
+                    raise
+                fallback_error = exc
+                effective_being_draft = False
+                result = self.backend.request("GET", context, f"/app/{app_key}/customButton/{button_id}", params={"beingDraft": False})
             response = {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
                 "app_key": app_key,
                 "button_id": button_id,
-                "being_draft": being_draft,
+                "being_draft": effective_being_draft,
+                "requested_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 fallback_error is not None:
+                response["warnings"] = [
+                    {
+                        "code": "CUSTOM_BUTTON_DRAFT_DETAIL_UNAVAILABLE",
+                        "message": "draft custom button detail is unavailable; returned published custom button detail instead",
+                        "backend_code": fallback_error.backend_code,
+                        "http_status": fallback_error.http_status,
+                        "request_id": fallback_error.request_id,
+                    }
+                ]
+                response["verification"] = {"draft_readable": False, "published_fallback_used": True}
             if include_raw:
                 response["summary"] = self._compact_button_detail(result if isinstance(result, dict) else {})
             return response
@@ -198,3 +245,10 @@ class CustomButtonTools(ToolBase):
             else None,
             "trigger_wings_config": deepcopy(item.get("triggerWingsConfig")) if isinstance(item.get("triggerWingsConfig"), dict) else None,
         }
+
+
+def _is_optional_draft_button_read_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

package/src/qingflow_mcp/tools/directory_tools.py

@@ -6,7 +6,7 @@ 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_int, is_auth_like_error, raise_tool_error
 from .base import ToolBase, tool_cn_name
 
 
@@ -20,28 +20,17 @@ class DirectoryTools(ToolBase):
     主要职责：
     1. 搜索用户、部门、外部联系人；
     2. 列举内部用户与部门层级；
-    3. 为审批/字段候选提供目录侧数据来源。
+    3. 为 builder 配置、审批处理或联系人确认提供目录侧数据来源。
+
+    注意：记录成员/部门字段候选应优先使用 record_member_candidates /
+    record_department_candidates，避免把普通记录读写误带入通讯录目录链路。
     """
 
     def register(self, mcp: FastMCP) -> None:
         """注册当前工具到 MCP 服务。"""
-        @mcp.tool()
-        def directory_search(
-            profile: str = DEFAULT_PROFILE,
-            query: str = "",
-            scopes: list[str] | None = None,
-            page_num: int = 1,
-            page_size: int = 20,
-        ) -> dict[str, Any]:
-            return self.directory_search(
-                profile=profile,
-                query=query,
-                scopes=scopes,
-                page_num=page_num,
-                page_size=page_size,
-            )
+        self.register_frontend_search(mcp)
 
-        @mcp.tool()
+        @mcp.tool(description="List internal workspace members through the contact directory route. This is a directory/admin-style lookup, not the record field candidate path.")
         def directory_list_internal_users(
             profile: str = DEFAULT_PROFILE,
             keyword: str | None = None,
@@ -61,7 +50,7 @@ class DirectoryTools(ToolBase):
                 contain_disable=include_disabled,
             )
 
-        @mcp.tool()
+        @mcp.tool(description="Page through internal workspace members through the contact directory route. This is a directory/admin-style lookup, not the record field candidate path.")
         def directory_list_all_internal_users(
             profile: str = DEFAULT_PROFILE,
             keyword: str | None = None,
@@ -81,7 +70,7 @@ class DirectoryTools(ToolBase):
                 max_pages=max_pages,
             )
 
-        @mcp.tool()
+        @mcp.tool(description="List internal departments. With keyword, uses frontend directory search; without keyword, browses the contact department tree and may require contact-directory permission.")
         def directory_list_internal_departments(
             profile: str = DEFAULT_PROFILE,
             keyword: str = "",
@@ -95,7 +84,7 @@ class DirectoryTools(ToolBase):
                 page_size=page_size,
             )
 
-        @mcp.tool()
+        @mcp.tool(description="Walk the internal department tree through the contact directory route. This may require contact-directory permission and should not be used for record department field candidates.")
         def directory_list_all_departments(
             profile: str = DEFAULT_PROFILE,
             parent_department_id: int | None = None,
@@ -109,20 +98,20 @@ class DirectoryTools(ToolBase):
                 max_items=max_items,
             )
 
-        @mcp.tool()
+        @mcp.tool(description="List child departments through the contact directory route. This may require contact-directory permission and should not be used for record department field candidates.")
         def directory_list_sub_departments(
             profile: str = DEFAULT_PROFILE,
             parent_department_id: int | None = None,
         ) -> dict[str, Any]:
             return self.directory_list_sub_departments(profile=profile, parent_dept_id=parent_department_id)
 
-        @mcp.tool()
+        @mcp.tool(description="Search external contacts. Defaults to the frontend simple external-member route; set simple=false only for full external-contact management data, which may require contact permission.")
         def directory_list_external_members(
             profile: str = DEFAULT_PROFILE,
             keyword: str | None = None,
             page_num: int = 1,
             page_size: int = 20,
-            simple: bool = False,
+            simple: bool = True,
         ) -> dict[str, Any]:
             return self.directory_list_external_members(
                 profile=profile,
@@ -132,6 +121,24 @@ class DirectoryTools(ToolBase):
                 simple=simple,
             )
 
+    def register_frontend_search(self, mcp: FastMCP) -> None:
+        """Register only the member-visible frontend search route."""
+        @mcp.tool(description="Search internal workspace members/departments by keyword via the frontend directory search route. Do not use for record member/department field candidates; use record_member_candidates or record_department_candidates instead.")
+        def directory_search(
+            profile: str = DEFAULT_PROFILE,
+            query: str = "",
+            scopes: list[str] | None = None,
+            page_num: int = 1,
+            page_size: int = 20,
+        ) -> dict[str, Any]:
+            return self.directory_search(
+                profile=profile,
+                query=query,
+                scopes=scopes,
+                page_num=page_num,
+                page_size=page_size,
+            )
+
     @tool_cn_name("通讯录搜索")
     def directory_search(
         self,
@@ -151,17 +158,28 @@ class DirectoryTools(ToolBase):
             raise_tool_error(QingflowApiError.config_error("query is required"))
 
         def runner(session_profile, context):
-            result = self.backend.request(
-                "POST",
-                context,
-                "/member/search",
-                json_body={
-                    "dimensions": normalized_scopes,
-                    "searchKey": query,
-                    "pageNum": page_num,
-                    "pageSize": page_size,
-                },
-            )
+            try:
+                result = self.backend.request(
+                    "POST",
+                    context,
+                    "/member/search",
+                    json_body={
+                        "dimensions": normalized_scopes,
+                        "searchKey": query,
+                        "pageNum": page_num,
+                        "pageSize": page_size,
+                    },
+                )
+            except QingflowApiError as exc:
+                if _is_directory_permission_denied(exc):
+                    return self._directory_permission_denied_payload(
+                        profile=profile,
+                        session_profile=session_profile,
+                        context=context,
+                        error=exc,
+                        operation="directory_search",
+                    )
+                raise
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
@@ -209,7 +227,18 @@ class DirectoryTools(ToolBase):
                 params["deptId"] = dept_id
             if role_id is not None:
                 params["roleId"] = role_id
-            result = self.backend.request("GET", context, "/contact", params=params)
+            try:
+                result = self.backend.request("GET", context, "/contact", params=params)
+            except QingflowApiError as exc:
+                if _is_directory_permission_denied(exc):
+                    return self._directory_permission_denied_payload(
+                        profile=profile,
+                        session_profile=session_profile,
+                        context=context,
+                        error=exc,
+                        operation="directory_list_internal_users",
+                    )
+                raise
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
@@ -269,7 +298,18 @@ class DirectoryTools(ToolBase):
                     params["deptId"] = dept_id
                 if role_id is not None:
                     params["roleId"] = role_id
-                result = self.backend.request("GET", context, "/contact", params=params)
+                try:
+                    result = self.backend.request("GET", context, "/contact", params=params)
+                except QingflowApiError as exc:
+                    if _is_directory_permission_denied(exc):
+                        return self._directory_permission_denied_payload(
+                            profile=profile,
+                            session_profile=session_profile,
+                            context=context,
+                            error=exc,
+                            operation="directory_list_all_internal_users",
+                        )
+                    raise
                 page_items = _directory_items(result)
                 if reported_total is None:
                     reported_total = _coerce_int(_payload_value(result, "total"))
@@ -329,13 +369,24 @@ class DirectoryTools(ToolBase):
 
         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,
-                )
+                try:
+                    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,
+                    )
+                except QingflowApiError as exc:
+                    if _is_directory_permission_denied(exc):
+                        return self._directory_permission_denied_payload(
+                            profile=profile,
+                            session_profile=session_profile,
+                            context=context,
+                            error=exc,
+                            operation="directory_list_internal_departments",
+                        )
+                    raise
                 start = (page_num - 1) * page_size
                 page_items = items[start : start + page_size]
                 reported_total = None if truncated else len(items)
@@ -367,17 +418,35 @@ class DirectoryTools(ToolBase):
             )
 
         def runner(session_profile, context):
-            result = self.backend.request(
-                "GET",
-                context,
-                "/contact/deptByPage",
-                params={"keyword": normalized_keyword, "pageNum": page_num, "pageSize": page_size},
-            )
+            try:
+                result = self.backend.request(
+                    "POST",
+                    context,
+                    "/member/search",
+                    json_body={
+                        "dimensions": ["DEPT"],
+                        "searchKey": normalized_keyword,
+                        "pageNum": page_num,
+                        "pageSize": page_size,
+                    },
+                )
+            except QingflowApiError as exc:
+                if _is_directory_permission_denied(exc):
+                    return self._directory_permission_denied_payload(
+                        profile=profile,
+                        session_profile=session_profile,
+                        context=context,
+                        error=exc,
+                        operation="directory_list_internal_departments",
+                    )
+                raise
+            dept_bucket = _payload_value(result, "dept") or result
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
                 "request_route": self._request_route_payload(context),
-                "page": result,
+                "page": dept_bucket,
+                "result": result,
             }
 
         raw = self._run(profile, runner)
@@ -411,19 +480,30 @@ class DirectoryTools(ToolBase):
             raise_tool_error(QingflowApiError.config_error("max_items must be positive"))
 
         def runner(session_profile, context):
-            items, truncated, deepest_depth = self._walk_department_tree(
-                context,
-                parent_dept_id=parent_dept_id,
-                max_depth=max_depth,
-                max_items=max_items,
-            )
-            if not items and parent_dept_id is None:
+            try:
                 items, truncated, deepest_depth = self._walk_department_tree(
                     context,
-                    parent_dept_id=0,
+                    parent_dept_id=parent_dept_id,
                     max_depth=max_depth,
                     max_items=max_items,
                 )
+                if not items and parent_dept_id is None:
+                    items, truncated, deepest_depth = self._walk_department_tree(
+                        context,
+                        parent_dept_id=0,
+                        max_depth=max_depth,
+                        max_items=max_items,
+                    )
+            except QingflowApiError as exc:
+                if _is_directory_permission_denied(exc):
+                    return self._directory_permission_denied_payload(
+                        profile=profile,
+                        session_profile=session_profile,
+                        context=context,
+                        error=exc,
+                        operation="directory_list_all_departments",
+                    )
+                raise
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
@@ -454,7 +534,18 @@ class DirectoryTools(ToolBase):
             params: dict[str, Any] = {}
             if parent_dept_id is not None:
                 params["parentDeptId"] = parent_dept_id
-            result = self.backend.request("GET", context, "/contact/subDeptList", params=params)
+            try:
+                result = self.backend.request("GET", context, "/contact/subDeptList", params=params)
+            except QingflowApiError as exc:
+                if _is_directory_permission_denied(exc):
+                    return self._directory_permission_denied_payload(
+                        profile=profile,
+                        session_profile=session_profile,
+                        context=context,
+                        error=exc,
+                        operation="directory_list_sub_departments",
+                    )
+                raise
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
@@ -479,22 +570,46 @@ class DirectoryTools(ToolBase):
         keyword: str | None,
         page_num: int,
         page_size: int,
-        simple: bool,
+        simple: bool = True,
     ) -> dict[str, Any]:
         """执行组织目录相关逻辑。"""
         def runner(session_profile, context):
             if simple:
-                result = self.backend.request(
-                    "POST",
-                    context,
-                    "/external/member/simple/pageList",
-                    json_body={"keyword": keyword, "pageNum": page_num, "pageSize": page_size},
-                )
+                try:
+                    result = self.backend.request(
+                        "POST",
+                        context,
+                        "/external/member/simple/pageList",
+                        json_body={"keyword": keyword, "pageNum": page_num, "pageSize": page_size},
+                    )
+                except QingflowApiError as exc:
+                    if _is_directory_permission_denied(exc):
+                        return self._directory_permission_denied_payload(
+                            profile=profile,
+                            session_profile=session_profile,
+                            context=context,
+                            error=exc,
+                            operation="directory_list_external_members_simple",
+                        ) | {"simple": simple}
+                    raise
             else:
-                params: dict[str, Any] = {"pageNum": page_num, "pageSize": page_size}
-                if keyword:
-                    params["keyword"] = keyword
-                result = self.backend.request("GET", context, "/external/member/pageList", params=params)
+                try:
+                    result = self.backend.request(
+                        "POST",
+                        context,
+                        "/external/member/pageList",
+                        json_body={"keyword": keyword, "pageNum": page_num, "pageSize": page_size},
+                    )
+                except QingflowApiError as exc:
+                    if _is_directory_permission_denied(exc):
+                        return self._directory_permission_denied_payload(
+                            profile=profile,
+                            session_profile=session_profile,
+                            context=context,
+                            error=exc,
+                            operation="directory_list_external_members_full",
+                        ) | {"simple": simple}
+                    raise
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
@@ -542,7 +657,7 @@ class DirectoryTools(ToolBase):
         """执行内部辅助逻辑。"""
         response = dict(raw)
         response["ok"] = bool(raw.get("ok", True))
-        response["warnings"] = []
+        response["warnings"] = list(raw.get("warnings") or [])
         response["output_profile"] = "normal"
         response["data"] = {
             "items": items,
@@ -551,6 +666,49 @@ class DirectoryTools(ToolBase):
         }
         return response
 
+    def _directory_permission_denied_payload(
+        self,
+        *,
+        profile: str,
+        session_profile,  # type: ignore[no-untyped-def]
+        context,  # type: ignore[no-untyped-def]
+        error: QingflowApiError,
+        operation: str,
+    ) -> dict[str, Any]:
+        candidate_hint = (
+            "For record member/department fields, use record_member_candidates or "
+            "record_department_candidates."
+            if operation == "directory_search"
+            else (
+                "For record member/department fields, use record_member_candidates, "
+                "record_department_candidates, or directory_search with a keyword instead."
+            )
+        )
+        return {
+            "profile": profile,
+            "ws_id": session_profile.selected_ws_id,
+            "ok": False,
+            "status": "failed",
+            "error_code": "CONTACT_DIRECTORY_PERMISSION_DENIED",
+            "message": (
+                "Contact-directory management data is not readable for the current user. "
+                f"{candidate_hint}"
+            ),
+            "backend_code": error.backend_code,
+            "request_id": error.request_id,
+            "http_status": error.http_status,
+            "request_route": self._request_route_payload(context),
+            "items": [],
+            "pagination": {"returned_items": 0},
+            "warnings": [
+                {
+                    "code": "CONTACT_DIRECTORY_PERMISSION_DENIED",
+                    "message": "This is a contact-directory permission boundary, not proof that record field candidates are unavailable.",
+                    "operation": operation,
+                }
+            ],
+        }
+
     def _walk_department_tree(
         self,
         context,  # type: ignore[no-untyped-def]
@@ -641,6 +799,12 @@ def _directory_has_more(payload: Any, *, current_page: int, page_size: int, retu
     return returned_items >= page_size and returned_items > 0
 
 
+def _is_directory_permission_denied(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    return backend_code_int(error) in {40002, 40027}
+
+
 def _directory_member_key(item: dict[str, Any]) -> str:
     for key in ("uid", "id", "userId"):
         value = item.get(key)