@josephyan/qingflow-app-user-mcp 0.2.0-beta.994 → 0.2.0-beta.996

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.2.0-beta.994",
+  "version": "0.2.0-beta.996",
   "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.0b994"
+version = "0.2.0b996"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/src/qingflow_mcp/__init__.py

@@ -5,7 +5,7 @@ from pathlib import Path
 
 __all__ = ["__version__"]
 
-_FALLBACK_VERSION = "0.2.0b994"
+_FALLBACK_VERSION = "0.2.0b996"
 
 
 def _resolve_local_pyproject_version() -> str | None:

package/src/qingflow_mcp/cli/commands/task.py

@@ -23,27 +23,44 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     list_parser.add_argument("--page-size", type=int, default=20)
     list_parser.set_defaults(handler=_handle_list, format_hint="task_list")
 
-    get = task_subparsers.add_parser("get", help="读取待办详情")
-    get.add_argument("--app-key", required=True)
-    get.add_argument("--record-id", required=True)
-    get.add_argument("--workflow-node-id", required=True, type=int)
+    get = task_subparsers.add_parser("get", help="读取待办详情；推荐直接传 --task-id")
+    get.add_argument("--task-id")
+    get.add_argument("--app-key")
+    get.add_argument("--record-id")
+    get.add_argument("--workflow-node-id", type=int)
     get.add_argument("--include-candidates", action=argparse.BooleanOptionalAction, default=True)
     get.add_argument("--include-associated-reports", action=argparse.BooleanOptionalAction, default=True)
     get.set_defaults(handler=_handle_get, format_hint="task_get")
 
     action = task_subparsers.add_parser("action", help="执行待办动作")
-    action.add_argument("--app-key", required=True)
-    action.add_argument("--record-id", required=True)
-    action.add_argument("--workflow-node-id", required=True, type=int)
+    action.add_argument("--task-id")
+    action.add_argument("--app-key")
+    action.add_argument("--record-id")
+    action.add_argument("--workflow-node-id", type=int)
     action.add_argument("--action", required=True)
     action.add_argument("--payload-file")
     action.add_argument("--fields-file")
-    action.set_defaults(handler=_handle_action, format_hint="")
+    action.set_defaults(
+        handler=_handle_action,
+        format_hint="task_action_execute",
+        hide_effective_context_line=True,
+    )
 
-    log = task_subparsers.add_parser("log", help="读取流程日志")
-    log.add_argument("--app-key", required=True)
-    log.add_argument("--record-id", required=True)
-    log.add_argument("--workflow-node-id", required=True, type=int)
+    report = task_subparsers.add_parser("report", help="读取待办关联报表详情；推荐直接传 --task-id")
+    report.add_argument("--task-id")
+    report.add_argument("--app-key")
+    report.add_argument("--record-id")
+    report.add_argument("--workflow-node-id", type=int)
+    report.add_argument("--report-id", required=True, type=int)
+    report.add_argument("--page", type=int, default=1)
+    report.add_argument("--page-size", type=int, default=20)
+    report.set_defaults(handler=_handle_report, format_hint="task_associated_report_detail_get")
+
+    log = task_subparsers.add_parser("log", help="读取流程日志；推荐直接传 --task-id")
+    log.add_argument("--task-id")
+    log.add_argument("--app-key")
+    log.add_argument("--record-id")
+    log.add_argument("--workflow-node-id", type=int)
     log.set_defaults(handler=_handle_log, format_hint="")
 
 
@@ -61,22 +78,32 @@ def _handle_list(args: argparse.Namespace, context: CliContext) -> dict:
 
 
 def _handle_get(args: argparse.Namespace, context: CliContext) -> dict:
+    if not args.task_id and not (args.app_key and args.record_id and args.workflow_node_id):
+        raise RuntimeError(
+            '{"category":"config","message":"task get requires --task-id, or --app-key together with --record-id and --workflow-node-id"}'
+        )
     return context.task.task_get(
         profile=args.profile,
-        app_key=args.app_key,
-        record_id=args.record_id,
-        workflow_node_id=args.workflow_node_id,
+        task_id=args.task_id,
+        app_key=args.app_key or "",
+        record_id=args.record_id or "",
+        workflow_node_id=int(args.workflow_node_id or 0),
         include_candidates=bool(args.include_candidates),
         include_associated_reports=bool(args.include_associated_reports),
     )
 
 
 def _handle_action(args: argparse.Namespace, context: CliContext) -> dict:
+    if not args.task_id and not (args.app_key and args.record_id and args.workflow_node_id):
+        raise RuntimeError(
+            '{"category":"config","message":"task action requires --task-id, or --app-key together with --record-id and --workflow-node-id"}'
+        )
     return context.task.task_action_execute(
         profile=args.profile,
-        app_key=args.app_key,
-        record_id=args.record_id,
-        workflow_node_id=args.workflow_node_id,
+        task_id=args.task_id,
+        app_key=args.app_key or "",
+        record_id=args.record_id or "",
+        workflow_node_id=int(args.workflow_node_id or 0),
         action=args.action,
         payload=load_object_arg(args.payload_file, option_name="--payload-file") or {},
         fields=load_object_arg(args.fields_file, option_name="--fields-file") or {},
@@ -84,9 +111,31 @@ def _handle_action(args: argparse.Namespace, context: CliContext) -> dict:
 
 
 def _handle_log(args: argparse.Namespace, context: CliContext) -> dict:
+    if not args.task_id and not (args.app_key and args.record_id and args.workflow_node_id):
+        raise RuntimeError(
+            '{"category":"config","message":"task log requires --task-id, or --app-key together with --record-id and --workflow-node-id"}'
+        )
     return context.task.task_workflow_log_get(
         profile=args.profile,
-        app_key=args.app_key,
-        record_id=args.record_id,
-        workflow_node_id=args.workflow_node_id,
+        task_id=args.task_id,
+        app_key=args.app_key or "",
+        record_id=args.record_id or "",
+        workflow_node_id=int(args.workflow_node_id or 0),
+    )
+
+
+def _handle_report(args: argparse.Namespace, context: CliContext) -> dict:
+    if not args.task_id and not (args.app_key and args.record_id and args.workflow_node_id):
+        raise RuntimeError(
+            '{"category":"config","message":"task report requires --task-id, or --app-key together with --record-id and --workflow-node-id"}'
+        )
+    return context.task.task_associated_report_detail_get(
+        profile=args.profile,
+        task_id=args.task_id,
+        app_key=args.app_key or "",
+        record_id=args.record_id or "",
+        workflow_node_id=int(args.workflow_node_id or 0),
+        report_id=int(args.report_id),
+        page=int(args.page),
+        page_size=int(args.page_size),
     )

package/src/qingflow_mcp/cli/formatters.py

@@ -177,17 +177,15 @@ def _format_task_list(result: dict[str, Any]) -> str:
     for item in items:
         if not isinstance(item, dict):
             continue
-        lines.append(
-            "- "
-            + " / ".join(
-                [
-                    str(item.get("app_key") or "-"),
-                    str(item.get("record_id") or "-"),
-                    str(item.get("workflow_node_id") or "-"),
-                    str(item.get("workflow_node_name") or "-"),
-                ]
-            )
-        )
+        header_parts = [
+            str(item.get("task_id") or "-"),
+            str(item.get("app_name") or item.get("app_key") or "-"),
+            str(item.get("workflow_node_name") or "-"),
+        ]
+        apply_time = item.get("apply_time")
+        if apply_time not in (None, ""):
+            header_parts.append(str(apply_time))
+        lines.append("- " + " / ".join(header_parts))
         summary_fields = item.get("summary_fields") if isinstance(item.get("summary_fields"), list) else []
         for summary in summary_fields:
             if not isinstance(summary, dict):
@@ -206,15 +204,20 @@ def _format_task_get(result: dict[str, Any]) -> str:
     extras = data.get("extras") if isinstance(data.get("extras"), dict) else {}
     initiator = task.get("initiator") if isinstance(task.get("initiator"), dict) else {}
     initiator_label = initiator.get("displayName") or initiator.get("email") or "-"
-    lines = [
-        f"Task: {task.get('app_key') or '-'} / {task.get('record_id') or '-'} / {task.get('workflow_node_id') or '-'}",
-        f"Node: {task.get('workflow_node_name') or '-'}",
-        f"App: {task.get('app_name') or '-'}",
-        f"Initiator: {initiator_label}",
-        f"Apply Status: {record_summary.get('apply_status')}",
-        f"Available Actions: {', '.join(str(item) for item in available_actions) or '-'}",
-        f"Editable Fields: {len(editable_fields)}",
-    ]
+    lines = []
+    if task.get("task_id") not in (None, ""):
+        lines.append(f"Task ID: {task.get('task_id')}")
+    lines.extend(
+        [
+            f"Locator: {task.get('app_key') or '-'} / {task.get('record_id') or '-'} / {task.get('workflow_node_id') or '-'}",
+            f"Node: {task.get('workflow_node_name') or '-'}",
+            f"App: {task.get('app_name') or '-'}",
+            f"Initiator: {initiator_label}",
+            f"Apply Status: {record_summary.get('apply_status')}",
+            f"Available Actions: {', '.join(str(item) for item in available_actions) or '-'}",
+            f"Editable Fields: {len(editable_fields)}",
+        ]
+    )
     core_fields = record_summary.get("core_fields") if isinstance(record_summary.get("core_fields"), dict) else {}
     if core_fields:
         lines.append("Core Fields:")
@@ -246,6 +249,72 @@ def _format_task_get(result: dict[str, Any]) -> str:
     return "\n".join(lines) + "\n"
 
 
+def _format_task_action(result: dict[str, Any]) -> str:
+    data = result.get("data") if isinstance(result.get("data"), dict) else {}
+    action = str(data.get("action") or "").strip().lower()
+    status = str(result.get("status") or "").strip().lower()
+
+    if status == "failed" or result.get("ok") is False:
+        lines = [_task_action_failure_label(action)]
+        reason = _task_action_failure_reason(result)
+        if reason:
+            lines.append(f"原因：{reason}")
+        debug_lines = _task_action_debug_lines(result)
+        if debug_lines:
+            lines.append("调试信息：")
+            lines.extend(f"- {line}" for line in debug_lines)
+        return "\n".join(lines) + "\n"
+
+    if status == "partial_success":
+        lines = [_task_action_success_label(action)]
+        lines.append(f"说明：{_task_action_partial_success_message(result)}")
+        return "\n".join(lines) + "\n"
+
+    return _task_action_success_label(action) + "\n"
+
+
+def _format_task_associated_report_detail(result: dict[str, Any]) -> str:
+    data = result.get("data") if isinstance(result.get("data"), dict) else {}
+    selection = data.get("selection") if isinstance(data.get("selection"), dict) else {}
+    result_type = str(data.get("result_type") or "-")
+    context = data.get("context") if isinstance(data.get("context"), dict) else {}
+    lines = []
+    if selection.get("task_id") not in (None, ""):
+        lines.append(f"Task ID: {selection.get('task_id')}")
+    lines.extend(
+        [
+            f"Report: {selection.get('chart_name') or '-'} ({selection.get('report_id') or '-'})",
+            f"Type: {result_type}",
+        ]
+    )
+    if result_type == "view_list":
+        result_payload = data.get("result") if isinstance(data.get("result"), dict) else {}
+        items = result_payload.get("items") if isinstance(result_payload.get("items"), list) else []
+        lines.append(f"Returned Records: {len(items)}")
+        for item in items[:10]:
+            if isinstance(item, dict):
+                lines.append(json.dumps(item, ensure_ascii=False))
+        if len(items) > 10:
+            lines.append(f"... {len(items) - 10} more")
+    elif result_type == "chart_data":
+        result_payload = data.get("result") if isinstance(data.get("result"), dict) else {}
+        summary = result_payload.get("summary") if isinstance(result_payload.get("summary"), dict) else {}
+        rows = result_payload.get("rows") if isinstance(result_payload.get("rows"), list) else []
+        if summary:
+            lines.append(f"Summary: {json.dumps(summary, ensure_ascii=False)}")
+        lines.append(f"Rows: {len(rows)}")
+        for row in rows[:10]:
+            if isinstance(row, dict):
+                lines.append(json.dumps(row, ensure_ascii=False))
+        if len(rows) > 10:
+            lines.append(f"... {len(rows) - 10} more")
+    resolved_filters = context.get("resolved_filters") if isinstance(context.get("resolved_filters"), list) else []
+    if resolved_filters:
+        lines.append(f"Resolved Filters: {len(resolved_filters)}")
+    _append_warnings(lines, result.get("warnings"))
+    return "\n".join(lines) + "\n"
+
+
 def _format_import_verify(result: dict[str, Any]) -> str:
     lines = [
         f"App Key: {result.get('app_key') or '-'}",
@@ -371,6 +440,121 @@ def _first_present(payload: dict[str, Any], *keys: str) -> Any:
     return None
 
 
+def _task_action_success_label(action: str) -> str:
+    return {
+        "approve": "已通过",
+        "reject": "已驳回",
+        "rollback": "已退回",
+        "transfer": "已转交",
+        "save_only": "已保存",
+        "urge": "已催办",
+    }.get(action, "已执行")
+
+
+def _task_action_failure_label(action: str) -> str:
+    return {
+        "approve": "审批失败",
+        "reject": "驳回失败",
+        "rollback": "退回失败",
+        "transfer": "转交失败",
+        "save_only": "保存失败",
+        "urge": "催办失败",
+    }.get(action, "执行失败")
+
+
+def _task_action_partial_success_message(result: dict[str, Any]) -> str:
+    error_code = str(result.get("error_code") or "").strip().upper()
+    if error_code == "WORKFLOW_CONTINUATION_UNVERIFIED":
+        return "动作已提交，但暂未完成后续流程验证。可使用 --json 查看详细信息。"
+    if error_code == "TASK_ALREADY_PROCESSED":
+        return "当前待办已不可操作，系统判断流程可能已被其他人处理。可使用 --json 查看详细信息。"
+    warnings = result.get("warnings")
+    if isinstance(warnings, list):
+        for warning in warnings:
+            if not isinstance(warning, dict):
+                continue
+            code = str(warning.get("code") or "").strip().upper()
+            if code == "TASK_ALREADY_PROCESSED_UNCONFIRMED_ACTOR":
+                return "当前待办已不可操作，系统判断流程可能已被其他人处理。可使用 --json 查看详细信息。"
+            if code == "WORKFLOW_CONTINUATION_UNVERIFIED":
+                return "动作已提交，但暂未完成后续流程验证。可使用 --json 查看详细信息。"
+    return "动作已提交，但结果验证不完整。可使用 --json 查看详细信息。"
+
+
+def _task_action_failure_reason(result: dict[str, Any]) -> str | None:
+    error_code = str(result.get("error_code") or "").strip().upper()
+    mapped_error = {
+        "TASK_CONTEXT_VISIBILITY_UNVERIFIED": "当前待办已不可操作，且系统未能确认是否已被处理。",
+        "TASK_SAVE_ONLY_VERIFICATION_FAILED": "保存请求已发送，但未能确认字段是否全部保存成功。",
+        "WORKFLOW_CONTINUATION_UNVERIFIED": "动作已提交，但暂未验证到流程继续推进。",
+        "TASK_ALREADY_PROCESSED": "当前待办已不可操作，系统判断流程可能已被其他人处理。",
+    }.get(error_code)
+    if mapped_error:
+        return mapped_error
+
+    warnings = result.get("warnings")
+    if isinstance(warnings, list):
+        for warning in warnings:
+            if isinstance(warning, dict) and warning.get("message"):
+                return str(warning.get("message"))
+
+    data = result.get("data") if isinstance(result.get("data"), dict) else {}
+    transport_error = data.get("transport_error") if isinstance(data.get("transport_error"), dict) else {}
+    backend_code = transport_error.get("backend_code")
+    http_status = transport_error.get("http_status")
+    if backend_code not in (None, ""):
+        return f"后端返回错误码 {backend_code}。"
+    if http_status not in (None, ""):
+        return f"请求返回 HTTP {http_status}。"
+
+    verification = result.get("verification") if isinstance(result.get("verification"), dict) else {}
+    record_state_error = verification.get("record_state_error") if isinstance(verification.get("record_state_error"), dict) else {}
+    backend_code = record_state_error.get("backend_code")
+    http_status = record_state_error.get("http_status")
+    if backend_code not in (None, ""):
+        return f"后端返回错误码 {backend_code}。"
+    if http_status not in (None, ""):
+        return f"请求返回 HTTP {http_status}。"
+    if error_code:
+        return f"错误码：{error_code}"
+    return None
+
+
+def _task_action_debug_lines(result: dict[str, Any]) -> list[str]:
+    lines: list[str] = []
+    error_code = result.get("error_code")
+    if error_code not in (None, ""):
+        lines.append(f"error_code: {error_code}")
+
+    data = result.get("data") if isinstance(result.get("data"), dict) else {}
+    transport_error = data.get("transport_error") if isinstance(data.get("transport_error"), dict) else {}
+    for key in ("backend_code", "http_status", "category"):
+        value = transport_error.get(key)
+        if value not in (None, ""):
+            lines.append(f"{key}: {value}")
+
+    verification = result.get("verification") if isinstance(result.get("verification"), dict) else {}
+    for key in (
+        "runtime_continuation_verified",
+        "task_context_visibility_verified",
+        "fields_saved_verified",
+        "task_still_actionable",
+        "workflow_not_advanced",
+        "record_state_readable",
+    ):
+        if key in verification and verification.get(key) is not None:
+            lines.append(f"{key}: {verification.get(key)}")
+
+    record_state_error = verification.get("record_state_error") if isinstance(verification.get("record_state_error"), dict) else {}
+    for key in ("backend_code", "http_status", "category"):
+        value = record_state_error.get(key)
+        if value not in (None, ""):
+            entry = f"record_state_{key}: {value}"
+            if entry not in lines:
+                lines.append(entry)
+    return lines
+
+
 _FORMATTERS = {
     "auth_whoami": _format_whoami,
     "workspace_list": _format_workspace_list,
@@ -381,6 +565,8 @@ _FORMATTERS = {
     "record_list": _format_record_list,
     "task_list": _format_task_list,
     "task_get": _format_task_get,
+    "task_action_execute": _format_task_action,
+    "task_associated_report_detail_get": _format_task_associated_report_detail,
     "import_verify": _format_import_verify,
     "import_status": _format_import_status,
     "builder_summary": _format_builder_summary,

package/src/qingflow_mcp/cli/main.py

@@ -152,6 +152,7 @@ def _emit_cli_effective_context_notice(args: argparse.Namespace, context: CliCon
     spec = cli_public_tool_spec_from_namespace(args)
     if spec is None or not spec.cli_show_effective_context:
         return
+    hide_context_line = bool(getattr(args, "hide_effective_context_line", False))
     sessions = getattr(context, "sessions", None)
     if sessions is None or not hasattr(sessions, "get_profile"):
         return
@@ -168,9 +169,13 @@ def _emit_cli_effective_context_notice(args: argparse.Namespace, context: CliCon
         workspace_label = f"{workspace_name} ({workspace_id})"
     else:
         workspace_label = str(workspace_id)
-    lines = [f"Context: profile={profile_name} workspace={workspace_label}"]
+    lines: list[str] = []
+    if not hide_context_line:
+        lines.append(f"Context: profile={profile_name} workspace={workspace_label}")
     if spec.cli_context_write and profile_name == "default":
         lines.append("Warning: using default profile for a workspace-sensitive write command")
+    if not lines:
+        return
     stream.write("\n".join(lines) + "\n")
 
 

package/src/qingflow_mcp/public_surface.py

@@ -94,7 +94,13 @@ USER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
     PublicToolSpec(USER_DOMAIN, "task_list", ("task_list",), ("task", "list"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "task_get", ("task_get",), ("task", "get"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "task_action_execute", ("task_action_execute",), ("task", "action"), cli_show_effective_context=True, cli_context_write=True),
-    PublicToolSpec(USER_DOMAIN, "task_associated_report_detail_get", ("task_associated_report_detail_get",), cli_public=False, cli_show_effective_context=True),
+    PublicToolSpec(
+        USER_DOMAIN,
+        "task_associated_report_detail_get",
+        ("task_associated_report_detail_get",),
+        ("task", "report"),
+        cli_show_effective_context=True,
+    ),
     PublicToolSpec(USER_DOMAIN, "task_workflow_log_get", ("task_workflow_log_get",), ("task", "log"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "directory_search", ("directory_search",), cli_public=False),
     PublicToolSpec(USER_DOMAIN, "directory_list_internal_users", ("directory_list_internal_users",), cli_public=False),

package/src/qingflow_mcp/server.py

@@ -151,6 +151,10 @@ Use `record_code_block_run` when the user wants to execute a form code-block fie
 
 `task_list -> task_get -> task_action_execute`
 
+- `task_list` returns task-card summaries keyed by `task_id`.
+- Prefer `task_get(task_id=...)` for detail reads; MCP resolves the current todo locator internally.
+- `task_action_execute(task_id=..., action=...)` is also supported; MCP resolves the current todo locator internally before calling the real action route.
+- `task_workflow_log_get(task_id=...)` and `task_associated_report_detail_get(task_id=...)` are also supported for the current todo context.
 - 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`.

package/src/qingflow_mcp/server_app_user.py

@@ -146,6 +146,10 @@ Use `record_code_block_run` when the user wants to execute a form code-block fie
 
 `task_list -> task_get -> task_action_execute`
 
+- `task_list` returns task-card summaries keyed by `task_id`.
+- Prefer `task_get(task_id=...)` for detail reads; MCP resolves the current todo locator internally.
+- `task_action_execute(task_id=..., action=...)` is also supported; MCP resolves the current todo locator internally before calling the real action route.
+- `task_workflow_log_get(task_id=...)` and `task_associated_report_detail_get(task_id=...)` are also supported for the current todo context.
 - 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`.