@josephyan/qingflow-cli 0.2.0-beta.984 → 0.2.0-beta.986

package/src/qingflow_mcp/tools/portal_tools.py

@@ -5,11 +5,21 @@ 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
+from .base import ToolBase, tool_cn_name
 
 
 class PortalTools(ToolBase):
+    """门户工具（中文名：门户页管理）。
+
+    类型：门户配置工具。
+    主要职责：
+    1. 查询门户列表与详情；
+    2. 维护门户基础信息与配置；
+    3. 执行门户发布与删除操作。
+    """
+
     def register(self, mcp: FastMCP) -> None:
+        """注册当前工具到 MCP 服务。"""
         @mcp.tool()
         def portal_list(profile: str = DEFAULT_PROFILE) -> JSONObject:
             return self.portal_list(profile=profile)
@@ -42,14 +52,18 @@ class PortalTools(ToolBase):
         def portal_publish(profile: str = DEFAULT_PROFILE, dash_key: str = "") -> JSONObject:
             return self.portal_publish(profile=profile, dash_key=dash_key)
 
+    @tool_cn_name("门户列表")
     def portal_list(self, *, profile: str) -> JSONObject:
+        """执行门户相关逻辑。"""
         def runner(session_profile, context):
             result = self.backend.request("GET", context, "/dash")
             return {"profile": profile, "ws_id": session_profile.selected_ws_id, "items": result}
 
         return self._run(profile, runner)
 
+    @tool_cn_name("门户详情")
     def portal_get(self, *, profile: str, dash_key: str, being_draft: bool = False) -> JSONObject:
+        """执行门户相关逻辑。"""
         self._require_dash_key(dash_key)
 
         def runner(session_profile, context):
@@ -58,7 +72,9 @@ class PortalTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("创建门户")
     def portal_create(self, *, profile: str, payload: JSONObject) -> JSONObject:
+        """执行门户相关逻辑。"""
         body = self._require_dict(payload)
 
         def runner(session_profile, context):
@@ -67,7 +83,9 @@ class PortalTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("门户基础信息")
     def portal_get_base_info(self, *, profile: str, dash_key: str) -> JSONObject:
+        """执行门户相关逻辑。"""
         self._require_dash_key(dash_key)
 
         def runner(session_profile, context):
@@ -76,7 +94,9 @@ class PortalTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("更新门户基础信息")
     def portal_update_base_info(self, *, profile: str, dash_key: str, payload: JSONObject) -> JSONObject:
+        """执行门户相关逻辑。"""
         self._require_dash_key(dash_key)
         body = self._require_dict(payload)
 
@@ -90,7 +110,9 @@ class PortalTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("更新门户配置")
     def portal_update(self, *, profile: str, dash_key: str, payload: JSONObject) -> JSONObject:
+        """执行门户相关逻辑。"""
         self._require_dash_key(dash_key)
         body = self._require_dict(payload)
 
@@ -104,7 +126,9 @@ class PortalTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("删除门户")
     def portal_delete(self, *, profile: str, dash_key: str) -> JSONObject:
+        """执行门户相关逻辑。"""
         self._require_dash_key(dash_key)
 
         def runner(session_profile, context):
@@ -117,7 +141,9 @@ class PortalTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("发布门户")
     def portal_publish(self, *, profile: str, dash_key: str) -> JSONObject:
+        """执行门户相关逻辑。"""
         self._require_dash_key(dash_key)
 
         def runner(session_profile, context):
@@ -127,5 +153,6 @@ class PortalTools(ToolBase):
         return self._run(profile, runner)
 
     def _require_dash_key(self, dash_key: str) -> None:
+        """执行内部辅助逻辑。"""
         if not dash_key:
             raise_tool_error(QingflowApiError.config_error("dash_key is required"))

package/src/qingflow_mcp/tools/qingbi_report_tools.py

@@ -9,7 +9,7 @@ from ..backend_client import BackendRequestContext
 from ..config import DEFAULT_PROFILE, normalize_base_url
 from ..errors import QingflowApiError, raise_tool_error
 from ..json_types import JSONObject, JSONValue
-from .base import ToolBase
+from .base import ToolBase, tool_cn_name
 
 
 def _qingbi_base_url(base_url: str) -> str:
@@ -51,7 +51,17 @@ def _coerce_tool_error(error: RuntimeError | QingflowApiError) -> QingflowApiErr
 
 
 class QingbiReportTools(ToolBase):
+    """轻报表工具（中文名：图表与报表读取）。
+
+    类型：报表分析工具。
+    主要职责：
+    1. 查询报表列表与基础信息；
+    2. 获取报表配置与图表数据；
+    3. 为门户与任务上下文提供报表侧读取能力。
+    """
+
     def register(self, mcp: FastMCP) -> None:
+        """注册当前工具到 MCP 服务。"""
         @mcp.tool()
         def qingbi_report_list(
             profile: str = DEFAULT_PROFILE,
@@ -123,10 +133,13 @@ class QingbiReportTools(ToolBase):
         ) -> JSONObject:
             return self.qingbi_report_list_field_options(profile=profile, field_id=field_id, chart_id=chart_id)
 
+    @tool_cn_name("报表列表")
     def qingbi_report_list(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行工具方法逻辑。"""
         self._require_app_key(app_key)
         return self._request(profile, "GET", f"/qingbi/charts/data/bichart/{app_key}", app_key=app_key, items_key="items")
 
+    @tool_cn_name("报表排序列表")
     def qingbi_report_list_sorted(
         self,
         *,
@@ -136,6 +149,7 @@ class QingbiReportTools(ToolBase):
         page_size: int = 500,
         search_key: str | None = None,
     ) -> JSONObject:
+        """执行工具方法逻辑。"""
         self._require_app_key(app_key)
         body: JSONObject = {"appKey": app_key, "pageNum": page_num, "pageSize": page_size}
         if search_key:
@@ -153,11 +167,15 @@ class QingbiReportTools(ToolBase):
             json_body=body,
         )
 
+    @tool_cn_name("创建报表")
     def qingbi_report_create(self, *, profile: str, payload: JSONObject) -> JSONObject:
+        """执行工具方法逻辑。"""
         body = self._require_dict(payload)
         return self._request(profile, "POST", "/qingbi/charts", json_body=body)
 
+    @tool_cn_name("报表基础信息")
     def qingbi_report_get_base(self, *, profile: str, chart_id: str) -> JSONObject:
+        """执行工具方法逻辑。"""
         self._require_chart_id(chart_id)
         try:
             return self._request(profile, "GET", f"/qingbi/charts/baseinfo/{chart_id}", chart_id=chart_id)
@@ -167,20 +185,27 @@ class QingbiReportTools(ToolBase):
                 raise
         return self._request(profile, "GET", f"/qingbi/charts/qflow/baseinfo/{chart_id}", chart_id=chart_id)
 
+    @tool_cn_name("更新报表基础信息")
     def qingbi_report_update_base(self, *, profile: str, chart_id: str, payload: JSONObject) -> JSONObject:
+        """执行工具方法逻辑。"""
         self._require_chart_id(chart_id)
         body = self._require_dict(payload)
         return self._request(profile, "PUT", f"/qingbi/charts/baseinfo/{chart_id}", chart_id=chart_id, json_body=body, risk_operation="update", risk_target="report base settings")
 
+    @tool_cn_name("报表配置")
     def qingbi_report_get_config(self, *, profile: str, chart_id: str) -> JSONObject:
+        """执行工具方法逻辑。"""
         self._require_chart_id(chart_id)
         return self._request(profile, "GET", f"/qingbi/charts/{chart_id}/configs", chart_id=chart_id)
 
+    @tool_cn_name("更新报表配置")
     def qingbi_report_update_config(self, *, profile: str, chart_id: str, payload: JSONObject) -> JSONObject:
+        """执行工具方法逻辑。"""
         self._require_chart_id(chart_id)
         body = self._require_dict(payload)
         return self._request(profile, "PUT", f"/qingbi/charts/{chart_id}/configs", chart_id=chart_id, json_body=body, risk_operation="update", risk_target="report chart config")
 
+    @tool_cn_name("报表数据")
     def qingbi_report_get_data(
         self,
         *,
@@ -192,6 +217,7 @@ class QingbiReportTools(ToolBase):
         page_num_y: int | None = None,
         page_size_y: int | None = None,
     ) -> JSONObject:
+        """执行工具方法逻辑。"""
         self._require_chart_id(chart_id)
         params = {
             "qfUUID": uuid4().hex,
@@ -234,11 +260,15 @@ class QingbiReportTools(ToolBase):
             json_body=payload or {},
         )
 
+    @tool_cn_name("删除报表")
     def qingbi_report_delete(self, *, profile: str, chart_id: str) -> JSONObject:
+        """执行工具方法逻辑。"""
         self._require_chart_id(chart_id)
         return self._request(profile, "DELETE", f"/qingbi/charts/{chart_id}", chart_id=chart_id, risk_operation="delete", risk_target="report chart")
 
+    @tool_cn_name("报表排序")
     def qingbi_report_reorder(self, *, profile: str, app_key: str, chart_ids: list[str]) -> JSONObject:
+        """执行工具方法逻辑。"""
         self._require_app_key(app_key)
         if not isinstance(chart_ids, list) or not chart_ids:
             raise_tool_error(QingflowApiError.config_error("chart_ids must be a non-empty array"))
@@ -253,7 +283,9 @@ class QingbiReportTools(ToolBase):
             json_body={"appKey": app_key, "sortChartIdList": chart_ids},
         )
 
+    @tool_cn_name("报表字段列表")
     def qingbi_report_list_fields(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行工具方法逻辑。"""
         self._require_app_key(app_key)
         return self._request(
             profile,
@@ -265,7 +297,9 @@ class QingbiReportTools(ToolBase):
             result_transform=_extract_dataset_fields,
         )
 
+    @tool_cn_name("报表字段选项")
     def qingbi_report_list_field_options(self, *, profile: str, field_id: str, chart_id: str) -> JSONObject:
+        """执行工具方法逻辑。"""
         if not field_id:
             raise_tool_error(QingflowApiError.config_error("field_id is required"))
         path = f"/qingbi/charts/datasource/{chart_id}/question/option" if chart_id else "/qingbi/charts/datasource/question/option"
@@ -288,6 +322,7 @@ class QingbiReportTools(ToolBase):
         risk_target: str | None = None,
         **extra: JSONValue,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         def runner(session_profile, context):
             qingbi_context = BackendRequestContext(
                 base_url=_qingbi_base_url(context.base_url),
@@ -313,10 +348,12 @@ class QingbiReportTools(ToolBase):
         return self._run(profile, runner)
 
     def _require_app_key(self, app_key: str) -> None:
+        """执行内部辅助逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
 
     def _require_chart_id(self, chart_id: str) -> None:
+        """执行内部辅助逻辑。"""
         if not chart_id:
             raise_tool_error(QingflowApiError.config_error("chart_id is required"))