@josephyan/qingflow-app-user-mcp 0.2.0-beta.27 → 0.2.0-beta.29

package/README.md

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

package/package.json

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

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 `record_schema_get`. Use field_id-based DSLs only.
+Analysis tasks must start with `record_schema_get`. Read top-level `fields` and `suggested_*`, then build field_id-based DSLs only.
 
 ## Step 1: `record_schema_get` → Step 2: build DSL → Step 3: `record_analyze`
 

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

@@ -27,7 +27,7 @@ Use exactly one of these default paths:
 - `record_get`
 - `record_write`
 
-`record_schema_get` only exposes the current user's applicant-node visible fields; if a field is missing, treat it as unavailable in the current permission scope.
+`record_schema_get` only exposes the current user's applicant-node visible fields. Read top-level `fields` and `suggested_*`; if a field is missing, treat it as unavailable in the current permission scope.
 
 ## Supporting Tools
 
@@ -42,6 +42,8 @@ Use exactly one of these default paths:
 - `file_get_upload_info`
 - `file_upload_local`
 
+Use `record_member_candidates` / `record_department_candidates` as the default lookup path for member or department fields. Treat `directory_*` as org-browse or fallback tooling, not the primary field-candidate path.
+
 ## Standard Operating Order
 
 1. Ensure auth exists
@@ -58,6 +60,7 @@ Use exactly one of these default paths:
 ## Record Read Rules
 
 - Use `record_list` for browse/export/sample inspection only
+- For `columns`, prefer `[{ "field_id": 12 }]`; bare integer field ids are accepted for compatibility
 - Use `record_get` when `record_id` is known
 - `record_get` without explicit `columns` still returns only applicant-node visible fields; do not assume it exposes the full builder-side record
 - `record_list` and `record_get` may reject hidden-field `field_id`s because record tools now validate against the applicant-node visible schema only
@@ -101,8 +104,16 @@ The DSL is clause-shaped like SQL, but it is **not raw SQL text**.
 - Do not auto-resolve relation targets without first querying them
 - Do not assume member display names resolve automatically; `record_member_candidates` returns ids, but direct name-to-id write is not automatic
 - Do not assume department names resolve automatically; `record_department_candidates` returns ids, but direct name-to-id write is not automatic
+- For default-all member or department fields, prefer the field candidate tools; do not start with `directory_*`
 - Do not assume `record_schema_get` is a builder/full-field schema.
 
+### Complex field quick examples
+
+- `member`: `✅ {"field_id":5,"value":{"id":7}}` / `❌ {"field_id":5,"value":"张三"}`
+- `department`: `✅ {"field_id":22,"value":{"id":336193,"value":"北斗组"}}` / `❌ {"field_id":22,"value":"北斗组"}`
+- `relation`: `✅ {"field_id":25,"value":{"apply_id":5001}}` / `❌ {"field_id":25,"value":"客户A"}`
+- `attachment`: upload first, then `✅ {"field_id":13,"value":{"value":"https://.../a.pdf","name":"a.pdf"}}` / `❌ {"field_id":13,"value":"/tmp/a.pdf"}`
+
 ## Response Interpretation
 
 - `record_list` returns browse/sample data, not final analysis conclusions

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

@@ -15,7 +15,7 @@ Remember that `record_schema_get` only exposes the current user's applicant-node
 
 Keep the browse DSL simple:
 
-- `columns`: field ids only
+- `columns`: prefer `[{ "field_id": 12 }]`; bare integers are accepted for compatibility
 - `where`: flat AND filters only
 - `order_by`: field sorting only
 - `limit` and `page`: browsing intent only
@@ -110,3 +110,21 @@ If the payload includes them, stop after the blocked `record_write` response and
 - Relation fields are record-id based. Resolve the referenced target first, then write the relation field with the real `record_id`.
 - Attachment fields are two-step: upload first with `file_upload_local`, then reuse the returned attachment payload in `record_write`.
 - Subtable writes require the current schema shape; when updating existing subtable rows, preserve row ids if the current record exposes them.
+
+### Quick field examples
+
+```json
+{ "field_id": 5, "value": { "id": 7 } }
+```
+
+```json
+{ "field_id": 22, "value": { "id": 336193, "value": "北斗组" } }
+```
+
+```json
+{ "field_id": 25, "value": { "apply_id": 5001 } }
+```
+
+```json
+{ "field_id": 13, "value": { "value": "https://.../a.pdf", "name": "a.pdf" } }
+```

package/src/qingflow_mcp/__init__.py

@@ -2,4 +2,4 @@ from __future__ import annotations
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.0b27"
+__version__ = "0.2.0b29"

package/src/qingflow_mcp/server.py

@@ -53,6 +53,7 @@ Always call `record_schema_get` before `record_list`, `record_get`, `record_writ
 
 - Hidden fields are omitted.
 - Missing fields mean the field is not visible in the current permission scope.
+- Read `fields` and `suggested_*` from the top level of the schema response.
 
 ## Analytics Path
 
@@ -79,6 +80,8 @@ Analysis answers must include concrete numbers. When applicable, include percent
 
 `record_schema_get -> record_list / record_get / record_write`
 
+- For `columns`, prefer `[{{field_id}}]`; bare integer field ids remain supported for compatibility.
+
 `record_write` uses SQL-like JSON clauses:
 
 - `insert` -> `values`
@@ -87,6 +90,7 @@ Analysis answers must include concrete numbers. When applicable, include percent
 
 - Read relation targets from `record_schema_get.target_app_key` / `target_app_name` before preparing relation writes.
 - If a member or department field id is known but candidate ids are not, use `record_member_candidates` or `record_department_candidates` before `record_write`.
+- For default-all member or department fields, prefer those field candidate tools instead of starting with `directory_*`.
 
 ## Task Center Path
 

package/src/qingflow_mcp/server_app_user.py

@@ -41,6 +41,7 @@ Always call `record_schema_get` before `record_list`, `record_get`, `record_writ
 
 - Hidden fields are omitted.
 - Missing fields mean the field is not visible in the current permission scope.
+- Read `fields` and `suggested_*` from the top level of the schema response.
 
 ## Analytics Path
 
@@ -67,6 +68,8 @@ Analysis answers must include concrete numbers. When applicable, include percent
 
 `record_schema_get -> record_list / record_get / record_write`
 
+- For `columns`, prefer `[{{field_id}}]`; bare integer field ids remain supported for compatibility.
+
 `record_write` uses SQL-like JSON clauses:
 
 - `insert` -> `values`
@@ -75,6 +78,7 @@ Analysis answers must include concrete numbers. When applicable, include percent
 
 - Read relation targets from `record_schema_get.target_app_key` / `target_app_name` before preparing relation writes.
 - If a member or department field id is known but candidate ids are not, use `record_member_candidates` or `record_department_candidates` before `record_write`.
+- For default-all member or department fields, prefer those field candidate tools instead of starting with `directory_*`.
 
 ## Task Center Path
 

package/src/qingflow_mcp/tools/record_tools.py

@@ -269,7 +269,7 @@ class RecordTools(ToolBase):
         def record_list(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
-            columns: list[int] | None = None,
+            columns: list[JSONObject | int] | None = None,
             where: list[JSONObject] | None = None,
             order_by: list[JSONObject] | None = None,
             limit: int = 50,
@@ -296,7 +296,7 @@ class RecordTools(ToolBase):
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
             record_id: int = 0,
-            columns: list[int] | None = None,
+            columns: list[JSONObject | int] | None = None,
             workflow_node_id: int | None = None,
             output_profile: str = "normal",
         ) -> JSONObject:
@@ -389,23 +389,21 @@ class RecordTools(ToolBase):
                 "ok": True,
                 "status": "success",
                 "request_route": self._request_route_payload(context),
-                "data": {
-                    "app_key": app_key,
-                    "schema_scope": "applicant_node",
-                    "workflow_node": {
-                        "workflow_node_id": applicant_node.workflow_node_id,
-                        "name": applicant_node.name,
-                        "type": applicant_node.type,
-                    },
-                    "view_resolution": _view_selection_payload(view_selection),
-                    "fields": fields,
-                    "suggested_dimensions": suggested_dimensions,
-                    "suggested_metrics": suggested_metrics,
-                    "suggested_time_fields": suggested_time_fields,
+                "app_key": app_key,
+                "schema_scope": "applicant_node",
+                "workflow_node": {
+                    "workflow_node_id": applicant_node.workflow_node_id,
+                    "name": applicant_node.name,
+                    "type": applicant_node.type,
                 },
+                "view_resolution": _view_selection_payload(view_selection),
+                "fields": fields,
+                "suggested_dimensions": suggested_dimensions,
+                "suggested_metrics": suggested_metrics,
+                "suggested_time_fields": suggested_time_fields,
             }
             if output_profile == "verbose":
-                response["data"]["field_count"] = len(fields)
+                response["field_count"] = len(fields)
             return response
 
         return self._run_record_tool(profile, runner)
@@ -605,7 +603,7 @@ class RecordTools(ToolBase):
         *,
         profile: str,
         app_key: str,
-        columns: list[int],
+        columns: list[JSONObject | int],
         where: list[JSONObject],
         order_by: list[JSONObject],
         limit: int,
@@ -617,10 +615,9 @@ class RecordTools(ToolBase):
         normalized_output_profile = self._normalize_public_output_profile(output_profile)
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
-        if not columns:
+        normalized_columns = _normalize_public_column_selectors(columns)
+        if not normalized_columns:
             raise_tool_error(QingflowApiError.config_error("columns is required"))
-        if any(not isinstance(item, int) or item < 0 for item in columns):
-            raise_tool_error(QingflowApiError.config_error("columns must be a list of field_id integers"))
         if limit <= 0:
             raise_tool_error(QingflowApiError.config_error("limit must be positive"))
         if page <= 0:
@@ -640,8 +637,8 @@ class RecordTools(ToolBase):
             filters=self._normalize_record_list_where(where),
             sorts=self._normalize_record_list_order_by(order_by),
             max_rows=limit,
-            max_columns=len(columns),
-            select_columns=columns,
+            max_columns=len(normalized_columns),
+            select_columns=normalized_columns,
             amount_column=None,
             time_range={},
             stat_policy={},
@@ -674,7 +671,7 @@ class RecordTools(ToolBase):
                     "result_amount": pagination.get("result_amount"),
                 },
                 "selection": {
-                    "columns": columns,
+                    "columns": [_column_selector_payload(field_id) for field_id in normalized_columns],
                     "view": cast(JSONObject, raw["data"]).get("view"),
                 },
             },
@@ -695,17 +692,16 @@ class RecordTools(ToolBase):
         profile: str,
         app_key: str,
         record_id: int,
-        columns: list[int],
+        columns: list[JSONObject | int],
         workflow_node_id: int | None,
         output_profile: str,
     ) -> JSONObject:
         normalized_output_profile = self._normalize_public_output_profile(output_profile)
         if record_id <= 0:
             raise_tool_error(QingflowApiError.config_error("record_id must be positive"))
-        if columns and any(not isinstance(item, int) or item < 0 for item in columns):
-            raise_tool_error(QingflowApiError.config_error("columns must be a list of field_id integers"))
+        normalized_columns = _normalize_public_column_selectors(columns)
 
-        if columns:
+        if normalized_columns:
             raw = self.record_query(
                 profile=profile,
                 query_mode="record",
@@ -720,8 +716,8 @@ class RecordTools(ToolBase):
                 filters=[],
                 sorts=[],
                 max_rows=1,
-                max_columns=len(columns),
-                select_columns=columns,
+                max_columns=len(normalized_columns),
+                select_columns=normalized_columns,
                 amount_column=None,
                 time_range={},
                 stat_policy={},
@@ -742,7 +738,7 @@ class RecordTools(ToolBase):
                     "record_id": record_id,
                     "record": record_data.get("row"),
                     "selection": {
-                        "columns": columns,
+                        "columns": [_column_selector_payload(field_id) for field_id in normalized_columns],
                         "workflow_node_id": workflow_node_id,
                     },
                 },
@@ -1095,9 +1091,9 @@ class RecordTools(ToolBase):
         if _scope_is_default_all(scope_type, scope, keys=("member", "depart", "role")):
             candidates = [
                 _normalize_candidate_member(item, source_kind="workspace")
-                for item in self._fetch_internal_members(context, department_id=None, role_id=None)
+                for item in self._search_workspace_members(context, keyword=keyword)
             ]
-            filtered = _filter_member_candidates([item for item in candidates if item is not None], keyword)
+            filtered = [item for item in candidates if item is not None]
             filtered.sort(key=lambda item: (_normalize_optional_text(item.get("value")) or "", _coerce_count(item.get("id")) or 0))
             return filtered
         if scope_type != 1:
@@ -1191,7 +1187,7 @@ class RecordTools(ToolBase):
         merged: dict[str, JSONObject] = {}
         include_sub = _normalize_bool(scope.get("includeSubDeparts"))
         if _scope_is_default_all(scope_type, scope, keys=("depart",)):
-            for item in self._list_all_departments(context):
+            for item in self._search_workspace_departments(context, keyword=keyword):
                 normalized = _normalize_candidate_department(item, source_kind="workspace")
                 if normalized is not None:
                     self._merge_department_candidate(merged, normalized)
@@ -1408,6 +1404,56 @@ class RecordTools(ToolBase):
             current_page += 1
         return list(seen.values())
 
+    def _search_workspace_members(self, context, *, keyword: str) -> list[dict[str, Any]]:  # type: ignore[no-untyped-def]
+        return self._search_workspace_directory_dimension(context, dimension="MEMBER", bucket_key="member", keyword=keyword)
+
+    def _search_workspace_departments(self, context, *, keyword: str) -> list[dict[str, Any]]:  # type: ignore[no-untyped-def]
+        return self._search_workspace_directory_dimension(context, dimension="DEPT", bucket_key="dept", keyword=keyword)
+
+    def _search_workspace_directory_dimension(
+        self,
+        context,  # type: ignore[no-untyped-def]
+        *,
+        dimension: str,
+        bucket_key: str,
+        keyword: str,
+    ) -> list[dict[str, Any]]:
+        current_page = 1
+        fetched_pages = 0
+        seen: dict[str, dict[str, Any]] = {}
+        while fetched_pages < MAX_MEMBER_SCOPE_FETCH_PAGES:
+            result = self.backend.request(
+                "POST",
+                context,
+                "/member/search",
+                json_body={
+                    "dimensions": [dimension],
+                    "searchKey": keyword,
+                    "pageNum": current_page,
+                    "pageSize": DEFAULT_MEMBER_SCOPE_FETCH_PAGE_SIZE,
+                },
+            )
+            bucket_payload = _member_search_bucket_payload(result, bucket_key=bucket_key)
+            page_items = _directory_items(bucket_payload)
+            for item in page_items:
+                if not isinstance(item, dict):
+                    continue
+                normalized = dict(item)
+                item_key = _member_candidate_key(normalized) if bucket_key == "member" else _department_candidate_key(normalized)
+                if not item_key or item_key in seen:
+                    continue
+                seen[item_key] = normalized
+            fetched_pages += 1
+            if not _directory_has_more(
+                bucket_payload,
+                current_page=current_page,
+                page_size=DEFAULT_MEMBER_SCOPE_FETCH_PAGE_SIZE,
+                returned_items=len(page_items),
+            ):
+                break
+            current_page += 1
+        return list(seen.values())
+
     def _schema_field_family(self, field: FormField) -> str:
         if self._schema_is_identifier_like(field):
             return "text"
@@ -3360,6 +3406,8 @@ class RecordTools(ToolBase):
         self._raise_if_verify_unsupported_write_field(field, item, location=field.que_title)
         if "values" in item and isinstance(item["values"], list):
             values = item["values"]
+        elif field.que_type in RELATION_QUE_TYPES and isinstance(item.get("referValues"), list):
+            values = item["referValues"]
         elif "value" in item:
             values = [item["value"]]
         else:
@@ -3369,6 +3417,8 @@ class RecordTools(ToolBase):
                 fix_hint="Pass value for scalar fields, or values for multi-value fields.",
                 details={"location": field.que_title, "field": _field_ref_payload(field), "expected_format": _write_format_for_field(field)},
             )
+        if field.que_type in RELATION_QUE_TYPES:
+            return self._build_relation_answer(field, values)
         return {
             "queId": field.que_id,
             "queType": field.que_type or 2,
@@ -3387,6 +3437,8 @@ class RecordTools(ToolBase):
             }
         self._raise_if_verify_unsupported_write_field(field, raw_value, location=str(field_selector))
         values = raw_value if isinstance(raw_value, list) and field.que_type in MULTI_SELECT_QUE_TYPES else [raw_value]
+        if field.que_type in RELATION_QUE_TYPES:
+            return self._build_relation_answer(field, values)
         return {
             "queId": field.que_id,
             "queType": field.que_type or 2,
@@ -3394,6 +3446,21 @@ class RecordTools(ToolBase):
             "tableValues": [],
         }
 
+    def _build_relation_answer(self, field: FormField, raw_values: list[JSONValue]) -> JSONObject:
+        values: list[JSONObject] = []
+        refer_values: list[JSONObject] = []
+        for raw_value in _expand_values(raw_values):
+            value_payload, refer_payload = _relation_value_payload(field, raw_value)
+            values.append(value_payload)
+            refer_values.append(refer_payload)
+        return {
+            "queId": field.que_id,
+            "queType": field.que_type or 25,
+            "values": values,
+            "referValues": refer_values,
+            "tableValues": [],
+        }
+
     def _raise_if_verify_unsupported_write_field(self, field: FormField, raw_value: JSONValue, *, location: str) -> None:
         if field.que_type not in VERIFY_UNSUPPORTED_WRITE_QUE_TYPES:
             return
@@ -4435,6 +4502,25 @@ class RecordTools(ToolBase):
                     count_mismatches=count_mismatches,
                 )
                 continue
+            if field is not None and field.que_type in RELATION_QUE_TYPES:
+                expected_relation_ids = _relation_ids_from_answer(answer)
+                actual_relation_ids = _relation_ids_from_answer(actual)
+                if expected_relation_ids and not actual_relation_ids:
+                    empty_fields.append(field_payload)
+                    continue
+                if expected_relation_ids:
+                    actual_id_set = set(actual_relation_ids)
+                    missing_ids = [value for value in expected_relation_ids if value not in actual_id_set]
+                    if missing_ids:
+                        count_mismatches.append(
+                            {
+                                **field_payload,
+                                "expected_ids": expected_relation_ids,
+                                "actual_ids": actual_relation_ids,
+                                "missing_ids": missing_ids,
+                            }
+                        )
+                continue
             actual_values = actual.get("values") if isinstance(actual.get("values"), list) else []
             if not actual_values:
                 empty_fields.append(field_payload)
@@ -5262,6 +5348,28 @@ def _extract_sort_selector(item: JSONObject) -> JSONValue:
     return None
 
 
+def _normalize_public_column_selectors(columns: list[JSONObject | int]) -> list[int]:
+    normalized: list[int] = []
+    for item in columns:
+        field_id: int | None = None
+        if isinstance(item, int):
+            field_id = item
+        elif isinstance(item, dict):
+            field_id = _coerce_count(item.get("field_id", item.get("fieldId")))
+        if field_id is None or field_id < 0:
+            raise_tool_error(
+                QingflowApiError.config_error(
+                    "columns must be a list of field_id integers or {field_id} objects"
+                )
+            )
+        normalized.append(field_id)
+    return normalized
+
+
+def _column_selector_payload(field_id: int) -> JSONObject:
+    return {"field_id": field_id}
+
+
 def _resolve_sort_ascend(item: JSONObject) -> bool:
     if "isAscend" in item:
         return bool(item["isAscend"])
@@ -5896,7 +6004,24 @@ def _attachment_value(value: JSONValue) -> JSONObject:
 
 
 def _relation_value(value: JSONValue) -> JSONObject:
+    return _relation_value_payload(None, value)[0]
+
+
+def _relation_value_payload(field: FormField | None, value: JSONValue) -> tuple[JSONObject, JSONObject]:
     if isinstance(value, dict):
+        target_app_key = _normalize_optional_text(value.get("target_app_key", value.get("targetAppKey", value.get("app_key", value.get("appKey")))))
+        if field is not None and field.target_app_key and target_app_key and target_app_key != field.target_app_key:
+            raise RecordInputError(
+                message=f"relation field '{field.que_title}' points to a different target app",
+                error_code="RELATION_TARGET_APP_MISMATCH",
+                fix_hint=f"Use a record from target app '{field.target_app_key}'.",
+                details={
+                    "field": _field_ref_payload(field),
+                    "expected_target_app_key": field.target_app_key,
+                    "received_target_app_key": target_app_key,
+                    "received_value": value,
+                },
+            )
         apply_id = value.get("apply_id", value.get("applyId", value.get("value", value.get("id"))))
         if apply_id is None:
             raise RecordInputError(
@@ -5905,8 +6030,37 @@ def _relation_value(value: JSONValue) -> JSONObject:
                 fix_hint="Pass relation values like {'apply_id': 5001} or numeric apply ids.",
                 details={"received_value": value},
             )
-        return {"value": _stringify_json(apply_id)}
-    return {"value": _stringify_json(value)}
+        normalized_apply_id = _stringify_json(apply_id)
+        return ({"value": normalized_apply_id}, {"applyId": normalized_apply_id})
+    normalized_apply_id = _stringify_json(value)
+    return ({"value": normalized_apply_id}, {"applyId": normalized_apply_id})
+
+
+def _relation_ids_from_answer(answer: JSONObject) -> list[str]:
+    ids: list[str] = []
+    seen: set[str] = set()
+    for key in ("referValues", "values"):
+        values = answer.get(key)
+        if not isinstance(values, list):
+            continue
+        for item in values:
+            if not isinstance(item, dict):
+                continue
+            relation_id = item.get("applyId", item.get("apply_id", item.get("value", item.get("id"))))
+            normalized = _normalize_optional_text(relation_id) or (_stringify_json(relation_id) if relation_id is not None else None)
+            if not normalized or normalized in seen:
+                continue
+            ids.append(normalized)
+            seen.add(normalized)
+    return ids
+
+
+def _member_search_bucket_payload(payload: JSONValue, *, bucket_key: str) -> JSONValue:
+    if isinstance(payload, dict):
+        bucket = payload.get(bucket_key)
+        if isinstance(bucket, (dict, list)):
+            return bucket
+    return payload
 
 
 def _normalize_candidate_member(
@@ -6247,8 +6401,8 @@ def _write_format_for_field(field: FormField) -> JSONObject:
         return _write_support_payload(
             support_level="restricted",
             kind="relation_record",
-            examples=[{"value": "5001"}],
-            required_presteps=["Query the target app first and use the referenced apply_id."],
+            examples=[{"apply_id": 5001}],
+            required_presteps=["Query the target app first and use the referenced apply_id from the target app."],
         )
     if field.que_type in SINGLE_SELECT_QUE_TYPES:
         return _write_support_payload(support_level="full", kind="single_select", options=field.options)