@josephyan/qingflow-app-builder-mcp 0.2.0-beta.1011 → 0.2.0-beta.1012

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-builder-mcp",
-  "version": "0.2.0-beta.1011",
+  "version": "0.2.0-beta.1012",
   "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 = "0.2.0b1011"
+version = "0.2.0b1012"
 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.0b1011"
+_FALLBACK_VERSION = "0.2.0b1012"
 
 
 def _resolve_local_pyproject_version() -> str | None:

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

@@ -15,6 +15,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     start.add_argument("--view-id", default="system:all")
     start.add_argument("--column", dest="columns", action="append", type=int, default=[], help="只导出这些 field_id；不传时导出当前视图全部字段")
     start.add_argument("--columns-file", help="JSON/YAML list，内容与 --column 语义一致")
+    start.add_argument("--where-file", help="JSON/YAML list，内容与 record list 的 where DSL 一致；内部先查命中 record_id 再走原生导出")
     start.add_argument("--record-id", dest="record_ids", action="append", default=[], help="只导出这些 record_id；不传时导出当前视图全部数据")
     start.add_argument("--record-ids-file", help="JSON/YAML list，内容与 --record-id 语义一致")
     start.add_argument("--include-workflow-log", action=argparse.BooleanOptionalAction, default=False, help="是否同时导出流程日志")
@@ -34,6 +35,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     direct.add_argument("--view-id", default="system:all")
     direct.add_argument("--column", dest="columns", action="append", type=int, default=[], help="只导出这些 field_id；不传时导出当前视图全部字段")
     direct.add_argument("--columns-file", help="JSON/YAML list，内容与 --column 语义一致")
+    direct.add_argument("--where-file", help="JSON/YAML list，内容与 record list 的 where DSL 一致；内部先查命中 record_id 再走原生导出")
     direct.add_argument("--record-id", dest="record_ids", action="append", default=[], help="只导出这些 record_id；不传时导出当前视图全部数据")
     direct.add_argument("--record-ids-file", help="JSON/YAML list，内容与 --record-id 语义一致")
     direct.add_argument("--include-workflow-log", action=argparse.BooleanOptionalAction, default=False, help="是否同时导出流程日志")
@@ -56,12 +58,17 @@ def _record_ids(args: argparse.Namespace) -> list[str | int]:
     return record_ids
 
 
+def _where(args: argparse.Namespace) -> list[dict]:
+    return load_list_arg(args.where_file, option_name="--where-file") if args.where_file else []
+
+
 def _handle_start(args: argparse.Namespace, context: CliContext) -> dict:
     return context.exports.record_export_start(
         profile=args.profile,
         app_key=args.app_key,
         view_id=args.view_id,
         columns=_columns(args),
+        where=_where(args),
         record_ids=_record_ids(args),
         include_workflow_log=args.include_workflow_log,
     )
@@ -88,6 +95,7 @@ def _handle_direct(args: argparse.Namespace, context: CliContext) -> dict:
         app_key=args.app_key,
         view_id=args.view_id,
         columns=_columns(args),
+        where=_where(args),
         record_ids=_record_ids(args),
         include_workflow_log=args.include_workflow_log,
         download_to_path=args.download_to_path,

package/src/qingflow_mcp/server.py

@@ -158,6 +158,10 @@ Use `record_code_block_run` when the user wants to execute a form code-block fie
 - `record_export_start` / `record_export_direct` support frontend-like row selection:
   - omit `record_ids` to export all rows in the selected view
   - pass `record_ids` to export selected rows only
+- `record_export_start` / `record_export_direct` also support internal query selection:
+  - pass `where` to resolve matching `record_id` values first
+  - then run native export as selected rows
+  - `where` and `record_ids` are mutually exclusive
 - `record_export_start` / `record_export_direct` also support frontend-like column selection:
   - omit `columns` to export all current-view fields
   - pass `columns` to export only selected fields, preserving the provided order

package/src/qingflow_mcp/server_app_user.py

@@ -153,6 +153,10 @@ Use `record_code_block_run` when the user wants to execute a form code-block fie
 - `record_export_start` / `record_export_direct` support frontend-like row selection:
   - omit `record_ids` to export all rows in the selected view
   - pass `record_ids` to export selected rows only
+- `record_export_start` / `record_export_direct` also support internal query selection:
+  - pass `where` to resolve matching `record_id` values first
+  - then run native export as selected rows
+  - `where` and `record_ids` are mutually exclusive
 - `record_export_start` / `record_export_direct` also support frontend-like column selection:
   - omit `columns` to export all current-view fields
   - pass `columns` to export only selected fields, preserving the provided order
@@ -241,6 +245,7 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
         app_key: str = "",
         view_id: str = "system:all",
         columns: list[dict | int] | None = None,
+        where: list[dict] | None = None,
         record_ids: list[str | int] | None = None,
         include_workflow_log: bool = False,
     ) -> dict:
@@ -249,6 +254,7 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
             app_key=app_key,
             view_id=view_id,
             columns=columns or [],
+            where=where or [],
             record_ids=record_ids or [],
             include_workflow_log=include_workflow_log,
         )
@@ -278,6 +284,7 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
         app_key: str = "",
         view_id: str = "system:all",
         columns: list[dict | int] | None = None,
+        where: list[dict] | None = None,
         record_ids: list[str | int] | None = None,
         include_workflow_log: bool = False,
         download_to_path: str | None = None,
@@ -288,6 +295,7 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
             app_key=app_key,
             view_id=view_id,
             columns=columns or [],
+            where=where or [],
             record_ids=record_ids or [],
             include_workflow_log=include_workflow_log,
             download_to_path=download_to_path,

package/src/qingflow_mcp/tools/export_tools.py

@@ -18,6 +18,7 @@ from ..json_types import JSONObject
 from .base import ToolBase, tool_cn_name
 from .record_tools import (
     AccessibleViewRoute,
+    DEFAULT_LIST_PAGE_SIZE,
     LAYOUT_ONLY_QUE_TYPES,
     RecordTools,
     _normalize_public_column_selectors,
@@ -58,6 +59,7 @@ class ExportTools(ToolBase):
             app_key: str = "",
             view_id: str = "system:all",
             columns: list[JSONObject | int] | None = None,
+            where: list[JSONObject] | None = None,
             record_ids: list[str | int] | None = None,
             include_workflow_log: bool = False,
         ) -> dict[str, Any]:
@@ -66,6 +68,7 @@ class ExportTools(ToolBase):
                 app_key=app_key,
                 view_id=view_id,
                 columns=columns or [],
+                where=where or [],
                 record_ids=record_ids or [],
                 include_workflow_log=include_workflow_log,
             )
@@ -98,6 +101,7 @@ class ExportTools(ToolBase):
             app_key: str = "",
             view_id: str = "system:all",
             columns: list[JSONObject | int] | None = None,
+            where: list[JSONObject] | None = None,
             record_ids: list[str | int] | None = None,
             include_workflow_log: bool = False,
             download_to_path: str | None = None,
@@ -108,6 +112,7 @@ class ExportTools(ToolBase):
                 app_key=app_key,
                 view_id=view_id,
                 columns=columns or [],
+                where=where or [],
                 record_ids=record_ids or [],
                 include_workflow_log=include_workflow_log,
                 download_to_path=download_to_path,
@@ -122,12 +127,14 @@ class ExportTools(ToolBase):
         app_key: str,
         view_id: str = "system:all",
         columns: list[JSONObject | int] | None = None,
+        where: list[JSONObject] | None = None,
         record_ids: list[str | int] | None = None,
         include_workflow_log: bool = False,
     ) -> dict[str, Any]:
         normalized_app_key = str(app_key or "").strip()
         normalized_view_id = str(view_id or "").strip() or "system:all"
         normalized_columns = _normalize_export_columns(columns or [])
+        normalized_where = self._record_tools._normalize_record_list_where(where or [])
         normalized_record_ids = _normalize_export_record_ids(record_ids or [])
         if not normalized_app_key:
             return self._failed_export_result(
@@ -154,11 +161,20 @@ class ExportTools(ToolBase):
                 resolved_view=resolved_view,
                 column_selectors=normalized_columns,
             )
+            effective_record_ids, row_scope = self._resolve_export_record_scope(
+                profile=profile,
+                context=context,
+                app_key=normalized_app_key,
+                resolved_view=resolved_view,
+                selected_record_ids=normalized_record_ids,
+                where_filters=normalized_where,
+                select_columns=cast(list[JSONObject], export_config.get("questionExportConfigList") or []),
+            )
             result_amount = self._estimate_export_result_amount(
                 context,
                 app_key=normalized_app_key,
                 resolved_view=resolved_view,
-                selected_record_ids=normalized_record_ids,
+                selected_record_ids=effective_record_ids,
             )
             self._validate_export_limits(
                 result_amount=result_amount,
@@ -167,7 +183,7 @@ class ExportTools(ToolBase):
             )
             filter_bean = self._build_export_filter_bean(
                 resolved_view,
-                selected_record_ids=normalized_record_ids,
+                selected_record_ids=effective_record_ids,
                 include_workflow_log=include_workflow_log,
             )
             started_at = _utc_now().replace(microsecond=0).isoformat()
@@ -180,7 +196,6 @@ class ExportTools(ToolBase):
                 export_config=export_config,
                 result_amount=result_amount,
             )
-            row_scope = "selected" if normalized_record_ids else "all"
             column_scope = "selected" if normalized_columns else "all"
             export_handle = uuid4().hex
             self._job_store.put(
@@ -194,7 +209,7 @@ class ExportTools(ToolBase):
                     "started_at": started_at,
                     "uid": session_profile.uid,
                     "row_scope": row_scope,
-                    "selected_record_count": len(normalized_record_ids),
+                    "selected_record_count": len(effective_record_ids),
                     "field_scope": column_scope,
                     "selected_field_count": len(cast(list[JSONObject], export_config.get("questionExportConfigList") or [])),
                     "include_workflow_log": bool(include_workflow_log),
@@ -212,7 +227,7 @@ class ExportTools(ToolBase):
                 "view_id": resolved_view.view_id,
                 "export_handle": export_handle,
                 "row_scope": row_scope,
-                "selected_record_count": len(normalized_record_ids),
+                "selected_record_count": len(effective_record_ids),
                 "field_scope": column_scope,
                 "selected_field_count": len(cast(list[JSONObject], export_config.get("questionExportConfigList") or [])),
                 "include_workflow_log": bool(include_workflow_log),
@@ -223,7 +238,8 @@ class ExportTools(ToolBase):
                 "verification": {
                     "export_acknowledged": bool(socket_result.get("backend_export_id")),
                     "view_route_supported": True,
-                    "row_selection_applied": bool(normalized_record_ids),
+                    "row_selection_applied": bool(effective_record_ids),
+                    "query_filter_applied": bool(normalized_where),
                     "field_selection_applied": bool(normalized_columns),
                 },
                 "request_route": self.backend.describe_route(context),
@@ -407,6 +423,7 @@ class ExportTools(ToolBase):
         app_key: str,
         view_id: str = "system:all",
         columns: list[JSONObject | int] | None = None,
+        where: list[JSONObject] | None = None,
         record_ids: list[str | int] | None = None,
         include_workflow_log: bool = False,
         download_to_path: str | None = None,
@@ -428,6 +445,7 @@ class ExportTools(ToolBase):
                 app_key=normalized_app_key,
                 view_id=normalized_view_id,
                 columns=columns or [],
+                where=where or [],
                 record_ids=record_ids or [],
                 include_workflow_log=include_workflow_log,
             )
@@ -552,6 +570,141 @@ class ExportTools(ToolBase):
                 extra={"app_key": normalized_app_key, "view_id": normalized_view_id},
             )
 
+    def _resolve_export_record_scope(
+        self,
+        *,
+        profile: str,
+        context,
+        app_key: str,
+        resolved_view: AccessibleViewRoute,
+        selected_record_ids: list[int],
+        where_filters: list[JSONObject],
+        select_columns: list[JSONObject],
+    ) -> tuple[list[int], str]:
+        if selected_record_ids and where_filters:
+            raise QingflowApiError(
+                category="config",
+                message="record export does not allow record_ids and where at the same time",
+                details={
+                    "error_code": "EXPORT_ROW_SCOPE_CONFLICT",
+                    "fix_hint": "Use record_ids for explicit selected rows or where for internal query selection, but not both.",
+                },
+            )
+        if selected_record_ids:
+            return selected_record_ids, "selected"
+        if not where_filters:
+            return [], "all"
+        resolved_ids = self._collect_record_ids_from_where(
+            profile=profile,
+            context=context,
+            app_key=app_key,
+            resolved_view=resolved_view,
+            where_filters=where_filters,
+            select_columns=select_columns,
+        )
+        if not resolved_ids:
+            raise QingflowApiError.config_error(
+                "record export query did not match any records",
+                details={
+                    "error_code": "EXPORT_NO_MATCHED_RECORDS",
+                    "view_id": resolved_view.view_id,
+                },
+            )
+        return resolved_ids, "queried"
+
+    def _collect_record_ids_from_where(
+        self,
+        *,
+        profile: str,
+        context,
+        app_key: str,
+        resolved_view: AccessibleViewRoute,
+        where_filters: list[JSONObject],
+        select_columns: list[JSONObject],
+    ) -> list[int]:
+        browse_scope = self._record_tools._build_browse_write_scope(
+            profile,
+            context,
+            app_key,
+            resolved_view,
+            force_refresh=False,
+        )
+        index = browse_scope["index"]
+        match_rules = self._record_tools._resolve_match_rules(context, where_filters, index)
+        dept_member_cache: dict[int, set[int]] = {}
+        current_page = 1
+        selected_ids: list[int] = []
+        seen: set[int] = set()
+        primary_field_ids = [
+            _coerce_int(item.get("queId"))
+            for item in select_columns
+            if isinstance(item, dict)
+        ]
+        primary_search_que_ids = [item for item in primary_field_ids if item is not None][:1] or None
+
+        while True:
+            page = self._record_tools._search_page(
+                context,
+                app_key=app_key,
+                view_selection=resolved_view.view_selection,
+                page_num=current_page,
+                page_size=DEFAULT_LIST_PAGE_SIZE,
+                query_key=None,
+                match_rules=match_rules,
+                sorts=[],
+                search_que_ids=primary_search_que_ids,
+                list_type=resolved_view.list_type if resolved_view.list_type is not None else DEFAULT_RECORD_LIST_TYPE,
+            )
+            raw_rows = page.get("list")
+            items = raw_rows if isinstance(raw_rows, list) else []
+            for item in items:
+                if not isinstance(item, dict):
+                    continue
+                answers = item.get("answers")
+                answer_list = answers if isinstance(answers, list) else []
+                if not self._record_tools._matches_view_selection(
+                    context,
+                    answer_list,
+                    view_selection=resolved_view.view_selection,
+                    dept_member_cache=dept_member_cache,
+                ):
+                    continue
+                record_id = _coerce_int(item.get("applyId"))
+                if record_id is None:
+                    record_id = _coerce_int(item.get("apply_id"))
+                if record_id is None:
+                    record_id = _coerce_int(item.get("id"))
+                if record_id is None:
+                    record_id = _coerce_int(item.get("record_id"))
+                if record_id is None or record_id in seen or record_id <= 0:
+                    continue
+                seen.add(record_id)
+                selected_ids.append(record_id)
+                if len(selected_ids) > EXPORT_ROWS_LIMIT:
+                    raise QingflowApiError.config_error(
+                        f"record export exceeds the native row limit of {EXPORT_ROWS_LIMIT}",
+                        details={
+                            "error_code": "EXPORT_ROWS_LIMIT_EXCEEDED",
+                            "result_amount": len(selected_ids),
+                            "row_limit": EXPORT_ROWS_LIMIT,
+                        },
+                    )
+            if current_page == 1:
+                reported_total = _effective_total(page, page_size=DEFAULT_LIST_PAGE_SIZE)
+                if reported_total > EXPORT_ROWS_LIMIT:
+                    raise QingflowApiError.config_error(
+                        f"record export exceeds the native row limit of {EXPORT_ROWS_LIMIT}",
+                        details={
+                            "error_code": "EXPORT_ROWS_LIMIT_EXCEEDED",
+                            "result_amount": reported_total,
+                            "row_limit": EXPORT_ROWS_LIMIT,
+                        },
+                    )
+            if not _page_has_more(page, current_page=current_page, page_size=DEFAULT_LIST_PAGE_SIZE, returned_rows=len(items)):
+                break
+            current_page += 1
+        return selected_ids
+
     def _build_export_filter_bean(
         self,
         resolved_view: AccessibleViewRoute,
@@ -1101,6 +1254,13 @@ def _effective_total(page: JSONObject, *, page_size: int) -> int:
     return returned_rows
 
 
+def _page_has_more(page: JSONObject, *, current_page: int, page_size: int, returned_rows: int) -> bool:
+    page_amount = _coerce_int(page.get("pageAmount"))
+    if page_amount is not None:
+        return current_page < page_amount
+    return returned_rows >= page_size
+
+
 def _resolve_download_targets(
     destination_hint: str,
     *,