@josephyan/qingflow-app-builder-mcp 0.2.0-beta.4 → 0.2.0-beta.41

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,
@@ -260,19 +303,79 @@ class DirectoryTools(ToolBase):
         page_num: int,
         page_size: int,
     ) -> dict[str, Any]:
-        if not keyword:
-            raise_tool_error(QingflowApiError.config_error("keyword is required"))
+        if page_num <= 0:
+            raise_tool_error(QingflowApiError.config_error("page_num must be positive"))
+        if page_size <= 0:
+            raise_tool_error(QingflowApiError.config_error("page_size must be positive"))
+        normalized_keyword = keyword.strip()
+
+        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,
+                )
+                start = (page_num - 1) * page_size
+                page_items = items[start : start + page_size]
+                reported_total = None if truncated else len(items)
+                page_amount = None if truncated else ((len(items) + page_size - 1) // page_size if items else 0)
+                if truncated and page_items:
+                    page_amount = max(page_num + 1, (start + len(page_items) + page_size - 1) // page_size)
+                return {
+                    "profile": profile,
+                    "ws_id": session_profile.selected_ws_id,
+                    "request_route": self._request_route_payload(context),
+                    "items": page_items,
+                    "pagination": {
+                        "page": page_num,
+                        "page_size": page_size,
+                        "returned_items": len(page_items),
+                        "reported_total": reported_total,
+                        "page_amount": page_amount,
+                        "depth_scanned": deepest_depth + 1 if page_items else 0,
+                    },
+                }
+
+            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=raw.get("pagination", {}),
+                selection={"keyword": None},
+            )
 
         def runner(session_profile, context):
             result = self.backend.request(
                 "GET",
                 context,
                 "/contact/deptByPage",
-                params={"keyword": keyword, "pageNum": page_num, "pageSize": page_size},
+                params={"keyword": normalized_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": normalized_keyword},
+        )
 
     def directory_list_all_departments(
         self,
@@ -304,18 +407,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 +433,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 +471,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,

package/src/qingflow_mcp/tools/feedback_tools.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from mcp.server.fastmcp import FastMCP
+
+from ..backend_client import BackendClient
+from ..config import get_feedback_app_key, get_feedback_base_url, get_feedback_qsource_token, normalize_base_url
+from ..errors import QingflowApiError, raise_tool_error
+from ..json_types import JSONObject
+
+
+CATEGORY_MAP = {
+    "feature_request": "功能需求",
+    "bug_report": "问题反馈",
+    "ux_feedback": "体验建议",
+    "unsupported_scenario": "不支持场景",
+    "other": "其他",
+}
+
+IMPACT_SCOPE_MAP = {
+    "personal": "仅个人",
+    "small_team": "小范围团队",
+    "cross_team": "跨团队",
+    "global": "全局",
+}
+
+
+@dataclass(slots=True)
+class FeedbackTools:
+    backend: BackendClient
+    mcp_side: str
+
+    def register(self, mcp: FastMCP) -> None:
+        @mcp.tool()
+        def feedback_submit(
+            category: str = "",
+            title: str = "",
+            description: str = "",
+            expected_behavior: str | None = None,
+            actual_behavior: str | None = None,
+            impact_scope: str | None = None,
+            tool_name: str | None = None,
+            app_key: str | None = None,
+            record_id: str | int | None = None,
+            workflow_node_id: str | int | None = None,
+            note: str | None = None,
+        ) -> JSONObject:
+            """Submit product feedback to the Qingflow MCP team.
+
+            Use this when the current MCP capability is unsupported, awkward, or still cannot satisfy the user's need
+            after reasonable attempts. This helper writes through the internal q-source feedback intake, does not
+            require Qingflow login or workspace selection, and should be called only after explicit user confirmation.
+            """
+            return self.feedback_submit(
+                category=category,
+                title=title,
+                description=description,
+                expected_behavior=expected_behavior,
+                actual_behavior=actual_behavior,
+                impact_scope=impact_scope,
+                tool_name=tool_name,
+                app_key=app_key,
+                record_id=record_id,
+                workflow_node_id=workflow_node_id,
+                note=note,
+            )
+
+    def feedback_submit(
+        self,
+        *,
+        category: str,
+        title: str,
+        description: str,
+        expected_behavior: str | None,
+        actual_behavior: str | None,
+        impact_scope: str | None,
+        tool_name: str | None,
+        app_key: str | None,
+        record_id: str | int | None,
+        workflow_node_id: str | int | None,
+        note: str | None,
+    ) -> JSONObject:
+        qsource_token = get_feedback_qsource_token()
+        if not qsource_token:
+            raise_tool_error(
+                QingflowApiError(
+                    category="config",
+                    message=(
+                        "feedback_submit is not configured. Set "
+                        "feedback.qsource_token or QINGFLOW_MCP_FEEDBACK_QSOURCE_TOKEN first."
+                    ),
+                    details={"error_code": "FEEDBACK_NOT_CONFIGURED"},
+                )
+            )
+
+        base_url = get_feedback_base_url()
+        if not base_url:
+            raise_tool_error(
+                QingflowApiError.config_error(
+                    "feedback_submit requires a base_url. Configure feedback.base_url or default_base_url."
+                )
+            )
+
+        normalized_payload = self._build_payload(
+            category=category,
+            title=title,
+            description=description,
+            expected_behavior=expected_behavior,
+            actual_behavior=actual_behavior,
+            impact_scope=impact_scope,
+            tool_name=tool_name,
+            app_key=app_key,
+            record_id=record_id,
+            workflow_node_id=workflow_node_id,
+            note=note,
+        )
+
+        try:
+            response = self.backend.public_request_with_meta(
+                "POST",
+                base_url,
+                f"/qsource/{qsource_token}",
+                json_body=normalized_payload,
+                unwrap=True,
+                qf_version=None,
+            )
+        except QingflowApiError as exc:
+            raise_tool_error(exc)
+        result = response.data if isinstance(response.data, dict) else {}
+        feedback_request_id = result.get("requestId") if isinstance(result, dict) else None
+
+        return {
+            "ok": True,
+            "request_route": {
+                "base_url": normalize_base_url(base_url) or base_url,
+                "qf_version": None,
+                "qf_version_source": "not_applicable",
+            },
+            "submission_mode": "qsource_passive",
+            "feedback_target": {
+                "app_key": get_feedback_app_key(),
+                "mcp_side": self.mcp_side,
+            },
+            "normalized_payload": normalized_payload,
+            "feedback_request_id": feedback_request_id,
+        }
+
+    def _build_payload(
+        self,
+        *,
+        category: str,
+        title: str,
+        description: str,
+        expected_behavior: str | None,
+        actual_behavior: str | None,
+        impact_scope: str | None,
+        tool_name: str | None,
+        app_key: str | None,
+        record_id: str | int | None,
+        workflow_node_id: str | int | None,
+        note: str | None,
+    ) -> JSONObject:
+        payload: JSONObject = {
+            "title": self._require_text("title", title),
+            "category": self._normalize_label("category", category, CATEGORY_MAP, required=True),
+            "description": self._require_text("description", description),
+            "submit_method": "AI代提",
+            "status": "待处理",
+            "mcp_side": self.mcp_side,
+        }
+
+        optional_text = {
+            "expected_result": expected_behavior,
+            "actual_behavior": actual_behavior,
+            "tool_name": tool_name,
+            "app_key": app_key,
+            "note": note,
+        }
+        for key, value in optional_text.items():
+            normalized = self._normalize_optional_text(value)
+            if normalized is not None:
+                payload[key] = normalized
+
+        if impact_scope is not None and str(impact_scope).strip():
+            payload["impact_scope"] = self._normalize_label("impact_scope", impact_scope, IMPACT_SCOPE_MAP, required=False)
+
+        if record_id is not None and str(record_id).strip():
+            payload["record_id"] = str(record_id).strip()
+        if workflow_node_id is not None and str(workflow_node_id).strip():
+            payload["workflow_node_id"] = str(workflow_node_id).strip()
+
+        return payload
+
+    def _normalize_label(self, field: str, value: str, mapping: dict[str, str], *, required: bool) -> str:
+        text = str(value or "").strip()
+        if not text:
+            if required:
+                raise_tool_error(QingflowApiError.config_error(f"{field} is required"))
+            return ""
+
+        canonical = text.lower()
+        if canonical in mapping:
+            return mapping[canonical]
+        if text in mapping.values():
+            return text
+        supported_values = list(mapping.keys()) + list(mapping.values())
+        raise_tool_error(
+            QingflowApiError(
+                category="config",
+                message=f"{field} must be one of the supported canonical values or labels",
+                details={
+                    "error_code": "FEEDBACK_INVALID_INPUT",
+                    "field": field,
+                    "supported_values": supported_values,
+                },
+            )
+        )
+
+    def _require_text(self, field: str, value: str) -> str:
+        normalized = str(value or "").strip()
+        if not normalized:
+            raise_tool_error(QingflowApiError.config_error(f"{field} is required"))
+        return normalized
+
+    def _normalize_optional_text(self, value: str | None) -> str | None:
+        if value is None:
+            return None
+        normalized = str(value).strip()
+        return normalized or None

package/src/qingflow_mcp/tools/file_tools.py

@@ -178,6 +178,7 @@ class FileTools(ToolBase):
                 "download_url": download_url,
                 "attachment_value": {
                     "value": download_url,
+                    "otherInfo": file_name,
                     "name": file_name,
                 },
                 "comment_file_info": {