@josephyan/qingflow-app-user-mcp 1.0.7 → 1.0.8

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-user-mcp@1.0.7
+npm install @josephyan/qingflow-app-user-mcp@1.0.8
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-user-mcp@1.0.7 qingflow-app-user-mcp
+npx -y -p @josephyan/qingflow-app-user-mcp@1.0.8 qingflow-app-user-mcp
 ```
 
 Environment:

package/package.json

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

package/skills/qingflow-app-user/references/public-surface-sync.md

@@ -8,6 +8,7 @@ It is not a user-facing product spec. It exists to prevent skill drift.
 ### User data
 
 - Read range first with `app_get`, then `record_browse_schema_get(view_id=...)`
+- Treat `record_browse_schema_get.fields` as the selected Qingflow table view header schema; `record_access.fields` and `schema.json` must stay aligned with it.
 - Standard flows:
   - analyze: `app_get -> record_browse_schema_get -> record_access -> Python`
   - browse detail: `app_get -> record_browse_schema_get -> record_list / record_get`

package/skills/qingflow-record-analysis/SKILL.md

@@ -9,7 +9,7 @@ metadata:
 
 This skill is for final statistical conclusions only.
 Assumes MCP is connected, authenticated, and on the correct workspace.
-Analysis tasks must start with `app_get`, then `record_browse_schema_get(view_id=...)`. Read top-level `fields` and `suggested_*`, then choose field_id-based columns and filters only.
+Analysis tasks must start with `app_get`, then `record_browse_schema_get(view_id=...)`. `record_browse_schema_get.fields` is the selected Qingflow table view's readable header schema and is the same field source used by `record_access.fields` / `schema.json`. Read top-level `fields` and `suggested_*`, then choose field_id-based columns and filters only.
 If `app_get.accessible_views` marks a view with `analysis_supported=false`, do not use that view for `record_access`, `record_list`, or `record_analyze`. `boardView` and `ganttView` are special UI views, not data-access targets.
 
 ## Step 1: `app_get` → Step 2: `record_browse_schema_get(view_id=...)` → Step 3: `record_access` → Step 4: Python
@@ -76,6 +76,7 @@ Use `record_access` to fetch detail rows into local CSV shards. It does not anal
 Then run Python against every `files[].local_path`. CSV columns are stable: `record_id`, then `field_<field_id>`. Use `fields[]` plus `metadata_files.schema` / `metadata_files.readme` in the same output directory to map titles and types, especially when reusing the CSV later.
 
 - Never ask for `page`, `page_size`, `limit`, or `max_rows`; `record_access` owns paging internally and follows the backend's native paging capability.
+- Never treat backend `searchQueIds` as column selection; it is only a full-text search scope.
 - If multiple CSV files are returned, read them all.
 - If `complete=false` or `safe_for_final_conclusion=false`, downgrade the answer and disclose the limitation.
 - `record_export_direct` is only for explicit export/download/Excel requests, not default analysis.

package/skills/qingflow-record-analysis/references/analysis-patterns.md

@@ -33,7 +33,7 @@ Result reading order:
 6. `record_access.fields`
 7. `record_access.warnings`
 
-Treat `record_browse_schema_get` as the browse-schema source of truth. Missing fields are permission boundaries, not invitations to guess hidden ids.
+Treat `record_browse_schema_get` as the browse-schema source of truth. It matches the selected Qingflow table view header and is the same schema source used by `record_access.fields` and `schema.json`. Missing fields are permission boundaries, not invitations to guess hidden ids.
 
 ## Lightweight `record_analyze` helper sequence
 

package/src/qingflow_mcp/server_app_user.py

@@ -60,7 +60,9 @@ 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`.
 Inside `optional_fields`, any field with `may_become_required=true` is still writable, but may become required when linked visibility or option-driven runtime rules activate.
 `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` and its `schema.json` use that exact same view schema; a missing field means it is not readable in that view.
+`searchQueIds` is a backend full-text search scope, not an output-column/projection mechanism.
 `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.
 

package/src/qingflow_mcp/tools/record_tools.py

@@ -602,7 +602,7 @@ class RecordTools(ToolBase):
                             ),
                         }
                     )
-                browse_scope = self._build_browse_write_scope(
+                browse_scope = self._build_browse_read_scope(
                     profile,
                     context,
                     app_key,
@@ -1848,25 +1848,20 @@ class RecordTools(ToolBase):
         sorts = self._normalize_record_list_order_by(order_by)
 
         def runner(session_profile, context):
-            index = self._get_field_index(profile, context, app_key, force_refresh=False)
-            selected_fields = self._resolve_select_columns(
+            browse_scope = self._build_browse_read_scope(
+                profile,
+                context,
+                app_key,
+                view_route,
+                force_refresh=False,
+            )
+            index = cast(FieldIndex, browse_scope["index"])
+            selected_fields = self._resolve_record_access_columns(
                 normalized_columns,
                 index,
-                max_columns=len(normalized_columns),
-                default_limit=MAX_LIST_COLUMN_LIMIT,
+                view_route=view_route,
             )
-            selected_field_batches = _chunk_fields(selected_fields, BACKEND_LIST_SEARCH_FIELD_LIMIT)
-            primary_search_que_ids: list[int] | None = [field.que_id for field in selected_field_batches[0]]
             view_selection = view_route.view_selection
-            if view_selection is not None and not _view_selection_supported_by_search_ids(
-                view_selection,
-                primary_search_que_ids,
-            ):
-                primary_search_que_ids = None
-                remaining_field_batches: list[list[FormField]] = []
-            else:
-                remaining_field_batches = selected_field_batches[1:]
-                primary_search_que_ids = primary_search_que_ids or None
             match_rules = self._resolve_match_rules(context, filters, index)
             sort_rules = self._resolve_sorts(sorts, index)
             used_list_type: int | None = None
@@ -1949,7 +1944,7 @@ class RecordTools(ToolBase):
                                     query_key=None,
                                     match_rules=match_rules,
                                     sorts=sort_rules,
-                                    search_que_ids=primary_search_que_ids,
+                                    search_que_ids=None,
                                     list_type=candidate_list_type,
                                 )
                                 used_list_type = None if view_selection is not None else candidate_list_type
@@ -1976,7 +1971,7 @@ class RecordTools(ToolBase):
                             query_key=None,
                             match_rules=match_rules,
                             sorts=sort_rules,
-                            search_que_ids=primary_search_que_ids,
+                            search_que_ids=None,
                             list_type=used_list_type,
                         )
                     page_rows = page.get("list")
@@ -1996,34 +1991,6 @@ class RecordTools(ToolBase):
                             continue
                         page_apply_order.append(apply_id)
                         page_answer_map[apply_id] = cast(list[JSONValue], answer_list)
-                    if page_apply_order and remaining_field_batches:
-                        for batch in remaining_field_batches:
-                            extra_page = self._search_page(
-                                context,
-                                app_key=app_key,
-                                view_selection=view_selection,
-                                page_num=current_page,
-                                page_size=BACKEND_RECORD_ACCESS_PAGE_SIZE,
-                                query_key=None,
-                                match_rules=match_rules,
-                                sorts=sort_rules,
-                                search_que_ids=[field.que_id for field in batch],
-                                list_type=used_list_type or DEFAULT_RECORD_LIST_TYPE,
-                            )
-                            extra_rows = extra_page.get("list")
-                            extra_items = extra_rows if isinstance(extra_rows, list) else []
-                            for extra_item in extra_items:
-                                if not isinstance(extra_item, dict):
-                                    continue
-                                apply_id = _coerce_count(extra_item.get("applyId")) or _coerce_count(extra_item.get("id"))
-                                if apply_id is None or apply_id not in page_answer_map:
-                                    continue
-                                extra_answers = extra_item.get("answers")
-                                extra_answer_list = extra_answers if isinstance(extra_answers, list) else []
-                                page_answer_map[apply_id] = _merge_answer_lists_by_field_id(
-                                    page_answer_map.get(apply_id, []),
-                                    cast(list[JSONValue], extra_answer_list),
-                                )
                     for apply_id in page_apply_order:
                         write_record(apply_id, page_answer_map.get(apply_id, []))
                     if not has_more:
@@ -7427,6 +7394,39 @@ class RecordTools(ToolBase):
         self._form_cache[cache_key] = normalized
         return normalized
 
+    def _get_system_browse_base_info_schema(
+        self,
+        profile: str,
+        context,  # type: ignore[no-untyped-def]
+        app_key: str,
+        *,
+        list_type: int,
+        force_refresh: bool,
+    ) -> JSONObject:
+        """Return system view apply/baseInfo without falling back to app form metadata."""
+        cache_key = (profile, app_key, "browse_system_base_info", list_type)
+        if not force_refresh and cache_key in self._form_cache:
+            return self._form_cache[cache_key]
+        payload = self.backend.request(
+            "GET",
+            context,
+            f"/app/{app_key}/apply/baseInfo",
+            params={"type": list_type},
+        )
+        normalized = _normalize_data_list_base_info_schema(payload)
+        self._form_cache[cache_key] = normalized
+        return normalized
+
+    def _get_custom_view_browse_schema(self, profile: str, context, view_key: str, *, force_refresh: bool) -> JSONObject:  # type: ignore[no-untyped-def]
+        """Return the same baseInfo schema used by the Qingflow table view UI."""
+        cache_key = (profile, f"view:{view_key}", "browse_view_base_info", None)
+        if not force_refresh and cache_key in self._form_cache:
+            return self._form_cache[cache_key]
+        payload = self.backend.request("GET", context, f"/view/{view_key}/apply/baseInfo")
+        normalized = _normalize_data_list_base_info_schema(payload)
+        self._form_cache[cache_key] = normalized
+        return normalized
+
     def _get_view_field_index(self, profile: str, context, view_key: str, *, force_refresh: bool) -> FieldIndex:  # type: ignore[no-untyped-def]
         """执行内部辅助逻辑。"""
         return _build_field_index(self._get_view_form_schema(profile, context, view_key, force_refresh=force_refresh))
@@ -7469,6 +7469,80 @@ class RecordTools(ToolBase):
             force_refresh=force_refresh,
         )["index"]
 
+    def _build_browse_read_scope(
+        self,
+        profile: str,
+        context,  # type: ignore[no-untyped-def]
+        app_key: str,
+        resolved_view: AccessibleViewRoute | None,
+        *,
+        force_refresh: bool,
+    ) -> JSONObject:
+        """Build the UI/table-view readable field scope from apply/baseInfo."""
+        applicant_index: FieldIndex | None
+        applicant_writable_field_ids: set[int]
+        try:
+            applicant_index = self._get_applicant_top_level_field_index(profile, context, app_key, force_refresh=force_refresh)
+        except QingflowApiError as exc:
+            if exc.backend_code != 40002:
+                raise
+            applicant_index = None
+            applicant_writable_field_ids = set()
+        else:
+            applicant_writable_field_ids = {
+                field.que_id
+                for field in applicant_index.by_id.values()
+                if bool(self._schema_write_hints(field)["writable"])
+            }
+
+        if resolved_view is not None and resolved_view.kind == "custom" and resolved_view.view_selection is not None:
+            schema = self._get_custom_view_browse_schema(
+                profile,
+                context,
+                resolved_view.view_selection.view_key,
+                force_refresh=force_refresh,
+            )
+            index = _build_top_level_field_index(schema)
+        elif resolved_view is not None and resolved_view.kind == "system" and resolved_view.list_type is not None:
+            schema = self._get_system_browse_base_info_schema(
+                profile,
+                context,
+                app_key,
+                list_type=resolved_view.list_type,
+                force_refresh=force_refresh,
+            )
+            index = _build_top_level_field_index(schema)
+        else:
+            index = applicant_index or _build_top_level_field_index(
+                self._get_form_schema(profile, context, app_key, force_refresh=force_refresh)
+            )
+
+        if applicant_index is not None and index.by_id:
+            enriched_fields = [
+                _enrich_read_field_from_applicant(field, applicant_index.by_id.get(str(field.que_id)))
+                for field in index.by_id.values()
+            ]
+            index = _build_top_level_field_index({"formQues": [[_form_field_to_question(field) for field in enriched_fields]]})
+
+        visible_question_ids = {field.que_id for field in index.by_id.values()}
+        if applicant_index is None:
+            writable_field_ids = {
+                field.que_id
+                for field in index.by_id.values()
+                if bool(self._schema_write_hints(field)["writable"])
+            }
+        else:
+            writable_field_ids = {
+                field_id
+                for field_id in visible_question_ids
+                if field_id in applicant_writable_field_ids
+            }
+        return {
+            "index": index,
+            "writable_field_ids": writable_field_ids,
+            "visible_question_ids": visible_question_ids,
+        }
+
     def _build_browse_write_scope(
         self,
         profile: str,
@@ -9538,6 +9612,44 @@ class RecordTools(ToolBase):
                 break
         return fields
 
+    def _resolve_record_access_columns(
+        self,
+        selectors: list[int],
+        index: FieldIndex,
+        *,
+        view_route: AccessibleViewRoute,
+    ) -> list[FormField]:
+        """Resolve record_access columns against the selected view's baseInfo schema."""
+        if not selectors:
+            raise_tool_error(QingflowApiError.config_error("columns is required"))
+        fields: list[FormField] = []
+        seen: set[int] = set()
+        for selector in selectors:
+            try:
+                field = self._resolve_field_selector(selector, index, location="record_access.columns")
+            except RecordInputError as exc:
+                if exc.error_code == "FIELD_NOT_FOUND":
+                    raise RecordInputError(
+                        message=(
+                            f"record_access column field_id '{selector}' is not in the selected view schema "
+                            f"({view_route.view_id})."
+                        ),
+                        error_code="FIELD_NOT_IN_VIEW_SCHEMA",
+                        fix_hint="Call record_browse_schema_get for this exact view_id and pass only field_id values from its fields[].",
+                        details={
+                            "location": "record_access.columns",
+                            "requested": selector,
+                            "view_id": view_route.view_id,
+                            "view_name": view_route.name,
+                        },
+                    ) from exc
+                raise
+            if field.que_id in seen:
+                continue
+            fields.append(field)
+            seen.add(field.que_id)
+        return fields
+
     def _resolve_summary_preview_fields(
         self,
         selectors: list[str | int],
@@ -11295,6 +11407,38 @@ def _clone_form_field(field: FormField, *, readonly: bool | None = None) -> Form
     )
 
 
+def _enrich_read_field_from_applicant(field: FormField, applicant_field: FormField | None) -> FormField:
+    if applicant_field is None:
+        return field
+    raw = dict(applicant_field.raw) if isinstance(applicant_field.raw, dict) else {}
+    raw.update(dict(field.raw) if isinstance(field.raw, dict) else {})
+    raw["queId"] = field.que_id
+    raw["queTitle"] = field.que_title
+    que_type = field.que_type if field.que_type is not None else applicant_field.que_type
+    if que_type is not None:
+        raw["queType"] = que_type
+    readonly_source = field if any(key in field.raw for key in ("readonly", "beingReadonly", "canEdit")) else applicant_field
+    enriched = FormField(
+        que_id=field.que_id,
+        que_title=field.que_title,
+        que_type=que_type,
+        required=field.required or applicant_field.required,
+        readonly=readonly_source.readonly,
+        system=field.system or applicant_field.system,
+        options=list(field.options or applicant_field.options),
+        aliases=[],
+        target_app_key=field.target_app_key or applicant_field.target_app_key,
+        target_app_name_hint=field.target_app_name_hint or applicant_field.target_app_name_hint,
+        member_select_scope_type=field.member_select_scope_type if field.member_select_scope_type is not None else applicant_field.member_select_scope_type,
+        member_select_scope=field.member_select_scope or applicant_field.member_select_scope,
+        dept_select_scope_type=field.dept_select_scope_type if field.dept_select_scope_type is not None else applicant_field.dept_select_scope_type,
+        dept_select_scope=field.dept_select_scope or applicant_field.dept_select_scope,
+        raw=raw,
+    )
+    enriched.aliases = sorted(_field_alias_candidates(enriched))
+    return enriched
+
+
 def _form_field_to_question(field: FormField) -> JSONObject:
     question = dict(field.raw) if isinstance(field.raw, dict) else {}
     question.setdefault("queId", field.que_id)