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

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.32
 ```
 
 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.32 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.32",
   "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.0b32"
 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`
 

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.0b32"

package/src/qingflow_mcp/server.py

@@ -17,6 +17,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 +94,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.
@@ -115,6 +124,7 @@ Avoid builder-side app or schema changes here.""",
     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_user.py

@@ -12,6 +12,7 @@ from .tools.auth_tools import AuthTools
 from .tools.directory_tools import DirectoryTools
 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 +82,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.
@@ -221,6 +230,7 @@ Avoid builder-side app or schema changes here.""",
     )
 
     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)