@josephyan/qingflow-app-user-mcp 0.2.0-beta.1002 → 0.2.0-beta.1003

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.2.0-beta.1002",
+  "version": "0.2.0-beta.1003",
   "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.0b1002"
+version = "0.2.0b1003"
 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.0b1002"
+_FALLBACK_VERSION = "0.2.0b1003"
 
 
 def _resolve_local_pyproject_version() -> str | None:

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

@@ -3,6 +3,9 @@ from __future__ import annotations
 import argparse
 
 from ..context import CliContext
+from ..interaction import cancelled_result, resolve_interactive_selection
+from ..terminal_ui import SelectionOption
+from .common import raise_config_error
 
 
 def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
@@ -19,7 +22,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     search.set_defaults(handler=_handle_search, format_hint="app_search")
 
     get = app_subparsers.add_parser("get", help="读取应用可访问视图与导入能力")
-    get.add_argument("--app-key", required=True)
+    get.add_argument("--app-key", help="不传时在交互终端中选择应用")
     get.set_defaults(handler=_handle_get, format_hint="app_get")
 
 
@@ -37,4 +40,47 @@ def _handle_search(args: argparse.Namespace, context: CliContext) -> dict:
 
 
 def _handle_get(args: argparse.Namespace, context: CliContext) -> dict:
+    if not (args.app_key or "").strip():
+        selection = _choose_app_interactively(args, context)
+        if selection.status == "unavailable":
+            raise_config_error(
+                "app get requires --app-key, or an interactive terminal to choose an app",
+                fix_hint="Run `app list` to inspect visible apps, or retry with `--app-key APP_KEY`.",
+            )
+        if selection.status == "empty":
+            raise_config_error(
+                selection.message or "app get could not open a selector because no visible apps were returned.",
+                fix_hint="Run `app list` to confirm visible apps, or retry with `--app-key APP_KEY`.",
+            )
+        if selection.status == "cancelled":
+            return cancelled_result(selection.message or "已取消")
+        args.app_key = str(selection.value or "")
     return context.app.app_get(profile=args.profile, app_key=args.app_key)
+
+
+def _choose_app_interactively(args: argparse.Namespace, context: CliContext):
+    def load_options() -> list[SelectionOption[str]]:
+        result = context.app.app_list(profile=args.profile)
+        items = result.get("items") if isinstance(result, dict) and isinstance(result.get("items"), list) else []
+        options: list[SelectionOption[str]] = []
+        for item in items:
+            if not isinstance(item, dict):
+                continue
+            app_key = str(item.get("app_key") or "").strip()
+            if not app_key:
+                continue
+            app_name = str(item.get("app_name") or app_key).strip() or app_key
+            package_name = str(item.get("package_name") or "").strip()
+            hint = f"app_key={app_key}"
+            if package_name:
+                hint += f" · package={package_name}"
+            options.append(SelectionOption(value=app_key, label=app_name, hint=hint))
+        return options
+
+    return resolve_interactive_selection(
+        args,
+        title="选择应用",
+        unavailable_message="app get requires --app-key, or an interactive terminal to choose an app",
+        empty_message="app get could not open a selector because no visible apps were returned.",
+        load_options=load_options,
+    )

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

@@ -3,7 +3,9 @@ from __future__ import annotations
 import argparse
 
 from ..context import CliContext
-from .common import load_object_arg
+from ..interaction import cancelled_result, resolve_interactive_selection
+from ..terminal_ui import SelectionOption
+from .common import load_object_arg, raise_config_error
 
 
 def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
@@ -51,7 +53,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     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("--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")
@@ -78,10 +80,9 @@ 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"}'
-        )
+    selection_result = _resolve_task_locator_or_select(args, context, tool_name="task get")
+    if isinstance(selection_result, dict):
+        return selection_result
     return context.task.task_get(
         profile=args.profile,
         task_id=args.task_id,
@@ -111,10 +112,9 @@ 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"}'
-        )
+    selection_result = _resolve_task_locator_or_select(args, context, tool_name="task log")
+    if isinstance(selection_result, dict):
+        return selection_result
     return context.task.task_workflow_log_get(
         profile=args.profile,
         task_id=args.task_id,
@@ -125,10 +125,12 @@ def _handle_log(args: argparse.Namespace, context: CliContext) -> dict:
 
 
 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"}'
-        )
+    selection_result = _resolve_task_locator_or_select(args, context, tool_name="task report")
+    if isinstance(selection_result, dict):
+        return selection_result
+    report_selection = _resolve_report_id_or_select(args, context)
+    if isinstance(report_selection, dict):
+        return report_selection
     return context.task.task_associated_report_detail_get(
         profile=args.profile,
         task_id=args.task_id,
@@ -139,3 +141,155 @@ def _handle_report(args: argparse.Namespace, context: CliContext) -> dict:
         page=int(args.page),
         page_size=int(args.page_size),
     )
+
+
+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",
+            fix_hint=(
+                "Retry in an interactive terminal to choose from current todo tasks, "
+                "or pass `--task-id TASK_ID` 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`.",
+        )
+    if selection.status == "cancelled":
+        return cancelled_result(selection.message or "已取消")
+
+    args.task_id = str(selection.value or "")
+    return None
+
+
+def _choose_todo_task_interactively(args: argparse.Namespace, context: CliContext, *, tool_name: str):
+    def load_options() -> list[SelectionOption[str]]:
+        result = context.task.task_list(
+            profile=args.profile,
+            task_box="todo",
+            flow_status="all",
+            app_key=None,
+            workflow_node_id=None,
+            query=None,
+            page=1,
+            page_size=100,
+        )
+        data = result.get("data") if isinstance(result, dict) and isinstance(result.get("data"), dict) else {}
+        items = data.get("items") if isinstance(data.get("items"), list) else []
+        options: list[SelectionOption[str]] = []
+        for item in items:
+            if not isinstance(item, dict):
+                continue
+            task_id = str(item.get("task_id") or "").strip()
+            if not task_id:
+                continue
+            node_name = str(item.get("workflow_node_name") or "未命名节点").strip() or "未命名节点"
+            app_name = str(item.get("app_name") or item.get("app_key") or "未知应用").strip() or "未知应用"
+            label = f"{node_name} / {app_name}"
+            hint_parts = [f"task_id={task_id}"]
+            apply_time = str(item.get("apply_time") or "").strip()
+            if apply_time:
+                hint_parts.append(apply_time)
+            summary_fields = item.get("summary_fields") if isinstance(item.get("summary_fields"), list) else []
+            preview_parts: list[str] = []
+            for summary in summary_fields[:2]:
+                if not isinstance(summary, dict):
+                    continue
+                title = str(summary.get("title") or "").strip()
+                answer = str(summary.get("answer") or "").strip()
+                if title and answer:
+                    preview_parts.append(f"{title}: {answer}")
+            if preview_parts:
+                hint_parts.append("; ".join(preview_parts))
+            options.append(SelectionOption(value=task_id, label=label, hint=" · ".join(hint_parts)))
+        return options
+
+    return resolve_interactive_selection(
+        args,
+        title="选择待办",
+        unavailable_message=(
+            f"{tool_name} requires --task-id, or --app-key together with --record-id and --workflow-node-id"
+        ),
+        empty_message=f"{tool_name} could not open a selector because no current todo tasks are available.",
+        load_options=load_options,
+    )
+
+
+def _resolve_report_id_or_select(args: argparse.Namespace, context: CliContext) -> dict | None:
+    if int(args.report_id or 0) > 0:
+        return None
+
+    selection = _choose_associated_report_interactively(args, context)
+    if selection.status == "unavailable":
+        raise_config_error(
+            "task report requires --report-id, or an interactive terminal to choose a visible associated report",
+            fix_hint="Pass `--report-id REPORT_ID`, or run in an interactive terminal and choose from visible associated reports.",
+        )
+    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.",
+        )
+    if selection.status == "cancelled":
+        return cancelled_result(selection.message or "已取消")
+
+    args.report_id = int(selection.value or 0)
+    return None
+
+
+def _choose_associated_report_interactively(args: argparse.Namespace, context: CliContext):
+    def load_options() -> list[SelectionOption[int]]:
+        result = context.task.task_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),
+            include_candidates=False,
+            include_associated_reports=True,
+        )
+        data = result.get("data") if isinstance(result, dict) and isinstance(result.get("data"), dict) else {}
+        extras = data.get("extras") if isinstance(data.get("extras"), dict) else {}
+        associated_reports = extras.get("associated_reports") if isinstance(extras.get("associated_reports"), dict) else {}
+        items = associated_reports.get("items") if isinstance(associated_reports.get("items"), list) else []
+        options: list[SelectionOption[int]] = []
+        for item in items:
+            if not isinstance(item, dict):
+                continue
+            report_id = int(item.get("report_id") or 0)
+            if report_id <= 0:
+                continue
+            chart_name = str(item.get("chart_name") or f"报表 {report_id}").strip() or f"报表 {report_id}"
+            graph_type = str(item.get("graph_type") or "chart").strip() or "chart"
+            options.append(
+                SelectionOption(
+                    value=report_id,
+                    label=chart_name,
+                    hint=f"report_id={report_id} · {graph_type}",
+                )
+            )
+        return options
+
+    return resolve_interactive_selection(
+        args,
+        title="选择关联报表",
+        unavailable_message="task report requires --report-id, or an interactive terminal to choose a visible associated report",
+        empty_message="task report could not open a selector because the selected task has no visible associated reports.",
+        load_options=load_options,
+    )

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

@@ -1,12 +1,11 @@
 from __future__ import annotations
 
 import argparse
-import json
 
 from ..context import CliContext
-from ..terminal_ui import SelectionOption, select_option
-
-_INTERACTIVE_SELECTION_UNAVAILABLE = object()
+from ..interaction import cancelled_result, resolve_interactive_selection
+from ..terminal_ui import SelectionOption
+from .common import raise_config_error
 
 
 def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
@@ -46,42 +45,27 @@ def _handle_get(args: argparse.Namespace, context: CliContext) -> dict:
 
 def _handle_select(args: argparse.Namespace, context: CliContext) -> dict:
     if int(args.ws_id or 0) <= 0:
-        selected_ws_id = _choose_workspace_interactively(args, context)
-        if selected_ws_id is _INTERACTIVE_SELECTION_UNAVAILABLE:
-            raise RuntimeError(
-                json.dumps(
-                    {
-                        "category": "config",
-                        "message": "workspace select requires --ws-id, or an interactive terminal to choose a workspace",
-                    },
-                    ensure_ascii=False,
-                )
+        selection = _choose_workspace_interactively(args, context)
+        if selection.status == "unavailable":
+            raise_config_error(
+                "workspace select requires --ws-id, or an interactive terminal to choose a workspace",
+                fix_hint="Retry in an interactive terminal, or pass `--ws-id WS_ID` explicitly.",
+            )
+        if selection.status == "empty":
+            raise_config_error(
+                selection.message or "workspace select could not open a selector because no workspaces are available.",
+                fix_hint="Run `workspace list` to confirm visible workspaces, or retry with `--ws-id WS_ID`.",
             )
-        if selected_ws_id is None:
-            return {"status": "cancelled", "message": "已取消"}
-        args.ws_id = selected_ws_id
+        if selection.status == "cancelled":
+            return cancelled_result(selection.message or "已取消")
+        args.ws_id = int(selection.value or 0)
     return context.workspace.workspace_select(
         profile=args.profile,
         ws_id=int(args.ws_id),
     )
 
 
-def _choose_workspace_interactively(args: argparse.Namespace, context: CliContext) -> int | None | object:
-    input_stream = getattr(args, "_stdin", None)
-    output_stream = getattr(args, "_stderr_stream", None)
-    if input_stream is None or output_stream is None:
-        return _INTERACTIVE_SELECTION_UNAVAILABLE
-    if not bool(getattr(input_stream, "isatty", lambda: False)()):
-        return _INTERACTIVE_SELECTION_UNAVAILABLE
-    page = context.workspace.workspace_list(
-        profile=args.profile,
-        page_num=1,
-        page_size=100,
-        include_external=False,
-    ).get("page")
-    items = page.get("list") if isinstance(page, dict) and isinstance(page.get("list"), list) else []
-    if not items:
-        return _INTERACTIVE_SELECTION_UNAVAILABLE
+def _choose_workspace_interactively(args: argparse.Namespace, context: CliContext):
     current_ws_id = None
     sessions = getattr(context, "sessions", None)
     if sessions is not None and hasattr(sessions, "get_profile"):
@@ -90,25 +74,36 @@ def _choose_workspace_interactively(args: argparse.Namespace, context: CliContex
         except Exception:
             session_profile = None
         current_ws_id = getattr(session_profile, "selected_ws_id", None) if session_profile is not None else None
-    options: list[SelectionOption[int]] = []
-    for item in items:
-        if not isinstance(item, dict):
-            continue
-        ws_id = int(item.get("wsId") or 0)
-        if ws_id <= 0:
-            continue
-        workspace_name = str(item.get("workspaceName") or item.get("wsName") or f"Workspace {ws_id}")
-        remark = str(item.get("remark") or "").strip()
-        label = workspace_name
-        if remark:
-            label = f"{workspace_name} - {remark}"
-        hint = f"ws_id={ws_id}"
-        if current_ws_id == ws_id:
-            hint += " · 当前"
-        options.append(SelectionOption(value=ws_id, label=label, hint=hint))
-    return select_option(
+    def load_options() -> list[SelectionOption[int]]:
+        page = context.workspace.workspace_list(
+            profile=args.profile,
+            page_num=1,
+            page_size=100,
+            include_external=False,
+        ).get("page")
+        items = page.get("list") if isinstance(page, dict) and isinstance(page.get("list"), list) else []
+        options: list[SelectionOption[int]] = []
+        for item in items:
+            if not isinstance(item, dict):
+                continue
+            ws_id = int(item.get("wsId") or 0)
+            if ws_id <= 0:
+                continue
+            workspace_name = str(item.get("workspaceName") or item.get("wsName") or f"Workspace {ws_id}")
+            remark = str(item.get("remark") or "").strip()
+            label = workspace_name
+            if remark:
+                label = f"{workspace_name} - {remark}"
+            hint = f"ws_id={ws_id}"
+            if current_ws_id == ws_id:
+                hint += " · 当前"
+            options.append(SelectionOption(value=ws_id, label=label, hint=hint))
+        return options
+
+    return resolve_interactive_selection(
+        args,
         title="选择工作区",
-        options=options,
-        input_stream=input_stream,
-        output_stream=output_stream,
+        unavailable_message="workspace select requires --ws-id, or an interactive terminal to choose a workspace",
+        empty_message="workspace select could not open a selector because no visible workspaces were returned.",
+        load_options=load_options,
     )

package/src/qingflow_mcp/cli/formatters.py

@@ -5,13 +5,21 @@ from typing import Any, TextIO
 
 
 def emit_text_result(result: dict[str, Any], *, hint: str, stream: TextIO) -> None:
-    formatter = _FORMATTERS.get(hint, _format_generic)
-    text = formatter(result)
+    text = _format_cancelled_result(result)
+    if text is None:
+        formatter = _FORMATTERS.get(hint, _format_generic)
+        text = formatter(result)
     stream.write(text)
     if not text.endswith("\n"):
         stream.write("\n")
 
 
+def _format_cancelled_result(result: dict[str, Any]) -> str | None:
+    if str(result.get("status") or "").lower() != "cancelled":
+        return None
+    return str(result.get("message") or "已取消") + "\n"
+
+
 def _format_generic(result: dict[str, Any]) -> str:
     lines: list[str] = []
     title = _first_present(result, "status", "message")

package/src/qingflow_mcp/cli/interaction.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Generic, TypeVar
+
+from .terminal_ui import SelectionOption, select_option
+
+
+T = TypeVar("T")
+
+
+@dataclass(slots=True)
+class InteractiveSelectionResult(Generic[T]):
+    status: str
+    value: T | None = None
+    message: str | None = None
+
+
+def cancelled_result(message: str = "已取消") -> dict[str, str]:
+    return {"status": "cancelled", "message": message}
+
+
+def resolve_interactive_selection(
+    args: object,
+    *,
+    title: str,
+    unavailable_message: str,
+    empty_message: str,
+    load_options: Callable[[], list[SelectionOption[T]]],
+) -> InteractiveSelectionResult[T]:
+    input_stream = getattr(args, "_stdin", None)
+    output_stream = getattr(args, "_stderr_stream", None)
+    if input_stream is None or output_stream is None:
+        return InteractiveSelectionResult(status="unavailable", message=unavailable_message)
+    if not bool(getattr(input_stream, "isatty", lambda: False)()):
+        return InteractiveSelectionResult(status="unavailable", message=unavailable_message)
+
+    options = list(load_options())
+    if not options:
+        return InteractiveSelectionResult(status="empty", message=empty_message)
+
+    value = select_option(
+        title=title,
+        options=options,
+        input_stream=input_stream,
+        output_stream=output_stream,
+    )
+    if value is None:
+        return InteractiveSelectionResult(status="cancelled", message="已取消")
+    return InteractiveSelectionResult(status="selected", value=value)