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

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, 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
 
@@ -31,26 +31,12 @@ class CustomButtonTools(ToolBase):
         self._require_app_key(app_key)
 
         def runner(session_profile, context):
-            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},
-                )
+            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:
@@ -61,23 +47,11 @@ class CustomButtonTools(ToolBase):
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
                 "app_key": app_key,
-                "being_draft": effective_being_draft,
-                "requested_being_draft": being_draft,
+                "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
@@ -100,37 +74,16 @@ class CustomButtonTools(ToolBase):
 
         def runner(session_profile, context):
             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/{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})
+            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": effective_being_draft,
-                "requested_being_draft": being_draft,
+                "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
@@ -245,10 +198,3 @@ 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, backend_code_int, is_auth_like_error, raise_tool_error
+from ..errors import QingflowApiError, raise_tool_error
 from .base import ToolBase, tool_cn_name
 
 
@@ -20,17 +20,28 @@ class DirectoryTools(ToolBase):
     主要职责：
     1. 搜索用户、部门、外部联系人；
     2. 列举内部用户与部门层级；
-    3. 为 builder 配置、审批处理或联系人确认提供目录侧数据来源。
-
-    注意：记录成员/部门字段候选应优先使用 record_member_candidates /
-    record_department_candidates，避免把普通记录读写误带入通讯录目录链路。
+    3. 为审批/字段候选提供目录侧数据来源。
     """
 
     def register(self, mcp: FastMCP) -> None:
         """注册当前工具到 MCP 服务。"""
-        self.register_frontend_search(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,
+            )
 
-        @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.")
+        @mcp.tool()
         def directory_list_internal_users(
             profile: str = DEFAULT_PROFILE,
             keyword: str | None = None,
@@ -50,7 +61,7 @@ class DirectoryTools(ToolBase):
                 contain_disable=include_disabled,
             )
 
-        @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.")
+        @mcp.tool()
         def directory_list_all_internal_users(
             profile: str = DEFAULT_PROFILE,
             keyword: str | None = None,
@@ -70,7 +81,7 @@ class DirectoryTools(ToolBase):
                 max_pages=max_pages,
             )
 
-        @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.")
+        @mcp.tool()
         def directory_list_internal_departments(
             profile: str = DEFAULT_PROFILE,
             keyword: str = "",
@@ -84,7 +95,7 @@ class DirectoryTools(ToolBase):
                 page_size=page_size,
             )
 
-        @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.")
+        @mcp.tool()
         def directory_list_all_departments(
             profile: str = DEFAULT_PROFILE,
             parent_department_id: int | None = None,
@@ -98,20 +109,20 @@ class DirectoryTools(ToolBase):
                 max_items=max_items,
             )
 
-        @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.")
+        @mcp.tool()
         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(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.")
+        @mcp.tool()
         def directory_list_external_members(
             profile: str = DEFAULT_PROFILE,
             keyword: str | None = None,
             page_num: int = 1,
             page_size: int = 20,
-            simple: bool = True,
+            simple: bool = False,
         ) -> dict[str, Any]:
             return self.directory_list_external_members(
                 profile=profile,
@@ -121,24 +132,6 @@ 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,
@@ -158,28 +151,17 @@ class DirectoryTools(ToolBase):
             raise_tool_error(QingflowApiError.config_error("query is required"))
 
         def runner(session_profile, context):
-            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
+            result = self.backend.request(
+                "POST",
+                context,
+                "/member/search",
+                json_body={
+                    "dimensions": normalized_scopes,
+                    "searchKey": query,
+                    "pageNum": page_num,
+                    "pageSize": page_size,
+                },
+            )
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
@@ -227,18 +209,7 @@ class DirectoryTools(ToolBase):
                 params["deptId"] = dept_id
             if role_id is not None:
                 params["roleId"] = role_id
-            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
+            result = self.backend.request("GET", context, "/contact", params=params)
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
@@ -298,18 +269,7 @@ class DirectoryTools(ToolBase):
                     params["deptId"] = dept_id
                 if role_id is not None:
                     params["roleId"] = role_id
-                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
+                result = self.backend.request("GET", context, "/contact", params=params)
                 page_items = _directory_items(result)
                 if reported_total is None:
                     reported_total = _coerce_int(_payload_value(result, "total"))
@@ -369,24 +329,13 @@ class DirectoryTools(ToolBase):
 
         if not normalized_keyword:
             def runner(session_profile, context):
-                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
+                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)
@@ -418,35 +367,17 @@ class DirectoryTools(ToolBase):
             )
 
         def runner(session_profile, context):
-            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
+            result = self.backend.request(
+                "GET",
+                context,
+                "/contact/deptByPage",
+                params={"keyword": normalized_keyword, "pageNum": page_num, "pageSize": page_size},
+            )
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
                 "request_route": self._request_route_payload(context),
-                "page": dept_bucket,
-                "result": result,
+                "page": result,
             }
 
         raw = self._run(profile, runner)
@@ -480,30 +411,19 @@ class DirectoryTools(ToolBase):
             raise_tool_error(QingflowApiError.config_error("max_items must be positive"))
 
         def runner(session_profile, context):
-            try:
+            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:
                 items, truncated, deepest_depth = self._walk_department_tree(
                     context,
-                    parent_dept_id=parent_dept_id,
+                    parent_dept_id=0,
                     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,
@@ -534,18 +454,7 @@ class DirectoryTools(ToolBase):
             params: dict[str, Any] = {}
             if parent_dept_id is not None:
                 params["parentDeptId"] = parent_dept_id
-            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
+            result = self.backend.request("GET", context, "/contact/subDeptList", params=params)
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
@@ -570,46 +479,22 @@ class DirectoryTools(ToolBase):
         keyword: str | None,
         page_num: int,
         page_size: int,
-        simple: bool = True,
+        simple: bool,
     ) -> dict[str, Any]:
         """执行组织目录相关逻辑。"""
         def runner(session_profile, context):
             if simple:
-                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
+                result = self.backend.request(
+                    "POST",
+                    context,
+                    "/external/member/simple/pageList",
+                    json_body={"keyword": keyword, "pageNum": page_num, "pageSize": page_size},
+                )
             else:
-                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
+                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)
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
@@ -657,7 +542,7 @@ class DirectoryTools(ToolBase):
         """执行内部辅助逻辑。"""
         response = dict(raw)
         response["ok"] = bool(raw.get("ok", True))
-        response["warnings"] = list(raw.get("warnings") or [])
+        response["warnings"] = []
         response["output_profile"] = "normal"
         response["data"] = {
             "items": items,
@@ -666,49 +551,6 @@ 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]
@@ -799,12 +641,6 @@ 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)