@josephyan/qingflow-app-user-mcp 0.2.0-beta.32 → 0.2.0-beta.33

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.2.0-beta.32",
+  "version": "0.2.0-beta.33",
   "description": "Operational end-user MCP for Qingflow records, tasks, comments, and directory workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

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

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

@@ -41,6 +41,7 @@ Route to exactly one of these specialized paths:
 - prefer canonical app ids, record ids, task ids, and workflow node ids over guessed names
 - if a field or target is still ambiguous after schema/task lookup, ask the user to confirm from a short candidate list instead of guessing
 - if the task can stay read-only, do not write or act
+- 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
 
 ## Resources
 

package/src/qingflow_mcp/__init__.py

@@ -2,4 +2,4 @@ from __future__ import annotations
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.0b32"
+__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
@@ -116,11 +117,20 @@ 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)

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,6 +10,7 @@ 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
@@ -104,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()
@@ -112,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(
@@ -227,8 +237,9 @@ 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)

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