@josephyan/qingflow-cli 0.2.0-beta.1000

package/src/qingflow_mcp/tools/navigation_tools.py

@@ -0,0 +1,210 @@
+from __future__ import annotations
+
+from mcp.server.fastmcp import FastMCP
+
+from ..config import DEFAULT_PROFILE
+from ..errors import QingflowApiError, raise_tool_error
+from ..json_types import JSONObject
+from .base import ToolBase, tool_cn_name
+
+
+class NavigationTools(ToolBase):
+    """导航工具（中文名：导航菜单管理）。
+
+    类型：门户导航配置工具。
+    主要职责：
+    1. 查询导航结构与发布状态；
+    2. 读取指定导航详情；
+    3. 应用导航配置变更。
+    """
+
+    def register(self, mcp: FastMCP) -> None:
+        """注册当前工具到 MCP 服务。"""
+        @mcp.tool()
+        def navigation_list_published(profile: str = DEFAULT_PROFILE, page_num: int = 1, page_size: int = 50) -> JSONObject:
+            return self.navigation_list_published(profile=profile, page_num=page_num, page_size=page_size)
+
+        @mcp.tool()
+        def navigation_list_draft_page(
+            profile: str = DEFAULT_PROFILE,
+            page_num: int = 1,
+            page_size: int = 50,
+            query_key: str | None = None,
+        ) -> JSONObject:
+            return self.navigation_list_draft_page(profile=profile, page_num=page_num, page_size=page_size, query_key=query_key)
+
+        @mcp.tool()
+        def navigation_list_draft_all(profile: str = DEFAULT_PROFILE, query_key: str | None = None) -> JSONObject:
+            return self.navigation_list_draft_all(profile=profile, query_key=query_key)
+
+        @mcp.tool()
+        def navigation_get_detail(profile: str = DEFAULT_PROFILE, navigation_item_id: int = 0, status: str = "draft") -> JSONObject:
+            return self.navigation_get_detail(profile=profile, navigation_item_id=navigation_item_id, status=status)
+
+        @mcp.tool()
+        def navigation_get_status(profile: str = DEFAULT_PROFILE) -> JSONObject:
+            return self.navigation_get_status(profile=profile)
+
+        @mcp.tool()
+        def navigation_set_visible(profile: str = DEFAULT_PROFILE, payload: JSONObject | None = None) -> JSONObject:
+            return self.navigation_set_visible(profile=profile, payload=payload or {})
+
+        @mcp.tool()
+        def navigation_create(profile: str = DEFAULT_PROFILE, payload: JSONObject | None = None) -> JSONObject:
+            return self.navigation_create(profile=profile, payload=payload or {})
+
+        @mcp.tool(description=self._high_risk_tool_description(operation="update", target="navigation item configuration"))
+        def navigation_update(profile: str = DEFAULT_PROFILE, navigation_item_id: int = 0, payload: JSONObject | None = None) -> JSONObject:
+            return self.navigation_update(profile=profile, navigation_item_id=navigation_item_id, payload=payload or {})
+
+        @mcp.tool(description=self._high_risk_tool_description(operation="delete", target="navigation item configuration"))
+        def navigation_delete(profile: str = DEFAULT_PROFILE, navigation_item_id: int = 0) -> JSONObject:
+            return self.navigation_delete(profile=profile, navigation_item_id=navigation_item_id)
+
+        @mcp.tool()
+        def navigation_publish(profile: str = DEFAULT_PROFILE, navigation_id: int = 0) -> JSONObject:
+            return self.navigation_publish(profile=profile, navigation_id=navigation_id)
+
+        @mcp.tool()
+        def navigation_reorder(profile: str = DEFAULT_PROFILE, payload: list[JSONObject] | None = None) -> JSONObject:
+            return self.navigation_reorder(profile=profile, payload=payload or [])
+
+    @tool_cn_name("导航已发布列表")
+    def navigation_list_published(self, *, profile: str, page_num: int = 1, page_size: int = 50) -> JSONObject:
+        """执行工具方法逻辑。"""
+        def runner(session_profile, context):
+            result = self.backend.request("GET", context, "/navigation", params={"pageNum": page_num, "pageSize": page_size})
+            return {"profile": profile, "ws_id": session_profile.selected_ws_id, "page": result}
+
+        return self._run(profile, runner)
+
+    @tool_cn_name("导航草稿分页")
+    def navigation_list_draft_page(self, *, profile: str, page_num: int = 1, page_size: int = 50, query_key: str | None = None) -> JSONObject:
+        """执行工具方法逻辑。"""
+        def runner(session_profile, context):
+            params: JSONObject = {"pageNum": page_num, "pageSize": page_size}
+            if query_key:
+                params["queryCondition"] = query_key
+            result = self.backend.request("GET", context, "/navigation/page", params=params)
+            return {"profile": profile, "ws_id": session_profile.selected_ws_id, "page": result}
+
+        return self._run(profile, runner)
+
+    @tool_cn_name("导航草稿全量")
+    def navigation_list_draft_all(self, *, profile: str, query_key: str | None = None) -> JSONObject:
+        """执行工具方法逻辑。"""
+        def runner(session_profile, context):
+            params: JSONObject = {}
+            if query_key:
+                params["queryCondition"] = query_key
+            result = self.backend.request("GET", context, "/navigation/all", params=params)
+            return {"profile": profile, "ws_id": session_profile.selected_ws_id, "items": result}
+
+        return self._run(profile, runner)
+
+    @tool_cn_name("导航详情")
+    def navigation_get_detail(self, *, profile: str, navigation_item_id: int, status: str = "draft") -> JSONObject:
+        """执行工具方法逻辑。"""
+        self._require_navigation_item_id(navigation_item_id)
+
+        def runner(session_profile, context):
+            result = self.backend.request(
+                "GET",
+                context,
+                f"/navigation/detail/{navigation_item_id}",
+                params={"status": status},
+            )
+            return {"profile": profile, "ws_id": session_profile.selected_ws_id, "navigation_item_id": navigation_item_id, "result": result}
+
+        return self._run(profile, runner)
+
+    @tool_cn_name("导航发布状态")
+    def navigation_get_status(self, *, profile: str) -> JSONObject:
+        """执行工具方法逻辑。"""
+        def runner(session_profile, context):
+            result = self.backend.request("GET", context, "/navigation/status")
+            return {"profile": profile, "ws_id": session_profile.selected_ws_id, "result": result}
+
+        return self._run(profile, runner)
+
+    @tool_cn_name("设置导航可见性")
+    def navigation_set_visible(self, *, profile: str, payload: JSONObject) -> JSONObject:
+        """执行工具方法逻辑。"""
+        body = self._require_dict(payload)
+
+        def runner(session_profile, context):
+            result = self.backend.request("POST", context, "/navigation/visible", json_body=body)
+            return {"profile": profile, "ws_id": session_profile.selected_ws_id, "result": result}
+
+        return self._run(profile, runner)
+
+    @tool_cn_name("创建导航项")
+    def navigation_create(self, *, profile: str, payload: JSONObject) -> JSONObject:
+        """执行工具方法逻辑。"""
+        body = self._require_dict(payload)
+
+        def runner(session_profile, context):
+            result = self.backend.request("POST", context, "/navigation", json_body=body)
+            return {"profile": profile, "ws_id": session_profile.selected_ws_id, "result": result}
+
+        return self._run(profile, runner)
+
+    @tool_cn_name("更新导航项")
+    def navigation_update(self, *, profile: str, navigation_item_id: int, payload: JSONObject) -> JSONObject:
+        """执行工具方法逻辑。"""
+        self._require_navigation_item_id(navigation_item_id)
+        body = self._require_dict(payload)
+
+        def runner(session_profile, context):
+            result = self.backend.request("PUT", context, f"/navigation/{navigation_item_id}", json_body=body)
+            return self._attach_human_review_notice(
+                {"profile": profile, "ws_id": session_profile.selected_ws_id, "navigation_item_id": navigation_item_id, "result": result},
+                operation="update",
+                target="navigation item configuration",
+            )
+
+        return self._run(profile, runner)
+
+    @tool_cn_name("删除导航项")
+    def navigation_delete(self, *, profile: str, navigation_item_id: int) -> JSONObject:
+        """执行工具方法逻辑。"""
+        self._require_navigation_item_id(navigation_item_id)
+
+        def runner(session_profile, context):
+            result = self.backend.request("DELETE", context, f"/navigation/{navigation_item_id}")
+            return self._attach_human_review_notice(
+                {"profile": profile, "ws_id": session_profile.selected_ws_id, "navigation_item_id": navigation_item_id, "result": result},
+                operation="delete",
+                target="navigation item configuration",
+            )
+
+        return self._run(profile, runner)
+
+    @tool_cn_name("发布导航")
+    def navigation_publish(self, *, profile: str, navigation_id: int) -> JSONObject:
+        """执行工具方法逻辑。"""
+        if navigation_id <= 0:
+            raise_tool_error(QingflowApiError.config_error("navigation_id must be positive"))
+
+        def runner(session_profile, context):
+            result = self.backend.request("POST", context, f"/navigation/publish/{navigation_id}")
+            return {"profile": profile, "ws_id": session_profile.selected_ws_id, "navigation_id": navigation_id, "result": result}
+
+        return self._run(profile, runner)
+
+    @tool_cn_name("导航排序")
+    def navigation_reorder(self, *, profile: str, payload: list[JSONObject]) -> JSONObject:
+        """执行工具方法逻辑。"""
+        if not isinstance(payload, list) or not payload:
+            raise_tool_error(QingflowApiError.config_error("payload must be a non-empty array"))
+
+        def runner(session_profile, context):
+            result = self.backend.request("POST", context, "/navigation/ordinal", json_body=payload)
+            return {"profile": profile, "ws_id": session_profile.selected_ws_id, "result": result}
+
+        return self._run(profile, runner)
+
+    def _require_navigation_item_id(self, navigation_item_id: int) -> None:
+        """执行内部辅助逻辑。"""
+        if navigation_item_id <= 0:
+            raise_tool_error(QingflowApiError.config_error("navigation_item_id must be positive"))

package/src/qingflow_mcp/tools/package_tools.py

@@ -0,0 +1,326 @@
+from __future__ import annotations
+
+from copy import deepcopy
+
+from mcp.server.fastmcp import FastMCP
+
+from ..config import DEFAULT_PROFILE
+from ..errors import QingflowApiError, raise_tool_error
+from ..json_types import JSONObject
+from .base import ToolBase, tool_cn_name
+
+
+class PackageTools(ToolBase):
+    """分组工具（中文名：分组与归档管理）。
+
+    类型：资源组织工具。
+    主要职责：
+    1. 查询、解析、创建分组；
+    2. 管理应用与分组的挂载关系；
+    3. 为应用搭建提供分组定位能力。
+    """
+
+    def register(self, mcp: FastMCP) -> None:
+        """注册当前工具到 MCP 服务。"""
+        @mcp.tool()
+        def package_list(profile: str = DEFAULT_PROFILE, trial_status: str = "all", include_raw: bool = False) -> JSONObject:
+            return self.package_list(profile=profile, trial_status=trial_status, include_raw=include_raw)
+
+        @mcp.tool()
+        def package_get(profile: str = DEFAULT_PROFILE, tag_id: int = 0, include_raw: bool = False) -> JSONObject:
+            return self.package_get(profile=profile, tag_id=tag_id, include_raw=include_raw)
+
+        @mcp.tool()
+        def package_get_base(profile: str = DEFAULT_PROFILE, tag_id: int = 0, include_raw: bool = False) -> JSONObject:
+            return self.package_get_base(profile=profile, tag_id=tag_id, include_raw=include_raw)
+
+        @mcp.tool()
+        def package_create(profile: str = DEFAULT_PROFILE, payload: JSONObject | None = None) -> JSONObject:
+            return self.package_create(profile=profile, payload=payload or {})
+
+        @mcp.tool(description=self._high_risk_tool_description(operation="update", target="app package settings"))
+        def package_update(profile: str = DEFAULT_PROFILE, tag_id: int = 0, payload: JSONObject | None = None) -> JSONObject:
+            return self.package_update(profile=profile, tag_id=tag_id, payload=payload or {})
+
+        @mcp.tool(description=self._high_risk_tool_description(operation="delete", target="app package and linked data"))
+        def package_delete(profile: str = DEFAULT_PROFILE, tag_id: int = 0, deleted_all_data: bool = False) -> JSONObject:
+            return self.package_delete(profile=profile, tag_id=tag_id, deleted_all_data=deleted_all_data)
+
+    @tool_cn_name("分组列表")
+    def package_list(self, *, profile: str, trial_status: str = "all", include_raw: bool = False) -> JSONObject:
+        """执行分组与包相关逻辑。"""
+        def runner(session_profile, context):
+            result = self.backend.request("GET", context, "/tag", params={"trialStatus": trial_status})
+            raw_items, source_shape = self._extract_package_items(result)
+            compact_items = [self._compact_package(item) for item in raw_items if isinstance(item, dict)]
+            response = {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "trial_status": trial_status,
+                "items": result if include_raw else compact_items,
+                "count": len(compact_items),
+                "compact": not include_raw,
+                "source_shape": source_shape,
+                "retried": False,
+            }
+            if include_raw:
+                response["summary"] = compact_items
+            return response
+
+        return self._run(profile, runner)
+
+    @tool_cn_name("分组详情")
+    def package_get(self, *, profile: str, tag_id: int, include_raw: bool = False) -> JSONObject:
+        """执行分组与包相关逻辑。"""
+        self._require_tag_id(tag_id)
+
+        def runner(session_profile, context):
+            result = self.backend.request("GET", context, f"/tag/{tag_id}")
+            base_info = self.backend.request("GET", context, f"/tag/{tag_id}/baseInfo")
+            compact = self._compact_package(
+                result if isinstance(result, dict) else {},
+                base_info=base_info if isinstance(base_info, dict) else None,
+            )
+            response = {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "tag_id": tag_id,
+                "result": result if include_raw else compact,
+                "compact": not include_raw,
+            }
+            if include_raw:
+                response["summary"] = compact
+            return response
+
+        return self._run(profile, runner)
+
+    @tool_cn_name("分组基础信息")
+    def package_get_base(self, *, profile: str, tag_id: int, include_raw: bool = False) -> JSONObject:
+        """执行分组与包相关逻辑。"""
+        self._require_readable_tag_id(tag_id)
+
+        def runner(session_profile, context):
+            result = self.backend.request("GET", context, f"/tag/{tag_id}/baseInfo")
+            compact = self._compact_package(result if isinstance(result, dict) else {})
+            response = {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "tag_id": tag_id,
+                "result": result if include_raw else compact,
+                "compact": not include_raw,
+            }
+            if include_raw:
+                response["summary"] = compact
+            return response
+
+        return self._run(profile, runner)
+
+    @tool_cn_name("创建分组")
+    def package_create(self, *, profile: str, payload: JSONObject) -> JSONObject:
+        """执行分组与包相关逻辑。"""
+        body = self._require_dict(payload)
+
+        def runner(session_profile, context):
+            result = self.backend.request("POST", context, "/tag", json_body=self._normalize_package_payload(body))
+            return {"profile": profile, "ws_id": session_profile.selected_ws_id, "result": result}
+
+        return self._run(profile, runner)
+
+    @tool_cn_name("更新分组")
+    def package_update(self, *, profile: str, tag_id: int, payload: JSONObject) -> JSONObject:
+        """执行分组与包相关逻辑。"""
+        self._require_tag_id(tag_id)
+        body = self._require_dict(payload)
+
+        def runner(session_profile, context):
+            current = self.backend.request("GET", context, f"/tag/{tag_id}")
+            result = self.backend.request(
+                "PUT",
+                context,
+                f"/tag/{tag_id}",
+                json_body=self._normalize_package_payload(body, existing=current),
+            )
+            return self._attach_human_review_notice(
+                {"profile": profile, "ws_id": session_profile.selected_ws_id, "tag_id": tag_id, "result": result},
+                operation="update",
+                target="app package settings",
+            )
+
+        return self._run(profile, runner)
+
+    @tool_cn_name("分组排序")
+    def package_sort_items(self, *, profile: str, tag_id: int, tag_items: list[JSONObject]) -> JSONObject:
+        """执行分组与包相关逻辑。"""
+        self._require_tag_id(tag_id)
+
+        def runner(session_profile, context):
+            result = self.backend.request(
+                "POST",
+                context,
+                f"/tag/{tag_id}/ordinal",
+                json_body={"tagItems": deepcopy(tag_items)},
+            )
+            return {"profile": profile, "ws_id": session_profile.selected_ws_id, "tag_id": tag_id, "result": result}
+
+        return self._run(profile, runner)
+
+    @tool_cn_name("创建分组分栏")
+    def package_group_create(self, *, profile: str, tag_id: int, group_name: str) -> JSONObject:
+        """执行分组与包相关逻辑。"""
+        self._require_tag_id(tag_id)
+        normalized_name = str(group_name or "").strip()
+        if not normalized_name:
+            raise_tool_error(QingflowApiError.config_error("group_name is required"))
+
+        def runner(session_profile, context):
+            result = self.backend.request(
+                "POST",
+                context,
+                f"/tag/{tag_id}/group",
+                json_body={"groupName": normalized_name},
+            )
+            return {"profile": profile, "ws_id": session_profile.selected_ws_id, "tag_id": tag_id, "result": result}
+
+        return self._run(profile, runner)
+
+    @tool_cn_name("更新分组分栏")
+    def package_group_update(self, *, profile: str, tag_id: int, group_id: int, group_name: str) -> JSONObject:
+        """执行分组与包相关逻辑。"""
+        self._require_tag_id(tag_id)
+        self._require_group_id(group_id)
+        normalized_name = str(group_name or "").strip()
+        if not normalized_name:
+            raise_tool_error(QingflowApiError.config_error("group_name is required"))
+
+        def runner(session_profile, context):
+            result = self.backend.request(
+                "POST",
+                context,
+                f"/tag/{tag_id}/group/{group_id}",
+                json_body={"groupName": normalized_name},
+            )
+            return {"profile": profile, "ws_id": session_profile.selected_ws_id, "tag_id": tag_id, "group_id": group_id, "result": result}
+
+        return self._run(profile, runner)
+
+    @tool_cn_name("删除分组分栏")
+    def package_group_delete(self, *, profile: str, tag_id: int, group_id: int) -> JSONObject:
+        """执行分组与包相关逻辑。"""
+        self._require_tag_id(tag_id)
+        self._require_group_id(group_id)
+
+        def runner(session_profile, context):
+            result = self.backend.request("DELETE", context, f"/tag/{tag_id}/group/{group_id}")
+            return {"profile": profile, "ws_id": session_profile.selected_ws_id, "tag_id": tag_id, "group_id": group_id, "result": result}
+
+        return self._run(profile, runner)
+
+    @tool_cn_name("删除分组")
+    def package_delete(self, *, profile: str, tag_id: int, deleted_all_data: bool = False) -> JSONObject:
+        """执行分组与包相关逻辑。"""
+        self._require_tag_id(tag_id)
+
+        def runner(session_profile, context):
+            result = self.backend.request(
+                "DELETE",
+                context,
+                "/tag",
+                json_body={"tagId": tag_id, "deletedAllData": deleted_all_data},
+            )
+            return self._attach_human_review_notice(
+                {"profile": profile, "ws_id": session_profile.selected_ws_id, "tag_id": tag_id, "deleted_all_data": deleted_all_data, "result": result},
+                operation="delete",
+                target="app package and linked data",
+            )
+
+        return self._run(profile, runner)
+
+    def _require_tag_id(self, tag_id: int) -> None:
+        """执行内部辅助逻辑。"""
+        if tag_id <= 0:
+            raise_tool_error(QingflowApiError.config_error("tag_id must be positive"))
+
+    def _require_group_id(self, group_id: int) -> None:
+        """执行内部辅助逻辑。"""
+        if group_id <= 0:
+            raise_tool_error(QingflowApiError.config_error("group_id must be positive"))
+
+    def _require_readable_tag_id(self, tag_id: int) -> None:
+        """执行内部辅助逻辑。"""
+        if tag_id < 0:
+            raise_tool_error(QingflowApiError.config_error("tag_id must be non-negative"))
+
+    def _normalize_package_payload(self, payload: JSONObject, existing: JSONObject | None = None) -> JSONObject:
+        """执行内部辅助逻辑。"""
+        data = deepcopy(existing) if isinstance(existing, dict) else {}
+        data.update(deepcopy(payload))
+        data.pop("tagId", None)
+        data.pop("createTime", None)
+        data.pop("creator", None)
+        data.pop("publishStatus", None)
+        data.pop("beingTrial", None)
+        data.pop("trialExpireDate", None)
+        data.setdefault("tagIcon", "")
+        data.setdefault("tagItems", [])
+        data.setdefault("auth", _default_package_auth())
+        return data
+
+    def _compact_package(self, result: dict[str, object], *, base_info: dict[str, object] | None = None) -> JSONObject:
+        """执行内部辅助逻辑。"""
+        tag_items = result.get("tagItems") if isinstance(result.get("tagItems"), list) else []
+        permission_source = base_info if isinstance(base_info, dict) else result
+        preview = []
+        for item in tag_items[:10]:
+            if not isinstance(item, dict):
+                continue
+            preview.append(
+                {
+                    "title": item.get("title"),
+                    "itemType": item.get("itemType"),
+                    "appKey": item.get("appKey"),
+                    "dashKey": item.get("dashKey"),
+                }
+            )
+        compact = {
+            "tagId": result.get("tagId"),
+            "tagName": result.get("tagName"),
+            "tagIcon": result.get("tagIcon") if result.get("tagIcon") is not None else permission_source.get("tagIcon"),
+            "publishStatus": result.get("publishStatus") if result.get("publishStatus") is not None else permission_source.get("publishStatus"),
+            "beingTrial": result.get("beingTrial"),
+            "itemCount": len(tag_items),
+            "itemPreview": preview,
+            "addAppStatus": permission_source.get("addAppStatus"),
+            "editAppStatus": permission_source.get("editAppStatus"),
+            "delAppStatus": permission_source.get("delAppStatus"),
+            "editTagStatus": permission_source.get("editTagStatus"),
+        }
+        return {key: value for key, value in compact.items() if value is not None}
+
+    def _extract_package_items(self, result: object) -> tuple[list[dict[str, object]], str]:
+        """执行内部辅助逻辑。"""
+        if isinstance(result, list):
+            return [item for item in result if isinstance(item, dict)], "list"
+        if isinstance(result, dict):
+            tags = result.get("tags")
+            if isinstance(tags, list):
+                return [item for item in tags if isinstance(item, dict)], "dict.tags"
+            items = result.get("items")
+            if isinstance(items, list):
+                return [item for item in items if isinstance(item, dict)], "dict.items"
+            return [], "dict.unknown"
+        return [], type(result).__name__
+
+
+def _default_package_auth() -> JSONObject:
+    members = {
+        "depart": [],
+        "dynamic": [],
+        "includeSubDeparts": None,
+        "member": [],
+        "role": [],
+    }
+    return {
+        "type": "WORKSPACE",
+        "contactAuth": {"type": "WORKSPACE_ALL", "authMembers": deepcopy(members)},
+        "externalMemberAuth": {"type": "NOT", "authMembers": deepcopy(members)},
+    }