@qingflow-tech/qingflow-app-builder-mcp 1.0.16 → 1.0.17

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @qingflow-tech/qingflow-app-builder-mcp@1.0.16
+npm install @qingflow-tech/qingflow-app-builder-mcp@1.0.17
 ```
 
 Run:
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-app-builder-mcp@1.0.16 qingflow-app-builder-mcp
+npx -y -p @qingflow-tech/qingflow-app-builder-mcp@1.0.17 qingflow-app-builder-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-app-builder-mcp",
-  "version": "1.0.16",
+  "version": "1.0.17",
   "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 = "1.0.16"
+version = "1.0.17"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

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

@@ -110,6 +110,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     list_parser.add_argument("--where-file")
     list_parser.add_argument("--order-by-file")
     list_parser.add_argument("--page", type=int, default=1)
+    list_parser.add_argument("--page-size", type=int, default=10)
     list_parser.add_argument("--view-id")
     list_parser.add_argument("--list-type", dest="legacy_list_type", type=int, help=argparse.SUPPRESS)
     list_parser.add_argument("--view-key", dest="legacy_view_key", help=argparse.SUPPRESS)
@@ -367,6 +368,7 @@ def _handle_list(args: argparse.Namespace, context: CliContext) -> dict:
         where=load_list_arg(args.where_file, option_name="--where-file"),
         order_by=load_list_arg(args.order_by_file, option_name="--order-by-file"),
         page=args.page,
+        page_size=args.page_size,
         view_id=args.view_id,
     )
 

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

@@ -47,20 +47,14 @@ 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="读取待办详情；推荐直接传 --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 = task_subparsers.add_parser("get", help="读取待办详情；--task-id 必须来自 task list 的 data.items[].task_id")
+    get.add_argument("--task-id", help="来自 `qingflow --json task list` 的 data.items[].task_id；不是列表序号")
     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")
+    get.set_defaults(handler=_handle_get, format_hint="task_get", app_key="", record_id="", workflow_node_id=0)
 
-    action = task_subparsers.add_parser("action", help="执行待办动作")
-    action.add_argument("--task-id")
-    action.add_argument("--app-key")
-    action.add_argument("--record-id")
-    action.add_argument("--workflow-node-id", type=int)
+    action = task_subparsers.add_parser("action", help="执行待办动作；--task-id 必须来自 task list 的 data.items[].task_id")
+    action.add_argument("--task-id", help="来自 `qingflow --json task list` 的 data.items[].task_id；不是列表序号")
     action.add_argument("--action", help="不传时在交互终端中选择当前待办可执行动作")
     action.add_argument("--payload-file")
     action.add_argument("--fields-file")
@@ -68,24 +62,27 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
         handler=_handle_action,
         format_hint="task_action_execute",
         hide_effective_context_line=True,
+        app_key="",
+        record_id="",
+        workflow_node_id=0,
     )
 
-    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 = task_subparsers.add_parser("report", help="读取待办关联报表详情；--task-id 必须来自 task list 的 data.items[].task_id")
+    report.add_argument("--task-id", help="来自 `qingflow --json task list` 的 data.items[].task_id；不是列表序号")
     report.add_argument("--report-id", type=int, help="不传时在交互终端中选择关联报表")
     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")
+    report.set_defaults(
+        handler=_handle_report,
+        format_hint="task_associated_report_detail_get",
+        app_key="",
+        record_id="",
+        workflow_node_id=0,
+    )
 
-    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="")
+    log = task_subparsers.add_parser("log", help="读取流程日志；--task-id 必须来自 task list 的 data.items[].task_id")
+    log.add_argument("--task-id", help="来自 `qingflow --json task list` 的 data.items[].task_id；不是列表序号")
+    log.set_defaults(handler=_handle_log, format_hint="", app_key="", record_id="", workflow_node_id=0)
 
 
 def _handle_list(args: argparse.Namespace, context: CliContext) -> dict:
@@ -243,30 +240,20 @@ def _run_task_workbench_task_loop(args: argparse.Namespace, context: CliContext)
 def _resolve_task_locator_or_select(args: argparse.Namespace, context: CliContext, *, tool_name: str) -> dict | None:
     if (args.task_id or "").strip():
         return None
-    has_app_key = bool((args.app_key or "").strip())
-    has_record_id = bool((args.record_id or "").strip())
-    has_workflow_node_id = int(args.workflow_node_id or 0) > 0
-    if has_app_key and has_record_id and has_workflow_node_id:
-        return None
-    if has_app_key or has_record_id or has_workflow_node_id:
-        raise_config_error(
-            f"{tool_name} requires --task-id, or --app-key together with --record-id and --workflow-node-id",
-            fix_hint="Either pass `--task-id TASK_ID`, or provide the full locator triple `--app-key --record-id --workflow-node-id`.",
-        )
 
     selection = _choose_todo_task_interactively(args, context, tool_name=tool_name)
     if selection.status == "unavailable":
         raise_config_error(
-            f"{tool_name} requires --task-id, or --app-key together with --record-id and --workflow-node-id",
+            f"{tool_name} requires --task-id from task list data.items[].task_id",
             fix_hint=(
                 "Retry in an interactive terminal to choose from current todo tasks, "
-                "or pass `--task-id TASK_ID` explicitly."
+                "or pass `--task-id` from `task list` explicitly."
             ),
         )
     if selection.status == "empty":
         raise_config_error(
             selection.message or f"{tool_name} could not open a selector because no current todo tasks are available.",
-            fix_hint="Run `task list` to confirm current todo tasks, or retry later with `--task-id TASK_ID`.",
+            fix_hint="Run `task list` to confirm current todo tasks, then pass the selected `data.items[].task_id`.",
         )
     if selection.status == "cancelled":
         return cancelled_result(selection.message or "已取消")
@@ -327,7 +314,7 @@ def _choose_todo_task_interactively(
         args,
         title=title,
         unavailable_message=(
-            f"{tool_name} requires --task-id, or --app-key together with --record-id and --workflow-node-id"
+            f"{tool_name} requires --task-id from task list data.items[].task_id"
         ),
         empty_message=f"{tool_name} could not open a selector because no current todo tasks are available.",
         load_options=load_options,
@@ -347,7 +334,7 @@ def _resolve_report_id_or_select(args: argparse.Namespace, context: CliContext)
     if selection.status == "empty":
         raise_config_error(
             selection.message or "task report could not open a selector because the selected task has no visible associated reports.",
-            fix_hint="Run `task get --task-id TASK_ID` to inspect `extras.associated_reports`, or choose another task.",
+            fix_hint="Run `task get --task-id <data.items[].task_id>` to inspect `extras.associated_reports`, or choose another task.",
         )
     if selection.status == "cancelled":
         return cancelled_result(selection.message or "已取消")
@@ -395,7 +382,7 @@ def _resolve_task_action_or_select(
     if selection.status == "empty":
         raise_config_error(
             selection.message or "task action could not open an action selector because no interactive actions are available.",
-            fix_hint="Run `task get --task-id TASK_ID` to inspect available_actions, or pass a supported `--action` explicitly.",
+            fix_hint="Run `task get --task-id <data.items[].task_id>` to inspect available_actions, or pass a supported `--action` explicitly.",
         )
     if selection.status == "cancelled":
         return cancelled_result(selection.message or "已取消")
@@ -476,7 +463,7 @@ def _resolve_action_payload_or_select(
         if selection.status == "empty":
             raise_config_error(
                 selection.message or "task rollback could not open a selector because no rollback candidates are visible.",
-                fix_hint="Run `task get --task-id TASK_ID` to inspect rollback candidates, or choose another action.",
+                fix_hint="Run `task get --task-id <data.items[].task_id>` to inspect rollback candidates, or choose another action.",
             )
         if selection.status == "cancelled":
             return cancelled_result(selection.message or "已取消")
@@ -493,7 +480,7 @@ def _resolve_action_payload_or_select(
         if selection.status == "empty":
             raise_config_error(
                 selection.message or "task transfer could not open a selector because no transfer candidates are visible.",
-                fix_hint="Run `task get --task-id TASK_ID` to inspect transfer candidates, or choose another action.",
+                fix_hint="Run `task get --task-id <data.items[].task_id>` to inspect transfer candidates, or choose another action.",
             )
         if selection.status == "cancelled":
             return cancelled_result(selection.message or "已取消")

package/src/qingflow_mcp/server.py

@@ -184,12 +184,12 @@ 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.
+- For detail reads and actions, pass the exact `task_id` from `task_list.data.items[].task_id`.
+- `task_id` is not a row number, list index, record id, or workflow node id.
+- Do not reconstruct task actions from `app_key + record_id + workflow_node_id` unless the user explicitly provides that full locator for troubleshooting.
 - `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 the current task context workflow log page. For full record-level data/workflow logs, first choose an accessible view with `app_get`, then call `record_logs_get(app_key, record_id, view_id)` with that same explicit `view_id`.
-- Task actions operate on `app_key + record_id + workflow_node_id`, not `task_id`.
 
 ## Time Handling
 

package/src/qingflow_mcp/server_app_user.py

@@ -189,12 +189,12 @@ Use export only when the user explicitly asks to export/download/generate an Exc
 `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.
+- For detail reads and actions, pass the exact `task_id` from `task_list.data.items[].task_id`.
+- `task_id` is not a row number, list index, record id, or workflow node id.
+- Do not reconstruct task actions from `app_key + record_id + workflow_node_id` unless the user explicitly provides that full locator for troubleshooting.
 - `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 the current task context workflow log page. For full record-level data/workflow logs, first choose an accessible view with `app_get`, then call `record_logs_get(app_key, record_id, view_id)` with that same explicit `view_id`.
-- Task actions operate on `app_key + record_id + workflow_node_id`, not `task_id`.
 - Treat `task_action_execute` as the tool-level action enum surface; the current task's real actions are only the ones listed in `task_get.capabilities.available_actions`.
 - Use `task_action_execute(action="save_only", fields=...)` when the user wants to save editable field changes on the current node without advancing the workflow.
 - `save_only` is exposed only when the backend current-node `editableQueIds` signal returns a non-empty result; MCP no longer infers `save_only` from local schema reconstruction.

package/src/qingflow_mcp/tools/record_tools.py

@@ -438,6 +438,7 @@ class RecordTools(ToolBase):
             where: list[JSONObject] | None = None,
             order_by: list[JSONObject] | None = None,
             page: int = 1,
+            page_size: int = DEFAULT_RECORD_LIST_RETURN_LIMIT,
             view_id: str | None = None,
             output_profile: str = "normal",
         ) -> JSONObject:
@@ -450,6 +451,7 @@ class RecordTools(ToolBase):
                 where=where or [],
                 order_by=order_by or [],
                 page=page,
+                page_size=page_size,
                 view_id=view_id,
                 list_type=None,
                 view_key=None,
@@ -1881,6 +1883,7 @@ class RecordTools(ToolBase):
         order_by: list[JSONObject],
         limit: int = DEFAULT_RECORD_LIST_RETURN_LIMIT,
         page: int = 1,
+        page_size: int = DEFAULT_RECORD_LIST_RETURN_LIMIT,
         view_id: str | None = None,
         list_type: int | None = None,
         view_key: str | None = None,
@@ -1899,6 +1902,8 @@ class RecordTools(ToolBase):
             raise_tool_error(QingflowApiError.config_error("limit must be positive"))
         if page <= 0:
             raise_tool_error(QingflowApiError.config_error("page must be positive"))
+        if page_size <= 0:
+            raise_tool_error(QingflowApiError.config_error("page_size must be positive"))
         if not (
             _normalize_optional_text(view_id)
             or list_type is not None
@@ -1971,12 +1976,12 @@ class RecordTools(ToolBase):
                 app_key=app_key,
                 view_route=view_route,
                 page_num=page,
-                page_size=DEFAULT_LIST_PAGE_SIZE,
+                page_size=page_size,
                 query_key=normalized_query,
                 search_que_ids=resolved_query_fields or None,
                 match_rules=match_rules,
                 sort_rules=sort_rules,
-                max_rows=limit,
+                max_rows=min(limit, page_size),
                 selected_fields=selected_fields,
                 output_profile="verbose" if normalized_output_profile in {"verbose", "normalized"} else DEFAULT_OUTPUT_PROFILE,
             )

package/src/qingflow_mcp/tools/task_context_tools.py

@@ -85,33 +85,37 @@ class TaskContextTools(ToolBase):
                 page_size=page_size,
             )
 
-        @mcp.tool()
+        @mcp.tool(
+            description=(
+                "Read one workflow task. Prefer task_id from task_list.data.items[].task_id; "
+                "task_id is not a row number, list index, record id, or workflow node id."
+            )
+        )
         def task_get(
             profile: str = DEFAULT_PROFILE,
             task_id: str = "",
-            app_key: str = "",
-            record_id: str = "",
-            workflow_node_id: int = 0,
             include_candidates: bool = True,
             include_associated_reports: bool = True,
         ) -> dict[str, Any]:
             return self.task_get(
                 profile=profile,
                 task_id=task_id,
-                app_key=app_key,
-                record_id=record_id,
-                workflow_node_id=workflow_node_id,
+                app_key="",
+                record_id="",
+                workflow_node_id=0,
                 include_candidates=include_candidates,
                 include_associated_reports=include_associated_reports,
             )
 
-        @mcp.tool(description=self._high_risk_tool_description(operation="execute", target="workflow task action"))
+        @mcp.tool(
+            description=(
+                self._high_risk_tool_description(operation="execute", target="workflow task action")
+                + " Pass task_id from task_list.data.items[].task_id. Do not pass a row number, list index, record id, or workflow node id as task_id."
+            )
+        )
         def task_action_execute(
             profile: str = DEFAULT_PROFILE,
             task_id: str = "",
-            app_key: str = "",
-            record_id: str = "",
-            workflow_node_id: int = 0,
             action: str = "",
             payload: dict[str, Any] | None = None,
             fields: dict[str, Any] | None = None,
@@ -119,21 +123,23 @@ class TaskContextTools(ToolBase):
             return self.task_action_execute(
                 profile=profile,
                 task_id=task_id,
-                app_key=app_key,
-                record_id=record_id,
-                workflow_node_id=workflow_node_id,
+                app_key="",
+                record_id="",
+                workflow_node_id=0,
                 action=action,
                 payload=payload or {},
                 fields=fields or {},
             )
 
-        @mcp.tool()
+        @mcp.tool(
+            description=(
+                "Read a task-associated report. Pass task_id from task_list.data.items[].task_id; "
+                "task_id is not a row number, list index, record id, or workflow node id."
+            )
+        )
         def task_associated_report_detail_get(
             profile: str = DEFAULT_PROFILE,
             task_id: str = "",
-            app_key: str = "",
-            record_id: str = "",
-            workflow_node_id: int = 0,
             report_id: int = 0,
             page: int = 1,
             page_size: int = 20,
@@ -141,28 +147,30 @@ class TaskContextTools(ToolBase):
             return self.task_associated_report_detail_get(
                 profile=profile,
                 task_id=task_id,
-                app_key=app_key,
-                record_id=record_id,
-                workflow_node_id=workflow_node_id,
+                app_key="",
+                record_id="",
+                workflow_node_id=0,
                 report_id=report_id,
                 page=page,
                 page_size=page_size,
             )
 
-        @mcp.tool()
+        @mcp.tool(
+            description=(
+                "Read workflow log for one task context. Pass task_id from task_list.data.items[].task_id; "
+                "task_id is not a row number, list index, record id, or workflow node id."
+            )
+        )
         def task_workflow_log_get(
             profile: str = DEFAULT_PROFILE,
             task_id: str = "",
-            app_key: str = "",
-            record_id: str = "",
-            workflow_node_id: int = 0,
         ) -> dict[str, Any]:
             return self.task_workflow_log_get(
                 profile=profile,
                 task_id=task_id,
-                app_key=app_key,
-                record_id=record_id,
-                workflow_node_id=workflow_node_id,
+                app_key="",
+                record_id="",
+                workflow_node_id=0,
             )
 
     @tool_cn_name("任务上下文列表")
@@ -1302,14 +1310,14 @@ class TaskContextTools(ToolBase):
             searched = ", ".join(incomplete_task_boxes)
             raise_tool_error(
                 QingflowApiError.config_error(
-                    f"task_id={task_id_text} resolved to an incomplete task locator in task_box={searched}; please refresh the task list and retry"
+                    f"task_id={task_id_text} resolved to an incomplete task locator in task_box={searched}; rerun task_list and pass the exact data.items[].task_id. Do not substitute a row number or rebuild the locator from app_key/record_id/workflow_node_id."
                 )
             )
         if inaccessible_task_boxes:
             searched = ", ".join(str(item.get("task_box")) for item in inaccessible_task_boxes)
             raise_tool_error(
                 QingflowApiError.config_error(
-                    f"task_id={task_id_text} was not found in visible task boxes; some task boxes were not searchable in the current permission context: {searched}",
+                    f"task_id={task_id_text} was not found in visible task boxes; some task boxes were not searchable in the current permission context: {searched}. Rerun task_list and use data.items[].task_id; do not substitute a row number or rebuild the locator.",
                     details={
                         "task_id": task_id_text,
                         "searched_task_boxes": list(searched_task_boxes),
@@ -1319,7 +1327,7 @@ class TaskContextTools(ToolBase):
             )
         raise_tool_error(
             QingflowApiError.config_error(
-                f"task_id={task_id_text} was not found in the current visible task boxes (todo, initiated, cc, done)"
+                f"task_id={task_id_text} was not found in the current visible task boxes (todo, initiated, cc, done). Rerun task_list and pass data.items[].task_id; do not use the displayed row number or guess app_key/record_id/workflow_node_id."
             )
         )