@qingflow-tech/qingflow-app-user-mcp 1.0.3 → 1.0.5

package/src/qingflow_mcp/cli/terminal_ui.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+import os
+import select
+import shutil
+import textwrap
+from dataclasses import dataclass
+from typing import Generic, Sequence, TextIO, TypeVar
+
+try:
+    import termios
+    import tty
+except ImportError:  # pragma: no cover - non-POSIX fallback
+    termios = None
+    tty = None
+
+
+T = TypeVar("T")
+RAW_TTY_NEWLINE = "\r\n"
+# Give terminal escape sequences a slightly roomier window so arrow keys
+# still parse correctly when an outer Node/npm launcher adds a bit of PTY lag.
+ESCAPE_SEQUENCE_TIMEOUT_SECONDS = 0.2
+ESCAPE_SEQUENCE_FOLLOWUP_TIMEOUT_SECONDS = 0.02
+
+
+@dataclass(slots=True)
+class SelectionOption(Generic[T]):
+    value: T
+    label: str
+    hint: str | None = None
+
+
+def select_option(
+    *,
+    title: str,
+    options: Sequence[SelectionOption[T]],
+    input_stream: TextIO,
+    output_stream: TextIO,
+    page_size: int = 8,
+) -> T | None:
+    if not options:
+        return None
+    if len(options) == 1:
+        return options[0].value
+    if not _supports_raw_selection(input_stream=input_stream, output_stream=output_stream):
+        return _select_option_via_prompt(title=title, options=options, input_stream=input_stream, output_stream=output_stream)
+    return _select_option_via_raw_terminal(
+        title=title,
+        options=options,
+        input_stream=input_stream,
+        output_stream=output_stream,
+        page_size=max(3, page_size),
+    )
+
+
+def _supports_raw_selection(*, input_stream: TextIO, output_stream: TextIO) -> bool:
+    if termios is None or tty is None:
+        return False
+    if not bool(getattr(input_stream, "isatty", lambda: False)()) or not bool(getattr(output_stream, "isatty", lambda: False)()):
+        return False
+    return hasattr(input_stream, "fileno")
+
+
+def _select_option_via_prompt(
+    *,
+    title: str,
+    options: Sequence[SelectionOption[T]],
+    input_stream: TextIO,
+    output_stream: TextIO,
+) -> T | None:
+    output_stream.write(title + "\n")
+    for index, option in enumerate(options, start=1):
+        suffix = f" ({option.hint})" if option.hint else ""
+        output_stream.write(f"{index}. {option.label}{suffix}\n")
+    output_stream.write("请输入编号并回车，留空取消: ")
+    output_stream.flush()
+    line = input_stream.readline()
+    selected = str(line or "").strip()
+    if not selected:
+        return None
+    if not selected.isdigit():
+        return None
+    index = int(selected) - 1
+    if index < 0 or index >= len(options):
+        return None
+    return options[index].value
+
+
+def _select_option_via_raw_terminal(
+    *,
+    title: str,
+    options: Sequence[SelectionOption[T]],
+    input_stream: TextIO,
+    output_stream: TextIO,
+    page_size: int,
+) -> T | None:
+    fd = input_stream.fileno()
+    original_mode = termios.tcgetattr(fd)
+    selected_index = 0
+    output_stream.write("\x1b[?1049h\x1b[?25l")
+    output_stream.flush()
+    try:
+        tty.setraw(fd)
+        while True:
+            _render_options(
+                title=title,
+                options=options,
+                selected_index=selected_index,
+                output_stream=output_stream,
+                page_size=page_size,
+            )
+            key = _read_key(input_stream)
+            if key in ("\r", "\n"):
+                return options[selected_index].value
+            if key in ("\x03", "\x1b", "q", "Q"):
+                return None
+            if key in ("\x1b[A", "k", "K"):
+                selected_index = (selected_index - 1) % len(options)
+                continue
+            if key in ("\x1b[B", "j", "J"):
+                selected_index = (selected_index + 1) % len(options)
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, original_mode)
+        output_stream.write("\x1b[?25h\x1b[?1049l")
+        output_stream.flush()
+
+
+def _render_options(
+    *,
+    title: str,
+    options: Sequence[SelectionOption[object]],
+    selected_index: int,
+    output_stream: TextIO,
+    page_size: int,
+) -> None:
+    terminal_width = shutil.get_terminal_size((100, 20)).columns
+    total = len(options)
+    page_start = max(0, min(selected_index - page_size // 2, max(total - page_size, 0)))
+    visible = options[page_start: page_start + page_size]
+    lines = _render_multiline_text(title, width=terminal_width)
+    lines.extend(
+        [
+            "↑/↓ 或 j/k 选择，Enter 确认，q / Esc 取消",
+            "",
+        ]
+    )
+    for offset, option in enumerate(visible, start=page_start):
+        marker = ">" if offset == selected_index else " "
+        suffix = f"  [{option.hint}]" if option.hint else ""
+        lines.append(_truncate_line(f"{marker} {option.label}{suffix}", width=terminal_width))
+    if total > page_size:
+        lines.append("")
+        lines.append(f"{selected_index + 1}/{total}")
+    output_stream.write("\x1b[2J\x1b[H")
+    output_stream.write(RAW_TTY_NEWLINE.join(lines))
+    output_stream.flush()
+
+
+def _truncate_line(text: str, *, width: int) -> str:
+    if width <= 0 or len(text) <= width:
+        return text
+    if width <= 1:
+        return text[:width]
+    return text[: width - 1] + "…"
+
+
+def _render_multiline_text(text: str, *, width: int) -> list[str]:
+    parts = text.splitlines() or [text]
+    rendered: list[str] = []
+    wrap_width = max(1, width)
+    for part in parts:
+        if not part:
+            rendered.append("")
+            continue
+        initial_indent = ""
+        subsequent_indent = ""
+        stripped = part.lstrip()
+        if stripped.startswith("- "):
+            leading_spaces = len(part) - len(stripped)
+            initial_indent = part[:leading_spaces] + "- "
+            subsequent_indent = part[:leading_spaces] + "  "
+            content = stripped[2:]
+        else:
+            content = part
+        wrapped = textwrap.wrap(
+            content,
+            width=wrap_width,
+            initial_indent=initial_indent,
+            subsequent_indent=subsequent_indent,
+            replace_whitespace=False,
+            drop_whitespace=False,
+            break_long_words=True,
+        )
+        rendered.extend(wrapped or [""])
+    return rendered
+
+
+def _read_key(input_stream: TextIO) -> str:
+    fd = input_stream.fileno()
+    first_bytes = os.read(fd, 1)
+    if not first_bytes:
+        return ""
+    first = first_bytes.decode("utf-8", errors="ignore")
+    if first != "\x1b":
+        return first
+    chunks = [first]
+    if not select.select([fd], [], [], ESCAPE_SEQUENCE_TIMEOUT_SECONDS)[0]:
+        return first
+    while True:
+        chunk = os.read(fd, 1).decode("utf-8", errors="ignore")
+        if not chunk:
+            break
+        chunks.append(chunk)
+        if len(chunks) >= 3:
+            break
+        if not select.select([fd], [], [], ESCAPE_SEQUENCE_FOLLOWUP_TIMEOUT_SECONDS)[0]:
+            break
+    return "".join(chunks)

package/src/qingflow_mcp/errors.py

@@ -54,8 +54,8 @@ class QingflowApiError(Exception):
         )
 
     @classmethod
-    def config_error(cls, message: str) -> "QingflowApiError":
-        return cls(category="config", message=message)
+    def config_error(cls, message: str, *, details: JSONObject | None = None) -> "QingflowApiError":
+        return cls(category="config", message=message, details=details)
 
     @classmethod
     def not_supported(cls, message: str) -> "QingflowApiError":

package/src/qingflow_mcp/export_store.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from datetime import timedelta
+from pathlib import Path
+
+from .import_store import _JsonEntryStore, _store_dir
+
+
+class ExportJobStore(_JsonEntryStore):
+    def __init__(self, base_dir: Path | None = None, *, ttl_seconds: int = 24 * 3600) -> None:
+        super().__init__(
+            base_dir=base_dir or _store_dir("QINGFLOW_MCP_EXPORT_JOB_HOME", "export-jobs"),
+            ttl=timedelta(seconds=ttl_seconds),
+        )

package/src/qingflow_mcp/public_surface.py

@@ -80,8 +80,9 @@ USER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
     ),
     PublicToolSpec(USER_DOMAIN, "record_member_candidates", ("record_member_candidates",), cli_public=False),
     PublicToolSpec(USER_DOMAIN, "record_department_candidates", ("record_department_candidates",), cli_public=False),
-    PublicToolSpec(USER_DOMAIN, "record_analyze", ("record_analyze",), ("record", "analyze")),
+    PublicToolSpec(USER_DOMAIN, "record_analyze", ("record_analyze",), ("record", "analyze"), mcp_public=False),
     PublicToolSpec(USER_DOMAIN, "record_list", ("record_list",), ("record", "list"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "record_access", ("record_access",), ("record", "access"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "record_get", ("record_get_public",), ("record", "get"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "record_insert", ("record_insert_public",), ("record", "insert"), cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(USER_DOMAIN, "record_update", ("record_update_public",), ("record", "update"), cli_show_effective_context=True, cli_context_write=True),
@@ -91,6 +92,10 @@ USER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
     PublicToolSpec(USER_DOMAIN, "record_import_repair_local", ("record_import_repair_local",), ("import", "repair")),
     PublicToolSpec(USER_DOMAIN, "record_import_start", ("record_import_start",), ("import", "start")),
     PublicToolSpec(USER_DOMAIN, "record_import_status_get", ("record_import_status_get",), ("import", "status")),
+    PublicToolSpec(USER_DOMAIN, "record_export_start", ("record_export_start",), ("export", "start"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "record_export_status_get", ("record_export_status_get",), ("export", "status"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "record_export_get", ("record_export_get",), ("export", "get"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "record_export_direct", ("record_export_direct",), ("export", "direct"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "record_code_block_run", ("record_code_block_run",), ("record", "code-block-run"), cli_show_effective_context=True, cli_context_write=True),
     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),
@@ -130,6 +135,7 @@ BUILDER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
     PublicToolSpec(BUILDER_DOMAIN, "role_create", ("role_create",), ("builder", "role", "create"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(BUILDER_DOMAIN, "app_release_edit_lock_if_mine", ("app_release_edit_lock_if_mine",), ("builder", "app", "release-edit-lock-if-mine"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(BUILDER_DOMAIN, "app_resolve", ("app_resolve",), ("builder", "app", "resolve"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "button_style_catalog_get", ("button_style_catalog_get",), ("builder", "button", "catalog"), has_contract=True, cli_show_effective_context=True),
     PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_list", ("app_custom_button_list",), ("builder", "button", "list"), has_contract=True, cli_show_effective_context=True),
     PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_get", ("app_custom_button_get",), ("builder", "button", "get"), has_contract=True, cli_show_effective_context=True),
     PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_create", ("app_custom_button_create",), ("builder", "button", "create"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),

package/src/qingflow_mcp/response_trim.py

@@ -65,7 +65,10 @@ def trim_success_response(tool_name: str | None, payload: dict[str, Any]) -> dic
     if not isinstance(payload, dict):
         return payload
     trimmed = deepcopy(payload)
-    _drop_top_keys(trimmed, COMMON_SUCCESS_DROP_TOP)
+    drop_keys = COMMON_SUCCESS_DROP_TOP
+    if tool_name == "user:record_get":
+        drop_keys = COMMON_SUCCESS_DROP_TOP - {"output_profile"}
+    _drop_top_keys(trimmed, drop_keys)
     transformer = SUCCESS_POLICY_BY_TOOL.get(tool_name or "")
     if transformer is not None:
         transformer(trimmed)
@@ -395,6 +398,9 @@ def _trim_record_write(payload: JSONObject) -> None:
 
 
 def _trim_record_get(payload: JSONObject) -> None:
+    if payload.get("fields") is not None or payload.get("semantic_context") is not None:
+        _trim_detail_context_record_get(payload)
+        return
     data = payload.get("data")
     if not isinstance(data, dict):
         return
@@ -417,22 +423,142 @@ def _trim_record_get(payload: JSONObject) -> None:
     payload["data"] = compact
 
 
+def _trim_detail_context_record_get(payload: JSONObject) -> None:
+    _trim_item_list(
+        payload,
+        "fields",
+        allowed=("field_id", "title", "type", "value", "display_value", "requested_focus", "asset_ids", "file_asset_ids"),
+    )
+    references = payload.get("references")
+    if isinstance(references, list):
+        compact_refs: list[JSONObject] = []
+        for item in references:
+            if not isinstance(item, dict):
+                continue
+            compact = _pick(
+                item,
+                (
+                    "field_id",
+                    "field_title",
+                    "target_app_key",
+                    "target_record_id",
+                    "target_title",
+                    "target_detail_completeness",
+                    "self_reference",
+                ),
+            )
+            target_fields = item.get("target_fields") if isinstance(item.get("target_fields"), list) else []
+            if target_fields:
+                compact["target_fields"] = [
+                    _pick(field, ("field_id", "title", "type", "value", "display_value", "asset_ids", "file_asset_ids"))
+                    for field in target_fields
+                    if isinstance(field, dict)
+                ]
+            compact_refs.append(compact)
+        payload["references"] = compact_refs
+    media_assets = payload.get("media_assets")
+    if isinstance(media_assets, dict):
+        compact_media = _pick(media_assets, ("status", "local_dir", "warnings"))
+        items = media_assets.get("items") if isinstance(media_assets.get("items"), list) else []
+        compact_media["items"] = [
+            _pick(
+                item,
+                (
+                    "asset_id",
+                    "kind",
+                    "source",
+                    "field_id",
+                    "field_title",
+                    "local_path",
+                    "access_status",
+                    "readable_by_agent",
+                    "mime_type",
+                    "size_bytes",
+                    "download_strategy",
+                    "storage_auth_type",
+                    "storage_cookie_prefix",
+                    "redirected",
+                ),
+            )
+            for item in items
+            if isinstance(item, dict)
+        ]
+        payload["media_assets"] = compact_media
+    file_assets = payload.get("file_assets")
+    if isinstance(file_assets, dict):
+        compact_files = _pick(file_assets, ("status", "local_dir", "warnings"))
+        items = file_assets.get("items") if isinstance(file_assets.get("items"), list) else []
+        compact_files["items"] = [
+            _pick(
+                item,
+                (
+                    "file_asset_id",
+                    "media_asset_id",
+                    "kind",
+                    "source",
+                    "field_id",
+                    "field_title",
+                    "file_name",
+                    "local_path",
+                    "access_status",
+                    "readable_by_agent",
+                    "mime_type",
+                    "size_bytes",
+                    "download_strategy",
+                    "storage_auth_type",
+                    "storage_cookie_prefix",
+                    "redirected",
+                    "extraction",
+                ),
+            )
+            for item in items
+            if isinstance(item, dict)
+        ]
+        payload["file_assets"] = compact_files
+    for key in ("data_logs", "workflow_logs"):
+        node = payload.get(key)
+        if not isinstance(node, dict):
+            continue
+        compact_node = _pick(
+            node,
+            (
+                "status",
+                "visible",
+                "reason",
+                "page",
+                "page_size",
+                "items_loaded",
+                "reported_total",
+                "has_more",
+                "complete",
+                "items",
+            ),
+        )
+        payload[key] = compact_node
+    associated_resources = payload.get("associated_resources")
+    if isinstance(associated_resources, list):
+        payload["associated_resources"] = [
+            _pick(item, ("type", "name", "app_key", "app_name", "view_key", "chart_key", "view_type", "data_access"))
+            for item in associated_resources
+            if isinstance(item, dict)
+        ]
+    _drop_deep_keys(payload, {"raw", "debug"})
+
+
 def _trim_record_list(payload: JSONObject) -> None:
     data = payload.get("data")
     if not isinstance(data, dict):
         return
     pagination = data.get("pagination") if isinstance(data.get("pagination"), dict) else {}
-    returned_items = pagination.get("returned_items")
-    result_amount = pagination.get("result_amount")
-    limit = pagination.get("limit")
-    truncated = False
-    if isinstance(result_amount, int) and isinstance(returned_items, int):
+    returned_items = pagination.get("returned_count", pagination.get("returned_items"))
+    result_amount = pagination.get("total_count", pagination.get("result_amount"))
+    truncated = bool(pagination.get("truncated"))
+    if not truncated and isinstance(result_amount, int) and isinstance(returned_items, int):
         truncated = result_amount > returned_items
     compact_pagination = {
         "loaded": True,
-        "page_size": limit,
-        "fetched_pages": 1,
-        "reported_total": result_amount,
+        "returned_count": returned_items,
+        "total_count": result_amount,
         "truncated": truncated,
     }
     selection = data.get("selection") if isinstance(data.get("selection"), dict) else {}
@@ -445,6 +571,43 @@ def _trim_record_list(payload: JSONObject) -> None:
     if view:
         compact["view"] = _pick(view, ("view_id", "name"))
     payload["data"] = compact
+    lookup = payload.get("lookup") if isinstance(payload.get("lookup"), dict) else {}
+    if lookup:
+        payload["lookup"] = {
+            "mode": lookup.get("mode"),
+            "query": lookup.get("query"),
+            "total_count": lookup.get("total_count", lookup.get("reported_total")),
+            "returned_count": lookup.get("returned_count"),
+            "truncated": lookup.get("truncated"),
+            "confidence": lookup.get("confidence"),
+            "next_action": lookup.get("next_action"),
+        }
+
+
+def _trim_record_access(payload: JSONObject) -> None:
+    compact: dict[str, Any] = {}
+    for key in (
+        "ok",
+        "status",
+        "app_key",
+        "view_id",
+        "format",
+        "local_dir",
+        "row_count",
+        "complete",
+        "truncated",
+        "safe_for_final_conclusion",
+        "files",
+        "fields",
+        "warnings",
+        "verification",
+        "scope",
+    ):
+        value = payload.get(key)
+        if value is not None:
+            compact[key] = value
+    payload.clear()
+    payload.update(compact)
 
 
 def _trim_record_analyze(payload: JSONObject) -> None:
@@ -666,7 +829,6 @@ def _trim_import_status_payload(payload: JSONObject) -> None:
         "total_rows",
         "success_rows",
         "failed_rows",
-        "error_file_urls",
         "operate_time",
         "operate_user",
         "verification",
@@ -674,6 +836,10 @@ def _trim_import_status_payload(payload: JSONObject) -> None:
         payload.pop(key, None)
 
 
+def _trim_export_payload(payload: JSONObject) -> None:
+    payload.pop("backend_export_id", None)
+
+
 def _summarize_import_issues(issues: list[Any]) -> dict[str, Any]:
     total = 0
     error_count = 0
@@ -756,6 +922,16 @@ _register_policy(
     ),
     _trim_import_schema,
 )
+_register_policy(
+    (USER_DOMAIN,),
+    (
+        "record_export_start",
+        "record_export_status_get",
+        "record_export_get",
+        "record_export_direct",
+    ),
+    _trim_export_payload,
+)
 _register_policy(
     (USER_DOMAIN,),
     (
@@ -770,6 +946,7 @@ _register_policy(
 _register_policy((USER_DOMAIN,), ("record_insert", "record_update"), _trim_record_write)
 _register_policy((USER_DOMAIN,), ("record_get",), _trim_record_get)
 _register_policy((USER_DOMAIN,), ("record_list",), _trim_record_list)
+_register_policy((USER_DOMAIN,), ("record_access",), _trim_record_access)
 _register_policy((USER_DOMAIN,), ("record_analyze",), _trim_record_analyze)
 _register_policy((USER_DOMAIN,), ("record_code_block_run",), _trim_code_block_run)
 _register_policy((USER_DOMAIN,), ("task_list",), _trim_task_list)
@@ -818,6 +995,7 @@ _register_policy(
         "role_create",
         "app_release_edit_lock_if_mine",
         "app_resolve",
+        "button_style_catalog_get",
         "app_custom_button_list",
         "app_custom_button_get",
         "app_custom_button_create",

package/src/qingflow_mcp/server.py

@@ -10,6 +10,7 @@ from .tools.app_tools import AppTools
 from .tools.auth_tools import AuthTools
 from .tools.code_block_tools import CodeBlockTools
 from .tools.feedback_tools import FeedbackTools
+from .tools.export_tools import ExportTools
 from .tools.file_tools import FileTools
 from .tools.import_tools import ImportTools
 from .tools.package_tools import PackageTools
@@ -49,14 +50,15 @@ All resource tools operate with the logged-in user's Qingflow permissions.
 
 If `app_key` is unknown, use `app_list` or `app_search` first.
 If the app is known but the data range is not, use `app_get` first and choose from `accessible_views`.
-If an accessible view has `analysis_supported=false`, do not use it for `record_list` or `record_analyze`. `boardView` and `ganttView` are special UI views, not list/analyze targets.
+If an accessible view has `analysis_supported=false`, do not use it for `record_access` or `record_list`. `boardView` and `ganttView` are special UI views, not data-access targets.
+`view_get(view_id=...)` also returns `export_capability`; it only means there is a supported export route, not that export permission has been verified.
 
 ## Schema-First Rule
 
 Call `record_insert_schema_get` before `record_insert`.
 Call `record_update_schema_get` before `record_update`.
 Call `record_code_block_schema_get` before `record_code_block_run`.
-Call `app_get` first when the data range is unclear, then use `record_browse_schema_get(view_id=...)` before `record_list`, `record_get`, or `record_analyze`.
+Call `app_get` first when the data range is unclear, then use `record_browse_schema_get(view_id=...)` before `record_access`, `record_list`, or `record_get`.
 Call `record_import_schema_get` when the import field mapping is unclear before template download or verify.
 
 - All `field_id` values must come from the schema response.
@@ -66,7 +68,8 @@ Call `record_import_schema_get` when the import field mapping is unclear before
 
 `record_insert_schema_get` returns the current user's insert-ready applicant schema; read `required_fields`, `optional_fields`, `runtime_linked_required_fields`, and `payload_template`.
 `record_update_schema_get` returns the current record's overall update-ready writable field set across matched accessible views; read `writable_fields` and `payload_template`.
-`record_browse_schema_get(view_id=...)` returns browse-schema fields for the selected accessible view.
+`record_browse_schema_get(view_id=...)` returns the same readable fields shown in the selected Qingflow table view header.
+`record_access.fields` / CSV columns and `record_list.columns / where / order_by / query_fields` use that exact same view schema.
 `record_code_block_schema_get` returns code-block-ready schema for exact code block field selection.
 `record_import_schema_get` returns import-ready column metadata.
 
@@ -76,16 +79,17 @@ Call `record_import_schema_get` when the import field mapping is unclear before
 
 ## Analytics Path
 
-`app_get -> record_browse_schema_get(view_id=...) -> record_analyze`
+`app_get -> record_browse_schema_get(view_id=...) -> record_access -> Python`
 
 Prefer `view_id` entries from `accessible_views` where `analysis_supported=true`.
 
+Use `record_access` to write local CSV shard files for analysis, then use Python to compute counts, rankings, ratios, trends, and final conclusions.
+
 Use this DSL shape:
 
-- `dimensions`: `{{field_id, alias, bucket}}`
-- `metrics`: `{{op, field_id, alias}}`
-- `filters`: `{{field_id, op, value}}`
-- `sort`: `{{by, order}}`
+- `columns`: `[{{field_id}}]`
+- `where`: `[{{field_id, op, value}}]`
+- `order_by`: `[{{field_id, direction}}]`
 
 Important key rules:
 
@@ -106,6 +110,7 @@ Analysis answers must include concrete numbers. When applicable, include percent
 `record_code_block_schema_get -> record_code_block_run`
 
 - Use `columns` as `[{{field_id}}]`
+- Use `record_list(query=..., query_fields=[{{field_id}}])` for fuzzy single-record lookup, then follow `lookup.next_action`; `query_fields` is search scope and `columns` is display shape.
 - Use `where` items as `{{field_id, op, value}}`
 - Use `order_by` items as `{{field_id, direction}}`
 - Legacy forms such as bare integer `field_id`, `fieldId`, `operator`, `values`, or `order` may still parse, but they are compatibility-only and not the canonical DSL
@@ -119,7 +124,10 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - `linkage.kind=logic_visibility` means linked visibility or option-driven rules are involved; `linkage.kind=reference_fill` means reference/default matching logic is involved; `linkage.kind=formula_fill` means formula/default auto-fill logic is involved.
 - `record_update_schema_get` exposes the overall writable field set for the record, but not every field combination is guaranteed; `record_update` still needs one single matched accessible view that can cover the payload.
 - `record_delete` deletes by `record_id` or `record_ids`.
-- When readback shape matters after insert or update, prefer `record_get(..., output_profile="normalized")` or `record_list(..., output_profile="normalized")`.
+- `record_get` is the single-record frontend detail context tool. It returns detail-page visible fields, one-level relation targets, first-page data/workflow logs, associated views/reports, local readable image assets, local downloadable file assets, unavailable context, and `semantic_context`.
+- Read record images from `record_get.media_assets.items[].local_path` when `readable_by_agent=true`; read attachments/documents/tables from `record_get.file_assets.items[].local_path` and `extraction.text_path` when present. `record_get` follows the frontend storage cookie redirect path for Qingflow attachments, and remote file URLs should not be treated as directly readable.
+- `record_get.columns` are focus hints only; they do not project the detail fields. Read facts from top-level `fields[]`.
+- When readback shape matters after insert or update, prefer `record_get` for human/detail-page context, or `record_list(..., output_profile="normalized")` for batch-shaped normalized rows.
 
 - Read relation targets from `record_insert_schema_get` / `record_update_schema_get` relation metadata before preparing relation writes.
 - Member and department fields may be written with natural strings directly on `record_insert` / `record_update`; only fall back to `record_member_candidates` or `record_department_candidates` when the user wants explicit candidate browsing or the write returns ambiguity that needs confirmation.
@@ -147,6 +155,25 @@ Use `record_code_block_run` when the user wants to execute a form code-block fie
 - Do not modify user-uploaded files unless the user explicitly authorizes repair.
 - If repair is authorized, keep the original file and repair a copy, then run `record_import_verify` again before `record_import_start`.
 
+## Export Path
+
+`view_get -> record_export_start -> record_export_status_get -> record_export_get`
+
+- `record_export_direct` is the one-shot export path that starts the export, waits for completion, downloads locally, and still returns remote download links.
+- Export v1 supports record views only and follows the same public `view_id` semantics as `record_list` (`system:*` and `custom:*`).
+- `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
+  - pass `order_by` to keep the internal query and export row order aligned with `record_list`
+  - then run native export as selected rows
+  - `where/order_by` 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
+- `include_workflow_log=true` maps to the native workflow-log export switch.
+
 ## Task Workflow Path
 
 `task_list -> task_get -> task_action_execute`
@@ -190,6 +217,7 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
     WorkspaceTools(sessions, backend).register(server)
     FileTools(sessions, backend).register(server)
     ImportTools(sessions, backend).register(server)
+    ExportTools(sessions, backend).register(server)
     CodeBlockTools(sessions, backend).register(server)
     TaskContextTools(sessions, backend).register(server)
     RoleTools(sessions, backend).register(server)

package/src/qingflow_mcp/server_app_builder.py

@@ -290,6 +290,10 @@ def build_builder_server() -> FastMCP:
             )
         return ai_builder.app_resolve(profile=profile, app_key=app_key, app_name=app_name, package_id=package_id)
 
+    @server.tool()
+    def button_style_catalog_get(profile: str = DEFAULT_PROFILE) -> dict:
+        return ai_builder.button_style_catalog_get(profile=profile)
+
     @server.tool()
     def app_custom_button_list(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:
         return ai_builder.app_custom_button_list(profile=profile, app_key=app_key)