@josephyan/qingflow-app-builder-mcp 0.2.0-beta.22 → 0.2.0-beta.24

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-builder-mcp",
-  "version": "0.2.0-beta.22",
+  "version": "0.2.0-beta.24",
   "description": "Builder MCP for Qingflow app/package/system design and staged solution 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.0b24"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

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

@@ -38,6 +38,7 @@ ATTACHMENT_QUE_TYPES = {13}
 RELATION_QUE_TYPES = {25}
 SUBTABLE_QUE_TYPES = {18}
 VERIFY_UNSUPPORTED_WRITE_QUE_TYPES = {14, 34, 35, 36}
+LAYOUT_ONLY_QUE_TYPES = {24}
 DEPARTMENT_MEMBER_JUDGE_PREFIX = "deptId_"
 JUDGE_EQUAL = 0
 JUDGE_UNEQUAL = 1
@@ -90,6 +91,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 +143,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 +296,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 +323,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 +548,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 +737,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 +750,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"],
@@ -1105,10 +1132,12 @@ class RecordTools(ToolBase):
             self._ensure_allowed_analyze_keys(
                 item,
                 location=f"metrics[{idx}]",
-                allowed_keys={"op", "field_id", "fieldId", "alias"},
+                allowed_keys={"op", "type", "agg", "aggregation", "field_id", "fieldId", "alias"},
                 example="{'op': 'sum', 'field_id': 7, 'alias': '总金额'}",
             )
-            op = _normalize_optional_text(item.get("op"))
+            op = _normalize_optional_text(
+                item.get("op") or item.get("type") or item.get("agg") or item.get("aggregation")
+            )
             if op not in supported_ops:
                 raise RecordInputError(
                     message=f"metrics[{idx}] uses unsupported op '{op}'",
@@ -1127,12 +1156,8 @@ class RecordTools(ToolBase):
                         details={"location": f"metrics[{idx}]", "field": _field_ref_payload(field), "op": op},
                     )
             elif item.get("field_id", item.get("fieldId")) is not None:
-                raise RecordInputError(
-                    message=f"metrics[{idx}] with op 'count' must not include field_id",
-                    error_code="INVALID_ANALYZE_METRIC",
-                    fix_hint="Remove field_id from count metrics.",
-                    details={"location": f"metrics[{idx}]", "op": op},
-                )
+                # LLM 经常给 count 传 field_id，静默忽略而非报错
+                pass
             alias = _normalize_optional_text(item.get("alias"))
             if alias is None:
                 if op == "count":
@@ -2390,10 +2415,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 +2432,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 +3934,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):
@@ -3919,16 +3994,19 @@ def _build_field_index(schema: JSONObject) -> FieldIndex:
         *[(question, False) for question in _flatten_questions(schema.get("formQues"))],
     ]
     for question, is_base_question in all_questions:
+        if not _should_index_question(question):
+            continue
         que_id = _coerce_count(question.get("queId"))
         title = _stringify_json(question.get("queTitle")).strip()
         if que_id is None or que_id < 0 or not title:
             continue
+        can_edit = question.get("canEdit")
         field = FormField(
             que_id=que_id,
             que_title=title,
             que_type=_coerce_count(question.get("queType")),
             required=bool(question.get("required") or question.get("beingRequired")),
-            readonly=bool(question.get("readonly") or question.get("beingReadonly") or is_base_question),
+            readonly=bool(question.get("readonly") or question.get("beingReadonly") or is_base_question or can_edit is False),
             system=bool(question.get("system") or question.get("beingSystem") or is_base_question),
             options=_extract_question_options(question),
             aliases=[],
@@ -3947,16 +4025,35 @@ def _build_field_index(schema: JSONObject) -> FieldIndex:
 def _flatten_questions(payload: JSONValue) -> list[JSONObject]:
     flattened: list[JSONObject] = []
     if isinstance(payload, dict):
-        if "queId" in payload or "queTitle" in payload:
+        is_question = "queId" in payload or "queTitle" in payload
+        if is_question:
             flattened.append(payload)
-        for value in payload.values():
-            flattened.extend(_flatten_questions(value))
+        for key in ("subQuestions", "innerQuestions", "subQues"):
+            value = payload.get(key)
+            if isinstance(value, list):
+                flattened.extend(_flatten_questions(value))
+        if not is_question:
+            for key in ("baseQues", "formQues"):
+                value = payload.get(key)
+                if isinstance(value, list):
+                    flattened.extend(_flatten_questions(value))
     elif isinstance(payload, list):
         for item in payload:
             flattened.extend(_flatten_questions(item))
     return flattened
 
 
+def _should_index_question(question: JSONObject) -> bool:
+    if bool(question.get("beingHide") or question.get("hidden")):
+        return False
+    if _coerce_count(question.get("quoteId")) is not None:
+        return False
+    que_type = _coerce_count(question.get("queType"))
+    if que_type in LAYOUT_ONLY_QUE_TYPES:
+        return False
+    return True
+
+
 def _extract_question_options(question: JSONObject) -> list[str]:
     options = question.get("options")
     if not isinstance(options, list):