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

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.28
 ```
 
 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.28 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.28",
   "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.0b28"
 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
 
@@ -58,6 +58,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
@@ -103,6 +104,13 @@ The DSL is clause-shaped like SQL, but it is **not raw SQL text**.
 - Do not assume department names resolve automatically; `record_department_candidates` returns ids, but direct name-to-id write is not automatic
 - 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.0b28"

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`

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`

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,
                     },
                 },
@@ -5262,6 +5258,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"])