@josephyan/qingflow-app-builder-mcp 0.2.0-beta.31 → 0.2.0-beta.33

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.31
+npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.33
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.31 qingflow-app-builder-mcp
+npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.33 qingflow-app-builder-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-builder-mcp",
-  "version": "0.2.0-beta.31",
+  "version": "0.2.0-beta.33",
   "description": "Builder MCP for Qingflow app/package/system design and staged solution workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "0.2.0b31"
+version = "0.2.0b33"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/skills/qingflow-app-builder/SKILL.md

@@ -63,6 +63,7 @@ Note:
   - use `member_search` only when the user explicitly names members or no stable role exists
   - use `role_create` when the business owner wants a reusable directory role instead of hard-coded members
 - On any `VALIDATION_ERROR`, inspect `suggested_next_call` first and prefer reusing the MCP-normalized arguments over re-guessing from the original natural language.
+- If the current MCP capability is unsupported, the workflow is awkward, or the user's need still cannot be satisfied after reasonable use, summarize the gap, ask whether to submit feedback, and call `feedback_submit` only after explicit user confirmation.
 
 Default policy:
 

package/src/qingflow_mcp/__init__.py

@@ -2,4 +2,4 @@ from __future__ import annotations
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.0b31"
+__version__ = "0.2.0b33"

package/src/qingflow_mcp/config.py

@@ -12,6 +12,7 @@ DEFAULT_USER_AGENT = "qingflow-mcp/1.0"
 DEFAULT_RECORD_LIST_TYPE = 8
 ATTACHMENT_QUESTION_TYPE = 13
 DEFAULT_BASE_URL = "https://qingflow.com/api"
+DEFAULT_FEEDBACK_APP_KEY = "e0d017kju002"
 
 
 def get_mcp_home() -> Path:
@@ -136,6 +137,43 @@ def get_default_qf_version() -> str | None:
     return normalized or None
 
 
+def get_feedback_qsource_token() -> str | None:
+    """获取反馈 q-source 被动入口 token"""
+    value = get_config_value(
+        "feedback.qsource_token",
+        env_var="QINGFLOW_MCP_FEEDBACK_QSOURCE_TOKEN",
+        default=None,
+    )
+    if value is None:
+        return None
+    normalized = str(value).strip()
+    return normalized or None
+
+
+def get_feedback_base_url() -> str | None:
+    """获取反馈 q-source 使用的 base URL"""
+    value = get_config_value(
+        "feedback.base_url",
+        env_var="QINGFLOW_MCP_FEEDBACK_BASE_URL",
+        default=None,
+    )
+    if value is None:
+        return get_default_base_url()
+    normalized = normalize_base_url(value)
+    return normalized or get_default_base_url()
+
+
+def get_feedback_app_key() -> str:
+    """获取内部反馈表 app_key"""
+    value = get_config_value(
+        "feedback.app_key",
+        env_var="QINGFLOW_MCP_FEEDBACK_APP_KEY",
+        default=DEFAULT_FEEDBACK_APP_KEY,
+    )
+    normalized = str(value or "").strip()
+    return normalized or DEFAULT_FEEDBACK_APP_KEY
+
+
 def get_timeout_seconds() -> float:
     """获取 HTTP 超时秒数"""
     value = get_config_value(

package/src/qingflow_mcp/server.py

@@ -8,6 +8,7 @@ from .backend_client import BackendClient
 from .session_store import SessionStore
 from .tools.app_tools import AppTools
 from .tools.auth_tools import AuthTools
+from .tools.feedback_tools import FeedbackTools
 from .tools.file_tools import FileTools
 from .tools.package_tools import PackageTools
 from .tools.navigation_tools import NavigationTools
@@ -17,6 +18,7 @@ from .tools.qingbi_report_tools import QingbiReportTools
 from .tools.record_tools import RecordTools
 from .tools.role_tools import RoleTools
 from .tools.solution_tools import SolutionTools
+from .tools.task_context_tools import TaskContextTools
 from .tools.view_tools import ViewTools
 from .tools.workflow_tools import WorkflowTools
 from .tools.workspace_tools import WorkspaceTools
@@ -93,6 +95,14 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - If a member or department field id is known but candidate ids are not, use `record_member_candidates` or `record_department_candidates` before `record_write`.
 - For default-all member or department fields, prefer those field candidate tools instead of starting with `directory_*`.
 
+## Task Workflow Path
+
+`task_list -> task_get -> task_action_execute`
+
+- Use `task_associated_report_detail_get` for associated view or report details.
+- Use `task_workflow_log_get` for full workflow log history.
+- Task actions operate on `app_key + record_id + workflow_node_id`, not `task_id`.
+
 ## Time Handling
 
 Normalize relative dates before building DSL.
@@ -107,14 +117,24 @@ Default to `prod` unless the user explicitly specifies `test`.
 
 ## Constraints
 
-Avoid builder-side app or schema changes here.""",
+Avoid builder-side app or schema changes here.
+
+## Feedback Path
+
+If the current MCP capability is unsupported, the workflow is awkward, or the user's need still cannot be satisfied after reasonable use, offer to submit product feedback.
+
+- First summarize what is still not working
+- Ask the user whether to submit feedback
+- Call `feedback_submit` only after explicit user confirmation""",
     )
     sessions = SessionStore()
     backend = BackendClient()
     AuthTools(sessions, backend).register(server)
+    FeedbackTools(backend, mcp_side="通用").register(server)
     WorkspaceTools(sessions, backend).register(server)
     FileTools(sessions, backend).register(server)
     RecordTools(sessions, backend).register(server)
+    TaskContextTools(sessions, backend).register(server)
     RoleTools(sessions, backend).register(server)
     AppTools(sessions, backend).register(server)
     QingbiReportTools(sessions, backend).register(server)

package/src/qingflow_mcp/server_app_builder.py

@@ -7,6 +7,7 @@ from .config import DEFAULT_PROFILE
 from .session_store import SessionStore
 from .tools.ai_builder_tools import AiBuilderTools
 from .tools.auth_tools import AuthTools
+from .tools.feedback_tools import FeedbackTools
 from .tools.file_tools import FileTools
 from .tools.workspace_tools import WorkspaceTools
 
@@ -26,7 +27,8 @@ def build_builder_server() -> FastMCP:
             "Use package_attach_app to attach apps to packages, and app_publish_verify for explicit final publish verification. "
             "For workflow edits, prefer preset plus explicit patching over generating a full custom graph from scratch, and declare node assignees and editable fields explicitly. "
             "If builder writes are blocked by the current user's own edit lock, use app_release_edit_lock_if_mine with the lock owner details from the failed result. "
-            "Do not handcraft internal solution payloads or rely on build_id/stage/repair."
+            "Do not handcraft internal solution payloads or rely on build_id/stage/repair. "
+            "If the current MCP capability is unsupported, the workflow is awkward, or the user's need still cannot be satisfied after reasonable use, first summarize the gap, ask whether to submit feedback, and call feedback_submit only after explicit user confirmation."
         ),
     )
     sessions = SessionStore()
@@ -35,6 +37,7 @@ def build_builder_server() -> FastMCP:
     workspace = WorkspaceTools(sessions, backend)
     files = FileTools(sessions, backend)
     ai_builder = AiBuilderTools(sessions, backend)
+    feedback = FeedbackTools(backend, mcp_side="App Builder MCP")
 
     @server.tool()
     def auth_login(
@@ -120,6 +123,8 @@ def build_builder_server() -> FastMCP:
             file_related_url=file_related_url,
         )
 
+    feedback.register(server)
+
     @server.tool()
     def package_list(profile: str = DEFAULT_PROFILE, trial_status: str = "all") -> dict:
         return ai_builder.package_list(profile=profile, trial_status=trial_status)

package/src/qingflow_mcp/server_app_user.py

@@ -10,8 +10,10 @@ from .session_store import SessionStore
 from .tools.app_tools import AppTools
 from .tools.auth_tools import AuthTools
 from .tools.directory_tools import DirectoryTools
+from .tools.feedback_tools import FeedbackTools
 from .tools.file_tools import FileTools
 from .tools.record_tools import RecordTools
+from .tools.task_context_tools import TaskContextTools
 from .tools.workspace_tools import WorkspaceTools
 
 
@@ -81,6 +83,14 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - If a member or department field id is known but candidate ids are not, use `record_member_candidates` or `record_department_candidates` before `record_write`.
 - For default-all member or department fields, prefer those field candidate tools instead of starting with `directory_*`.
 
+## Task Workflow Path
+
+`task_list -> task_get -> task_action_execute`
+
+- Use `task_associated_report_detail_get` for associated view or report details.
+- Use `task_workflow_log_get` for full workflow log history.
+- Task actions operate on `app_key + record_id + workflow_node_id`, not `task_id`.
+
 ## Time Handling
 
 Normalize relative dates before building DSL.
@@ -95,7 +105,15 @@ Default to `prod` unless the user explicitly specifies `test`.
 
 ## Constraints
 
-Avoid builder-side app or schema changes here.""",
+Avoid builder-side app or schema changes here.
+
+## Feedback Path
+
+If the current MCP capability is unsupported, the workflow is awkward, or the user's need still cannot be satisfied after reasonable use, offer to submit product feedback.
+
+- First summarize what is still not working
+- Ask the user whether to submit feedback
+- Call `feedback_submit` only after explicit user confirmation""",
     )
     sessions = SessionStore()
     backend = BackendClient()
@@ -103,6 +121,7 @@ Avoid builder-side app or schema changes here.""",
     apps = AppTools(sessions, backend)
     workspace = WorkspaceTools(sessions, backend)
     files = FileTools(sessions, backend)
+    feedback = FeedbackTools(backend, mcp_side="App User MCP")
 
     @server.tool()
     def auth_login(
@@ -218,9 +237,11 @@ Avoid builder-side app or schema changes here.""",
             bucket_type=bucket_type,
             path_id=path_id,
             file_related_url=file_related_url,
-    )
+        )
 
+    feedback.register(server)
     RecordTools(sessions, backend).register(server)
+    TaskContextTools(sessions, backend).register(server)
     DirectoryTools(sessions, backend).register(server)
 
     return server

package/src/qingflow_mcp/tools/approval_tools.py

@@ -611,9 +611,11 @@ class ApprovalTools(ToolBase):
         self._normalize_alias(body, "formId", "form_id")
 
         node_id = self._extract_node_id(body)
-        body["nodeId"] = node_id
+        body["nodeId"] = self._resolve_actionable_node_id(context, app_key, apply_id, node_id)
         body["applyId"] = self._match_or_fill_int(body, field_name="applyId", expected_value=apply_id)
         body["formId"] = self._resolve_form_id(profile, context, app_key, explicit_form_id=body.get("formId"))
+        if body.get("answers") is None:
+            body["answers"] = self._fetch_current_todo_answers(context, app_key, apply_id, body["nodeId"])
 
         self._validate_approval_payload(body)
         return body
@@ -672,6 +674,54 @@ class ApprovalTools(ToolBase):
         elif alias_value is not None and payload.get(canonical_key) != alias_value:
             raise_tool_error(QingflowApiError.config_error(f"payload.{canonical_key} and payload.{alias_key} must match when both are provided"))
 
+    def _resolve_actionable_node_id(self, context, app_key: str, apply_id: int, node_id: int) -> int:  # type: ignore[no-untyped-def]
+        infos = self.backend.request(
+            "GET",
+            context,
+            f"/app/{app_key}/apply/{apply_id}/auditInfo",
+            params={"type": 1},
+        )
+        if not isinstance(infos, list) or not infos:
+            raise_tool_error(
+                QingflowApiError.config_error(
+                    f"apply_id={apply_id} is not currently actionable for the logged-in user in todo list"
+                )
+            )
+        actionable_node_ids = {
+            candidate
+            for item in infos
+            if isinstance(item, dict)
+            for candidate in (item.get("auditNodeId"), item.get("nodeId"))
+            if isinstance(candidate, int) and candidate > 0
+        }
+        if node_id not in actionable_node_ids:
+            raise_tool_error(
+                QingflowApiError.config_error(
+                    f"payload.nodeId={node_id} is not an actionable todo node for apply_id={apply_id}"
+                )
+            )
+        return node_id
+
+    def _fetch_current_todo_answers(self, context, app_key: str, apply_id: int, node_id: int) -> list[dict[str, Any]]:  # type: ignore[no-untyped-def]
+        detail = self.backend.request(
+            "GET",
+            context,
+            f"/app/{app_key}/apply/{apply_id}",
+            params={"role": 3, "listType": 1, "auditNodeId": node_id},
+        )
+        answers = detail.get("answers") if isinstance(detail, dict) else None
+        if not isinstance(answers, list):
+            raise_tool_error(
+                QingflowApiError.config_error(
+                    f"cannot resolve current answers for apply_id={apply_id} nodeId={node_id}"
+                )
+            )
+        normalized_answers: list[dict[str, Any]] = []
+        for item in answers:
+            if isinstance(item, dict):
+                normalized_answers.append(dict(item))
+        return normalized_answers
+
     def _validate_approval_payload(self, payload: dict[str, Any]) -> None:
         self._reject_unsupported_fields(payload)
         if not isinstance(payload.get("formId"), int) or payload["formId"] <= 0:
@@ -680,6 +730,9 @@ class ApprovalTools(ToolBase):
             raise_tool_error(QingflowApiError.config_error("payload.applyId must be a positive integer"))
         if not isinstance(payload.get("nodeId"), int) or payload["nodeId"] <= 0:
             raise_tool_error(QingflowApiError.config_error("payload.nodeId must be a positive integer"))
+        answers = payload.get("answers")
+        if answers is not None and not isinstance(answers, list):
+            raise_tool_error(QingflowApiError.config_error("payload.answers must be an array when provided"))
 
     def _validate_audit_payload(self, payload: dict[str, Any], *, require_uid: bool = False) -> None:
         self._reject_unsupported_fields(payload)

package/src/qingflow_mcp/tools/feedback_tools.py

@@ -0,0 +1,224 @@
+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:
+            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/record_tools.py

@@ -3367,7 +3367,10 @@ class RecordTools(ToolBase):
             for item in match_rules:
                 if not isinstance(item, dict):
                     continue
-                queries.extend(_normalize_list_query_rules(item))
+                item_queries = _normalize_list_query_rules(item)
+                if item_queries:
+                    queries.extend(item_queries)
+                    continue
                 normalized_match_rules.extend(_normalize_list_match_rules(item))
             if queries:
                 body["queries"] = queries