@josephyan/qingflow-app-user-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-user-mcp@0.2.0-beta.31
+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.31 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.31",
+  "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.0b31"
+version = "0.2.0b33"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

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

@@ -19,16 +19,20 @@ Route to exactly one of these specialized paths:
 1. Record CRUD  
    Switch to [$qingflow-record-crud](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-crud/SKILL.md)
 
-2. Analysis  
+2. Task workflow operations  
+   Switch to [$qingflow-task-ops](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-task-ops/SKILL.md)
+
+3. Analysis  
    Switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
 
-3. MCP connection / auth / workspace selection  
+4. MCP connection / auth / workspace selection  
    Switch to [$qingflow-mcp-setup](/Users/yanqidong/.codex/skills/qingflow-mcp-setup/SKILL.md)
 
 ## Routing Rules
 
 - If the user does not know the target `app_key`, discover apps first with `app_list` or `app_search`, then route to the specialized skill
 - If the task is about browsing, reading, creating, updating, deleting, attachments, relations, subtable writes, or member/department-field candidate lookup, switch to `$qingflow-record-crud`
+- If the task is about todo discovery, task context, approval actions, rollback or transfer, associated report review, or workflow log review, switch to `$qingflow-task-ops`
 - If the task is about grouped distributions, ratios, rankings, trends, insights, or any final statistical conclusion, switch to `$qingflow-record-analysis`
 - If the MCP is not connected, authenticated, or bound to the right workspace, switch to `$qingflow-mcp-setup`
 
@@ -37,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/skills/qingflow-task-ops/SKILL.md

@@ -1,82 +1,62 @@
 ---
 name: qingflow-task-ops
-description: Use Qingflow task center, workflow usage actions, comments, and directory lookup after the MCP is already connected and authenticated. Do not use this skill for record CRUD or final statistical analysis.
+description: Use Qingflow todo discovery, workflow task context, associated approval context, workflow logs, and unified task actions after the MCP is already connected and authenticated. Do not use this skill for record CRUD or final statistical analysis.
 metadata:
-  short-description: Qingflow task center and workflow operations
+  short-description: Qingflow task workflow context and actions
 ---
 
 # Qingflow Task Ops
 
 ## Overview
 
-This skill is for task-center and workflow usage operations only.
+This skill is for task workflow operations only.
 Assumes MCP is connected, authenticated, and on the correct workspace.
 
 ## Default Paths
 
 Use exactly one of these default paths:
 
-1. Task headline counts  
-   `task_summary`
-
-2. Flat task browsing  
+1. Find target todos  
    `task_list`
 
-3. Grouped workload buckets  
-   `task_facets`
+2. Read one task context  
+   `task_list -> exact target -> task_get`
 
-4. Task or workflow action  
-   `task_list / task_facets -> exact target -> task_* action`
+3. Read associated approval context  
+   `task_get -> task_associated_report_detail_get` or `task_workflow_log_get`
 
-5. Comments and directory support  
-   `record_get -> record_comment_*` or `directory_*`
+4. Execute workflow action  
+   `task_list -> exact target -> task_get -> task_action_execute`
 
 ## Core Tools
 
-- `task_summary`
 - `task_list`
-- `task_facets`
-- `task_mark_read`
-- `task_mark_all_cc_read`
-- `task_urge`
-- `task_approve`
-- `task_reject`
-- `task_rollback_candidates`
-- `task_rollback`
-- `task_transfer_candidates`
-- `task_transfer`
-- `record_comment_write`
-- `record_comment_list`
-- `record_comment_mentions`
-- `record_comment_mark_read`
+- `task_get`
+- `task_action_execute`
+- `task_associated_report_detail_get`
+- `task_workflow_log_get`
 
 ## Supporting Tools
 
-- `directory_search`
-- `directory_list_internal_users`
-- `directory_list_all_internal_users`
-- `directory_list_internal_departments`
-- `directory_list_all_departments`
-- `directory_list_sub_departments`
-- `directory_list_external_members`
-- `record_get`
+- `app_list`
+- `app_search`
 
 ## Standard Operating Order
 
 1. Ensure auth exists
 2. Ensure workspace is selected
-3. Confirm target app and whether the task is task browse / grouped workload / comment / workflow action
-4. Use `task_summary`, `task_list`, or `task_facets` to locate the exact target first
-5. If a workflow action is required, identify the exact `task_id`, `record_id`, and `workflow_node_id` whenever practical
-6. Use directory tools only when member/department lookup is needed to support the action
-7. For production actions, read current task or record state first whenever practical
-8. After actions, report the affected `task_id`, `record_id`, or returned item count
+3. Discover the exact target with `task_list`
+4. Read node context with `task_get`
+5. Before giving any approval recommendation, read `task_workflow_log_get`
+6. If `task_get` returns any `associated_reports`, read every visible report through `task_associated_report_detail_get`
+7. Give an approval recommendation only after reviewing the node context, workflow log, and associated report details
+8. Wait for explicit user confirmation before `task_action_execute`
+9. Execute through `task_action_execute`
+10. After actions, report the exact `app_key`, `record_id`, `workflow_node_id`, and executed action
 
 ## Task-Center Rules
 
-- Use `task_summary` for headline counts
 - Use `task_list` for flat browsing
-- Use `task_facets` for grouped worksheet or workflow-node buckets
 - `task_box` must be one of:
   - `todo`
   - `initiated`
@@ -93,30 +73,39 @@ Use exactly one of these default paths:
   - `due_soon`
   - `unread`
   - `ended`
-- Task counts are task-center counts, not record counts
-- If the user asks for workload by worksheet or node, use `task_facets`
-- If a result set is truncated, describe it as `已返回分组中` or `主要分组`
+- `task_list` is the only public task discovery path in this MCP surface
+- Treat `task_id` as a locator only; the action primary key is `app_key + record_id + workflow_node_id`
+- Default box usage:
+  - `todo`: `task_list -> task_get -> task_workflow_log_get / task_associated_report_detail_get -> recommendation -> explicit user confirmation -> task_action_execute`
+  - `initiated`: `task_list -> record_get`
+  - `done`: `task_list -> record_get`
+  - `cc`: `task_list -> record_get`
+- Treat `initiated`, `done`, and `cc` primarily as list-plus-record-detail flows, not task action flows
 
 ## Workflow Usage Actions
 
-- Find the exact target first
-- For approve or reject, identify the exact `workflow_node_id` first; prefer task-center results or current audit info
-- Avoid workflow actions on ambiguous tasks or records
-- For rollback or transfer, fetch candidates first
-- Summarize the final action and target task ids or record ids
-
-## Comments and Directory
-
-- Use `record_comment_write` only after the exact `record_id` is known
-- Use `record_comment_mentions` to resolve mention candidates before building complex comment payloads
-- Use `directory_search` for fuzzy member/department lookup
-- Use `directory_list_all_internal_users` and `directory_list_all_departments` only when the user explicitly wants a complete export
+- `task_get.capabilities.available_actions` is the source of truth for v1 executable actions
+- Current public actions are:
+  - `approve`
+  - `reject`
+  - `rollback`
+  - `transfer`
+  - `urge`
+- Before any approve/reject/rollback/transfer recommendation, always review `task_workflow_log_get` when `task_get.visibility.audit_record_visible=true`
+- If `task_get` returns visible `associated_reports`, review each one with `task_associated_report_detail_get`; do not rely on report summary alone
+- Do not give an approval recommendation based only on `task_get`
+- Do not execute `task_action_execute` until the user explicitly confirms the chosen action
+- Avoid actions on ambiguous tasks or records
+- Summarize the final action and the exact `app_key / record_id / workflow_node_id`
 
 ## Response Interpretation
 
-- `task_summary` gives headline counts only
-- `task_list` returns flat task rows, not grouped workload conclusions
-- `task_facets` is the only default grouped workload path
+- `task_list` returns normalized todo rows and is the only default discovery path
+- `task_get` returns node context summary, not full historical report data
+- `task_associated_report_detail_get` may return either:
+  - `result_type=view_list`
+  - `result_type=chart_data`
+- `task_workflow_log_get` returns workflow log detail only when the node grants log visibility
 - Treat `request_route` as the source of truth for live route debugging
 - If only part of the requested work is completed, explicitly disclose which parts are done and which are not
 

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)