@josephyan/qingflow-app-user-mcp 0.2.0-beta.22 → 0.2.0-beta.23

package/README.md

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

package/package.json

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

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

@@ -24,6 +24,12 @@ Use these tools as the core analysis surface:
 
 Use `record_list` or `record_get` only when you need sample rows or a specific supporting example after the main analysis path.
 
+`record_schema_get` now returns the **current user's applicant-node visible schema only**:
+
+- hidden fields are omitted entirely
+- absent fields should be interpreted as `当前用户在申请人节点下不可见/不可用`
+- do not treat the schema as a builder/full-field metadata dump
+
 ## Hard Rules
 
 - Analysis tasks must start with `record_schema_get`
@@ -71,6 +77,7 @@ For analysis:
   - whether each side needs its own DSL
 - If you cannot name the denominator from real schema fields and filters, do not use words like `渗透率`, `转化率`, `占比`, `比例`, or `%`
 - If a field is still ambiguous after `record_schema_get`, do not guess; either select one unique `field_id` from the schema or ask the user to confirm from a short candidate list
+- If a business field is absent from `record_schema_get`, do not infer or guess a hidden `field_id`; explain that the field is not visible in the current applicant-node permission scope
 - If a statement depends on `count`, query `count`
 - If a statement depends on total amount, query `sum`
 - If a statement depends on average level, query `avg` or derive it from trusted `sum + count`

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

@@ -11,6 +11,8 @@ Correct recovery:
 3. build one or more small DSLs
 4. run `record_analyze`
 
+The schema here is applicant-node visible-only. If a field is absent, treat it as not available to the current user rather than switching to guessed ids or builder-side memory.
+
 ## Normalize relative time phrases before building the DSL.
 
 Examples:
@@ -77,6 +79,8 @@ Correct recovery:
 2. if several plausible candidates remain, ask the user to confirm from a short list
 3. build the DSL only after the field is clear
 
+If the intended field is absent from the schema altogether, stop and explain that it is not visible in the current applicant-node permission scope.
+
 Examples of the right recovery question:
 
 - “我找到两个可能的字段：`线索来源`、`来源渠道`。你要按哪个字段统计？”

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

@@ -30,6 +30,8 @@ Result reading order:
 5. `completeness`
 6. `presentation`
 
+Treat `record_schema_get` as applicant-node visible-only schema. Missing fields are permission boundaries, not invitations to guess hidden ids.
+
 ## Distribution / ratio pattern
 
 1. Run `record_schema_get`

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

@@ -55,6 +55,12 @@ Use exactly one of these default paths:
 - `record_get`
 - `record_write`
 
+`record_schema_get` now returns the **current user's applicant-node schema only**:
+
+- only fields visible to the current user at the applicant node are returned
+- hidden fields are omitted entirely
+- missing fields should be treated as `当前用户在申请人节点下不可见/不可用`, not as a reason to guess a different field
+
 ## Supporting Tools
 
 - `directory_search`
@@ -80,12 +86,14 @@ Use exactly one of these default paths:
 
 - Use `record_list` for browse/export/sample inspection only
 - 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` accepts:
   - `columns`
   - `where`
   - `order_by`
   - `limit`
   - `page`
+- `record_list` and `record_get` may reject hidden-field `field_id`s because record tools now validate against the applicant-node visible schema only
 - `record_list` is **not** an analysis tool
 - If a request turns into grouped distributions, ratios, rankings, trends, or final statistical conclusions, switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
 
@@ -153,6 +161,7 @@ The DSL is clause-shaped like SQL, but it is **not raw SQL text**.
 - Do not use free-form `WHERE` updates or deletes
 - Do not auto-fill missing fields
 - Do not auto-resolve relation targets without first querying them
+- Do not assume `record_schema_get` is a builder/full-field schema. It is the current user's applicant-node visible schema only.
 
 ## Response Interpretation
 
@@ -170,4 +179,3 @@ The DSL is clause-shaped like SQL, but it is **not raw SQL text**.
 - Environment switching: [references/environments.md](references/environments.md)
 - Record operation patterns: [references/record-patterns.md](references/record-patterns.md)
 - Data gotchas: [references/data-gotchas.md](references/data-gotchas.md)
-

package/skills/qingflow-record-crud/references/data-gotchas.md

@@ -6,6 +6,8 @@ For final statistics, grouped distributions, rankings, trends, or insight-style
 
 - `record_list` is for browsing, export, and sample inspection only
 - `record_get` is for one exact record
+- `record_schema_get` is applicant-node visible-only schema, not a builder/full-field schema
+- if a field is absent from `record_schema_get`, treat it as not visible or not usable for the current user at the applicant node
 - Do not present paged browse output as if it were a grouped or full-population conclusion
 - If the browser and MCP disagree, compare `request_route.base_url` and `request_route.qf_version` first
 
@@ -40,4 +42,3 @@ For final statistics, grouped distributions, rankings, trends, or insight-style
 - Use the current form schema's subfield titles; do not guess nested ids
 - When updating existing subtable rows, preserve row ids if the source record returns them
 - Nested subtable writes are still unsupported
-

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

@@ -11,6 +11,8 @@ Use `record_schema_get -> record_list` when:
 - a delete or update target still needs confirmation
 - the user needs sample rows or a small export
 
+Remember that `record_schema_get` only exposes the current user's applicant-node visible fields. If a field is missing from that schema, treat it as unavailable in the current permission scope instead of trying to guess another `field_id`.
+
 Keep the browse DSL simple:
 
 - `columns`: field ids only
@@ -29,6 +31,7 @@ Use `record_schema_get -> record_get` when:
 - a write target needs verification before action
 
 Prefer passing explicit `columns` when the user only needs a subset of fields.
+Without `columns`, `record_get` still returns only applicant-node visible fields, not the full builder-side record payload.
 
 ## Write Pattern
 
@@ -88,6 +91,7 @@ Do not do this:
 - do not invent formulas or expressions
 - do not auto-fill missing required fields
 - do not guess relation targets without first resolving them
+- do not guess hidden or missing fields from prior builder knowledge; if the field is absent from applicant-node schema, stop and explain the permission boundary
 - do not claim a blocked `record_write` was executed
 
 ## Unsupported Direct Writes
@@ -106,4 +110,3 @@ 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.
-

package/src/qingflow_mcp/__init__.py

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

package/src/qingflow_mcp/server.py

@@ -30,8 +30,9 @@ def build_server() -> FastMCP:
             "All resource tools operate with the logged-in user's Qingflow permissions.\n\n"
             "For analytics, use record_schema_get first, let the model build field_id-based DSL, "
             "then call record_analyze. record_analyze returns compact business-first output as query/result/ranking/ratios/completeness/presentation; use verbose only for route/debug details. "
+            "record_schema_get returns the current user's applicant-node visible schema only; hidden fields are omitted and missing fields should be treated as not visible in the current permission scope. "
             "For operational record reads, use record_schema_get first, then record_list or record_get. "
-            "For writes, use record_schema_get and then call record_write once; it performs internal preflight before any apply.\n\n"
+            "For writes, use record_schema_get and then call record_write once; it performs internal preflight before any apply and refuses fields outside the applicant-node writable schema.\n\n"
             "Task Center (待办/已办) handling:\n"
             "- Use task_summary to get headline counts.\n"
             "- Use task_list for flat task browsing with task_box and flow_status.\n"

package/src/qingflow_mcp/server_app_user.py

@@ -20,6 +20,7 @@ def build_user_server() -> FastMCP:
         instructions=(
             "Use this server for Qingflow operational workflows with a schema-first path. "
             "For records, start with record_schema_get, then choose record_list, record_get, or record_write. "
+            "record_schema_get returns the current user's applicant-node visible schema only; hidden fields are omitted and missing fields should be treated as not visible in the current permission scope. "
             "For analytics, switch to record_schema_get and record_analyze; its default output is compact query/result/ranking/ratios/completeness/presentation, with route/debug only in verbose mode. "
             "For task center, use task_summary, task_list, and task_facets before any explicit task action. "
             "Avoid builder-side app or schema changes here."

package/src/qingflow_mcp/tools/record_tools.py

@@ -90,6 +90,14 @@ class ViewSelection:
     conditions: list[list[ViewFilterCondition]]
 
 
+@dataclass(slots=True)
+class WorkflowNodeRef:
+    workflow_node_id: int
+    name: str
+    type: str
+    raw: JSONObject
+
+
 @dataclass(slots=True)
 class RecordInputError(Exception):
     message: str
@@ -134,7 +142,8 @@ FIELD_LOOKUP_STRIP_RE = re.compile(r"[\s_()（）\[\]【】{}<>·/\\:：-]+")
 class RecordTools(ToolBase):
     def __init__(self, sessions, backend) -> None:  # type: ignore[no-untyped-def]
         super().__init__(sessions, backend)
-        self._form_cache: dict[tuple[str, str], JSONObject] = {}
+        self._form_cache: dict[tuple[str, str, str, int], JSONObject] = {}
+        self._applicant_node_cache: dict[tuple[str, str], WorkflowNodeRef] = {}
         self._view_list_cache: dict[tuple[str, str], list[JSONObject]] = {}
         self._view_config_cache: dict[tuple[str, str], JSONObject] = {}
 
@@ -286,9 +295,10 @@ class RecordTools(ToolBase):
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
 
         def runner(session_profile, context):
+            applicant_node = self._resolve_applicant_node(profile, context, app_key, force_refresh=False)
             index = self._get_field_index(profile, context, app_key, force_refresh=False)
             view_selection = self._resolve_view_selection(profile, context, app_key, view_key=view_key, view_name=view_name)
-            fields = [self._schema_field_payload(field) for field in index.by_id.values()]
+            fields = [self._schema_field_payload(field, workflow_node_id=applicant_node.workflow_node_id) for field in index.by_id.values()]
             suggested_dimensions = [
                 {"field_id": item["field_id"], "title": item["title"]}
                 for item in fields
@@ -312,6 +322,12 @@ class RecordTools(ToolBase):
                 "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,
@@ -531,31 +547,39 @@ class RecordTools(ToolBase):
                 }
             return response
 
-        raw = self.record_get(
-            profile=profile,
-            app_key=app_key,
-            apply_id=record_id,
-            role=1,
-            list_type=None,
-            audit_node_id=workflow_node_id,
-        )
-        return {
-            "profile": profile,
-            "ws_id": raw.get("ws_id"),
-            "ok": bool(raw.get("ok", True)),
-            "request_route": raw.get("request_route"),
-            "warnings": [],
-            "output_profile": normalized_output_profile,
-            "data": {
-                "app_key": app_key,
-                "record_id": record_id,
-                "record": raw.get("result"),
-                "selection": {
-                    "columns": columns,
-                    "workflow_node_id": workflow_node_id,
+        def runner(session_profile, context):
+            index = self._get_field_index(profile, context, app_key, force_refresh=False)
+            selected_fields = list(index.by_id.values())
+            result = self.backend.request(
+                "GET",
+                context,
+                f"/app/{app_key}/apply/{record_id}",
+                params={"role": 1},
+            )
+            answer_list = result.get("answers") if isinstance(result, dict) and isinstance(result.get("answers"), list) else []
+            row = _build_flat_row(cast(list[JSONValue], answer_list), selected_fields, apply_id=record_id)
+            response: JSONObject = {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "ok": True,
+                "request_route": self._request_route_payload(context),
+                "warnings": [],
+                "output_profile": normalized_output_profile,
+                "data": {
+                    "app_key": app_key,
+                    "record_id": record_id,
+                    "record": row,
+                    "selection": {
+                        "columns": columns,
+                        "workflow_node_id": workflow_node_id,
+                    },
                 },
-            },
-        }
+            }
+            if normalized_output_profile == "verbose":
+                response["data"]["debug"] = {"raw_record": result}
+            return response
+
+        return self._run_record_tool(profile, runner)
 
     def record_write(
         self,
@@ -712,7 +736,7 @@ class RecordTools(ToolBase):
             preflight=None,
         )
 
-    def _schema_field_payload(self, field: FormField) -> JSONObject:
+    def _schema_field_payload(self, field: FormField, *, workflow_node_id: int) -> JSONObject:
         write_hints = self._schema_write_hints(field)
         return {
             "field_id": field.que_id,
@@ -725,6 +749,8 @@ class RecordTools(ToolBase):
             "role_hints": self._schema_role_hints(field),
             "readable": True,
             "writable": write_hints["writable"],
+            "permission_scope": "applicant_node",
+            "workflow_node_id": workflow_node_id,
             "write_kind": write_hints["write_kind"],
             "supported_read_ops": write_hints["supported_read_ops"],
             "supported_write_ops": write_hints["supported_write_ops"],
@@ -2390,10 +2416,16 @@ class RecordTools(ToolBase):
         return self._run_record_tool(profile, runner)
 
     def _get_form_schema(self, profile: str, context, app_key: str, *, force_refresh: bool) -> JSONObject:  # type: ignore[no-untyped-def]
-        cache_key = (profile, app_key)
+        applicant_node = self._resolve_applicant_node(profile, context, app_key, force_refresh=force_refresh)
+        cache_key = (profile, app_key, "applicant_node", applicant_node.workflow_node_id)
         if not force_refresh and cache_key in self._form_cache:
             return self._form_cache[cache_key]
-        schema = self.backend.request("GET", context, f"/app/{app_key}/form", params={"type": 1})
+        schema = self.backend.request(
+            "GET",
+            context,
+            f"/app/{app_key}/form",
+            params={"type": 1, "beingApply": True, "auditNodeId": applicant_node.workflow_node_id},
+        )
         normalized = _normalize_form_schema(schema)
         self._form_cache[cache_key] = normalized
         return normalized
@@ -2401,6 +2433,26 @@ class RecordTools(ToolBase):
     def _get_field_index(self, profile: str, context, app_key: str, *, force_refresh: bool) -> FieldIndex:  # type: ignore[no-untyped-def]
         return _build_field_index(self._get_form_schema(profile, context, app_key, force_refresh=force_refresh))
 
+    def _resolve_applicant_node(self, profile: str, context, app_key: str, *, force_refresh: bool) -> WorkflowNodeRef:  # type: ignore[no-untyped-def]
+        cache_key = (profile, app_key)
+        if not force_refresh and cache_key in self._applicant_node_cache:
+            return self._applicant_node_cache[cache_key]
+        payload = self.backend.request("GET", context, f"/app/{app_key}/auditNodes")
+        applicant_node = _extract_applicant_node(payload)
+        if applicant_node is None:
+            raise_tool_error(
+                QingflowApiError(
+                    category="config",
+                    message=f"cannot resolve applicant node for app {app_key}",
+                    details={
+                        "error_code": "APPLICANT_NODE_NOT_FOUND",
+                        "fix_hint": "Ensure the app has a workflow applicant node before using user-side record tools.",
+                    },
+                )
+            )
+        self._applicant_node_cache[cache_key] = applicant_node
+        return applicant_node
+
     def _get_view_list(self, profile: str, context, app_key: str) -> list[JSONObject]:  # type: ignore[no-untyped-def]
         cache_key = (profile, app_key)
         if cache_key in self._view_list_cache:
@@ -3883,6 +3935,30 @@ def _normalize_view_list(payload: JSONValue) -> list[JSONObject]:
     return flattened
 
 
+def _normalize_audit_nodes(payload: JSONValue) -> list[JSONObject]:
+    if isinstance(payload, list):
+        return [item for item in payload if isinstance(item, dict)]
+    if isinstance(payload, dict):
+        return [item for item in payload.values() if isinstance(item, dict)]
+    return []
+
+
+def _extract_applicant_node(payload: JSONValue) -> WorkflowNodeRef | None:
+    for item in _normalize_audit_nodes(payload):
+        node_type = _coerce_count(item.get("type"))
+        deal_type = _coerce_count(item.get("dealType"))
+        workflow_node_id = _coerce_count(item.get("auditNodeId"))
+        if workflow_node_id is None or node_type != 0 or deal_type != 3:
+            continue
+        return WorkflowNodeRef(
+            workflow_node_id=workflow_node_id,
+            name=_normalize_optional_text(item.get("auditNodeName")) or str(workflow_node_id),
+            type="applicant",
+            raw=item,
+        )
+    return None
+
+
 def _compile_view_conditions(config: JSONObject) -> list[list[ViewFilterCondition]]:
     raw_limit = config.get("viewgraphLimit")
     if not isinstance(raw_limit, list):