@josephyan/qingflow-app-user-mcp 0.2.0-beta.28 → 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.28
+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.28 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.28",
+  "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.0b28"
+version = "0.2.0b29"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

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

@@ -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
@@ -102,6 +104,7 @@ 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

package/src/qingflow_mcp/__init__.py

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

package/src/qingflow_mcp/server.py

@@ -90,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

@@ -78,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

@@ -1091,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:
@@ -1187,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)
@@ -1404,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"
@@ -3356,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:
@@ -3365,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,
@@ -3383,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,
@@ -3390,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
@@ -4431,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)
@@ -5914,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(
@@ -5923,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(
@@ -6265,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)