@josephyan/qingflow-app-user-mcp 0.2.0-beta.30 → 0.2.0-beta.31

package/README.md

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

package/package.json

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

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

@@ -60,7 +60,9 @@ Use `record_member_candidates` / `record_department_candidates` as the default l
 ## 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
+- For `columns`, use `[{ "field_id": 12 }]`
+- For `where`, use `{ "field_id": 12, "op": "eq", "value": "进行中" }`
+- For `order_by`, use `{ "field_id": 18, "direction": "desc" }`
 - 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

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

@@ -15,9 +15,9 @@ Remember that `record_schema_get` only exposes the current user's applicant-node
 
 Keep the browse DSL simple:
 
-- `columns`: prefer `[{ "field_id": 12 }]`; bare integers are accepted for compatibility
-- `where`: flat AND filters only
-- `order_by`: field sorting only
+- `columns`: use `[{ "field_id": 12 }]`
+- `where`: flat AND filters only, using `{ "field_id": 12, "op": "eq", "value": "进行中" }`
+- `order_by`: field sorting only, using `{ "field_id": 18, "direction": "desc" }`
 - `limit` and `page`: browsing intent only
 
 Do not use `record_list` for grouped conclusions, ratios, rankings, trends, or any final statistical claim.

package/src/qingflow_mcp/__init__.py

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

package/src/qingflow_mcp/server.py

@@ -78,7 +78,10 @@ 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.
+- Use `columns` as `[{{field_id}}]`
+- 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
 
 `record_write` uses SQL-like JSON clauses:
 

package/src/qingflow_mcp/server_app_user.py

@@ -66,7 +66,10 @@ 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.
+- Use `columns` as `[{{field_id}}]`
+- 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
 
 `record_write` uses SQL-like JSON clauses:
 

package/src/qingflow_mcp/tools/record_tools.py

@@ -565,6 +565,12 @@ class RecordTools(ToolBase):
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
         if limit <= 0:
             raise_tool_error(QingflowApiError.config_error("limit must be positive"))
+        legacy_warnings = _detect_analyze_legacy_warnings(
+            dimensions=dimensions,
+            metrics=metrics,
+            filters=filters,
+            sort=sort,
+        )
 
         def runner(session_profile, context):
             index = self._get_field_index(profile, context, app_key, force_refresh=False)
@@ -594,6 +600,7 @@ class RecordTools(ToolBase):
                 limit=limit,
                 strict_full=strict_full,
                 output_profile=output_profile,
+                extra_warnings=legacy_warnings,
             )
 
         return self._run_record_tool(profile, runner)
@@ -615,6 +622,7 @@ 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"))
+        legacy_warnings = _detect_record_list_legacy_warnings(columns=columns, where=where, order_by=order_by)
         normalized_columns = _normalize_public_column_selectors(columns)
         if not normalized_columns:
             raise_tool_error(QingflowApiError.config_error("columns is required"))
@@ -651,6 +659,7 @@ class RecordTools(ToolBase):
         list_data = cast(JSONObject, cast(JSONObject, raw["data"])["list"])
         pagination = cast(JSONObject, list_data["pagination"])
         warnings: list[JSONObject] = []
+        warnings.extend(legacy_warnings)
         warning = _normalize_optional_text(list_data.get("analysis_warning"))
         if warning:
             warnings.append({"code": "BROWSE_ONLY", "message": warning})
@@ -1906,6 +1915,7 @@ class RecordTools(ToolBase):
         limit: int,
         strict_full: bool,
         output_profile: str,
+        extra_warnings: list[JSONObject] | None = None,
     ) -> JSONObject:
         started_at = time.perf_counter()
         analysis_paging = _fixed_analysis_scan_policy()
@@ -2068,7 +2078,11 @@ class RecordTools(ToolBase):
                 for idx, row in enumerate(rows, start=1)
             ]
 
-        warnings = self._build_analyze_warnings(local_filtering=local_filtering, rows_truncated=rows_truncated)
+        warnings = self._build_analyze_warnings(
+            local_filtering=local_filtering,
+            rows_truncated=rows_truncated,
+            extra_warnings=extra_warnings or [],
+        )
         completeness: JSONObject = {
             "status": completeness_status,
             "safe_for_final_conclusion": completeness_status == "complete",
@@ -2230,8 +2244,15 @@ class RecordTools(ToolBase):
             )
         return sorted_rows
 
-    def _build_analyze_warnings(self, *, local_filtering: bool, rows_truncated: bool) -> list[JSONObject]:
+    def _build_analyze_warnings(
+        self,
+        *,
+        local_filtering: bool,
+        rows_truncated: bool,
+        extra_warnings: list[JSONObject],
+    ) -> list[JSONObject]:
         warnings: list[JSONObject] = []
+        warnings.extend(extra_warnings)
         if local_filtering:
             warnings.append({"code": "LOCAL_VIEW_FILTERING"})
         if rows_truncated:
@@ -3734,18 +3755,23 @@ class RecordTools(ToolBase):
         for idx, item in enumerate(where):
             if not isinstance(item, dict):
                 raise_tool_error(QingflowApiError.config_error(f"where[{idx}] must be an object"))
+            _ensure_allowed_record_list_keys(
+                item,
+                location=f"where[{idx}]",
+                allowed_keys={"field_id", "fieldId", "op", "operator", "value", "values"},
+                example="{'field_id': 12, 'op': 'eq', 'value': '进行中'}",
+            )
             field_id = _coerce_count(item.get("field_id", item.get("fieldId")))
             if field_id is None:
                 raise_tool_error(QingflowApiError.config_error(f"where[{idx}] requires field_id"))
             payload: JSONObject = {"field_id": field_id}
-            if "op" in item:
-                payload["op"] = item["op"]
-            if "operator" in item:
-                payload["operator"] = item["operator"]
+            op = item.get("op", item.get("operator"))
+            if op is not None:
+                payload["op"] = op
             if "value" in item:
                 payload["value"] = item["value"]
             elif "values" in item:
-                payload["values"] = item["values"]
+                payload["value"] = item["values"]
             normalized.append(payload)
         return normalized
 
@@ -3754,6 +3780,12 @@ class RecordTools(ToolBase):
         for idx, item in enumerate(order_by):
             if not isinstance(item, dict):
                 raise_tool_error(QingflowApiError.config_error(f"order_by[{idx}] must be an object"))
+            _ensure_allowed_record_list_keys(
+                item,
+                location=f"order_by[{idx}]",
+                allowed_keys={"field_id", "fieldId", "direction", "order"},
+                example="{'field_id': 18, 'direction': 'desc'}",
+            )
             field_id = _coerce_count(item.get("field_id", item.get("fieldId")))
             if field_id is None:
                 raise_tool_error(QingflowApiError.config_error(f"order_by[{idx}] requires field_id"))
@@ -5361,6 +5393,12 @@ def _normalize_public_column_selectors(columns: list[JSONObject | int]) -> list[
         if isinstance(item, int):
             field_id = item
         elif isinstance(item, dict):
+            _ensure_allowed_record_list_keys(
+                item,
+                location="columns[]",
+                allowed_keys={"field_id", "fieldId"},
+                example="{'field_id': 12}",
+            )
             field_id = _coerce_count(item.get("field_id", item.get("fieldId")))
         if field_id is None or field_id < 0:
             raise_tool_error(
@@ -5376,6 +5414,92 @@ def _column_selector_payload(field_id: int) -> JSONObject:
     return {"field_id": field_id}
 
 
+def _ensure_allowed_record_list_keys(
+    item: JSONObject,
+    *,
+    location: str,
+    allowed_keys: set[str],
+    example: str,
+) -> None:
+    unexpected_keys = sorted(str(key) for key in item.keys() if str(key) not in allowed_keys)
+    if unexpected_keys:
+        raise_tool_error(
+            QingflowApiError.config_error(
+                f"{location} contains unsupported keys: {unexpected_keys}. Use {example}."
+            )
+        )
+
+
+def _detect_record_list_legacy_warnings(
+    *,
+    columns: list[JSONObject | int],
+    where: list[JSONObject],
+    order_by: list[JSONObject],
+) -> list[JSONObject]:
+    warnings: list[JSONObject] = []
+    if any(isinstance(item, int) or (isinstance(item, dict) and "fieldId" in item) for item in columns):
+        warnings.append(
+            {
+                "code": "LEGACY_LIST_COLUMNS_DSL",
+                "message": "Use columns as [{field_id}] objects. Bare integers and fieldId are compatibility-only.",
+            }
+        )
+    if any(isinstance(item, dict) and any(key in item for key in ("fieldId", "operator", "values")) for item in where):
+        warnings.append(
+            {
+                "code": "LEGACY_LIST_FILTER_DSL",
+                "message": "Use where items as {field_id, op, value}. fieldId/operator/values are compatibility-only.",
+            }
+        )
+    if any(isinstance(item, dict) and any(key in item for key in ("fieldId", "order")) for item in order_by):
+        warnings.append(
+            {
+                "code": "LEGACY_LIST_SORT_DSL",
+                "message": "Use order_by items as {field_id, direction}. fieldId/order are compatibility-only.",
+            }
+        )
+    return warnings
+
+
+def _detect_analyze_legacy_warnings(
+    *,
+    dimensions: list[JSONObject],
+    metrics: list[JSONObject],
+    filters: list[JSONObject],
+    sort: list[JSONObject],
+) -> list[JSONObject]:
+    warnings: list[JSONObject] = []
+    if any(isinstance(item, dict) and "fieldId" in item for item in dimensions):
+        warnings.append(
+            {
+                "code": "LEGACY_ANALYZE_DIMENSION_DSL",
+                "message": "Use dimensions as {field_id, alias, bucket}. fieldId is compatibility-only.",
+            }
+        )
+    if any(isinstance(item, dict) and any(key in item for key in ("fieldId", "type", "agg", "aggregation")) for item in metrics):
+        warnings.append(
+            {
+                "code": "LEGACY_ANALYZE_METRIC_DSL",
+                "message": "Use metrics as {op, field_id, alias}. fieldId/type/agg/aggregation are compatibility-only.",
+            }
+        )
+    if any(isinstance(item, dict) and any(key in item for key in ("fieldId", "operator", "values")) for item in filters):
+        warnings.append(
+            {
+                "code": "LEGACY_ANALYZE_FILTER_DSL",
+                "message": "Use filters as {field_id, op, value}. fieldId/operator/values are compatibility-only.",
+            }
+        )
+    if any(isinstance(item, dict) and "direction" in item for item in sort):
+        warnings.append(
+            {
+                "code": "LEGACY_ANALYZE_SORT_DSL",
+                "message": "Use sort items as {by, order}. direction is compatibility-only.",
+            }
+        )
+    return warnings
+
+
 def _resolve_sort_ascend(item: JSONObject) -> bool:
     if "isAscend" in item:
         return bool(item["isAscend"])