@josephyan/qingflow-app-builder-mcp 0.2.0-beta.52 → 0.2.0-beta.53

package/README.md

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

package/package.json

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

package/src/qingflow_mcp/server.py

@@ -53,7 +53,8 @@ If an accessible view has `analysis_supported=false`, do not use it for `record_
 
 ## Schema-First Rule
 
-Call `record_schema_get(schema_mode="applicant")` before `record_write`.
+Call `record_schema_get(schema_mode="applicant")` before `record_insert`.
+Call `record_schema_get(schema_mode="applicant")` before `record_code_block_run`.
 Call `app_get` first when the data range is unclear, then use `record_schema_get(schema_mode="browse", view_id=...)` before `record_list`, `record_get`, or `record_analyze`.
 
 - All `field_id` values must come from the schema response.
@@ -94,7 +95,9 @@ Analysis answers must include concrete numbers. When applicable, include percent
 ## Record CRUD Path
 
 `app_get -> record_schema_get(schema_mode="browse", view_id=...) -> record_list / record_get`
-`record_schema_get(schema_mode="applicant") -> record_write`
+`record_schema_get(schema_mode="applicant") -> record_insert`
+`app_get -> record_schema_get(schema_mode="browse", view_id=...) -> record_update`
+`record_list / record_get -> record_delete`
 `record_schema_get(schema_mode="applicant") -> record_code_block_run`
 
 - Use `columns` as `[{{field_id}}]`
@@ -102,14 +105,12 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - 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:
-
-- `insert` -> `values`
-- `update` -> `record_id + set`
-- `delete` -> `record_id` or `record_ids`
+- `record_insert` uses an applicant-node `fields` map keyed by field title.
+- `record_update` uses a view-scoped `fields` map keyed by field title.
+- `record_delete` deletes by `record_id` or `record_ids`.
 
 - 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`.
+- If a member or department field id is known but candidate ids are not, use `record_member_candidates` or `record_department_candidates` before `record_insert` or `record_update`.
 - For default-all member or department fields, prefer those field candidate tools instead of starting with `directory_*`.
 
 ## Code Block Path

package/src/qingflow_mcp/server_app_user.py

@@ -41,7 +41,8 @@ If an accessible view has `analysis_supported=false`, do not use it for `record_
 
 ## Schema-First Rule
 
-Call `record_schema_get(schema_mode="applicant")` before `record_write`.
+Call `record_schema_get(schema_mode="applicant")` before `record_insert`.
+Call `record_schema_get(schema_mode="applicant")` before `record_code_block_run`.
 Call `app_get` first when the data range is unclear, then use `record_schema_get(schema_mode="browse", view_id=...)` before `record_list`, `record_get`, or `record_analyze`.
 
 - All `field_id` values must come from the schema response.
@@ -82,7 +83,9 @@ Analysis answers must include concrete numbers. When applicable, include percent
 ## Record CRUD Path
 
 `app_get -> record_schema_get(schema_mode="browse", view_id=...) -> record_list / record_get`
-`record_schema_get(schema_mode="applicant") -> record_write`
+`record_schema_get(schema_mode="applicant") -> record_insert`
+`app_get -> record_schema_get(schema_mode="browse", view_id=...) -> record_update`
+`record_list / record_get -> record_delete`
 `record_schema_get(schema_mode="applicant") -> record_code_block_run`
 
 - Use `columns` as `[{{field_id}}]`
@@ -90,14 +93,12 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - 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:
-
-- `insert` -> `values`
-- `update` -> `record_id + set`
-- `delete` -> `record_id` or `record_ids`
+- `record_insert` uses an applicant-node `fields` map keyed by field title.
+- `record_update` uses a view-scoped `fields` map keyed by field title.
+- `record_delete` deletes by `record_id` or `record_ids`.
 
 - 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`.
+- If a member or department field id is known but candidate ids are not, use `record_member_candidates` or `record_department_candidates` before `record_insert` or `record_update`.
 - For default-all member or department fields, prefer those field candidate tools instead of starting with `directory_*`.
 
 ## Code Block Path

package/src/qingflow_mcp/tools/import_tools.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import hashlib
 import json
 import mimetypes
+import re
 import shutil
 import tempfile
 from io import BytesIO
@@ -35,6 +36,7 @@ SAFE_REPAIRS = {
     "normalize_number_formats",
     "normalize_url_cells",
 }
+EMAIL_PATTERN = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
 
 
 class ImportTools(ToolBase):
@@ -135,7 +137,7 @@ class ImportTools(ToolBase):
 
         def runner(session_profile, context):
             import_capability, import_warnings = self._fetch_import_capability(context, app_key)
-            expected_columns, schema_fingerprint = self._expected_import_columns(
+            field_index, expected_columns, schema_fingerprint = self._resolve_import_schema_bundle(
                 profile,
                 context,
                 app_key,
@@ -261,7 +263,7 @@ class ImportTools(ToolBase):
                         "message": "record_import_verify could not determine import permission from app metadata; continuing with file verification only.",
                     }
                 ]
-            expected_columns, schema_fingerprint = self._expected_import_columns(
+            field_index, expected_columns, schema_fingerprint = self._resolve_import_schema_bundle(
                 profile,
                 context,
                 app_key,
@@ -275,8 +277,11 @@ class ImportTools(ToolBase):
             )
             template_header_titles = template_header_profile.get("allowed_titles")
             local_check = self._local_verify(
+                profile=profile,
+                context=context,
                 path=path,
                 app_key=app_key,
+                field_index=field_index,
                 expected_columns=expected_columns,
                 allowed_header_titles=template_header_titles,
                 schema_fingerprint=schema_fingerprint,
@@ -292,8 +297,11 @@ class ImportTools(ToolBase):
             if auto_normalization is not None:
                 effective_path = Path(str(auto_normalization["verified_file_path"]))
                 effective_local_check = self._local_verify(
+                    profile=profile,
+                    context=context,
                     path=effective_path,
                     app_key=app_key,
+                    field_index=field_index,
                     expected_columns=expected_columns,
                     allowed_header_titles=list(auto_normalization["header_titles"]),
                     schema_fingerprint=schema_fingerprint,
@@ -550,7 +558,13 @@ class ImportTools(ToolBase):
                     message="the file changed after verification; run record_import_verify again",
                     extra={"accepted": False},
                 )
-            _, current_schema_fingerprint = self._expected_import_columns(profile, context, app_key)
+            stored_import_capability = stored.get("import_capability")
+            _, current_schema_fingerprint = self._expected_import_columns(
+                profile,
+                context,
+                app_key,
+                import_capability=stored_import_capability if isinstance(stored_import_capability, dict) else None,
+            )
             if current_schema_fingerprint != stored.get("schema_fingerprint"):
                 return self._failed_start_result(
                     error_code="IMPORT_SCHEMA_CHANGED_AFTER_VERIFY",
@@ -702,14 +716,14 @@ class ImportTools(ToolBase):
         except RuntimeError as exc:
             return self._runtime_error_as_result(exc, error_code="IMPORT_STATUS_AMBIGUOUS")
 
-    def _expected_import_columns(
+    def _resolve_import_schema_bundle(
         self,
         profile: str,
         context,
         app_key: str,
         *,
         import_capability: JSONObject | None = None,
-    ) -> tuple[list[JSONObject], str]:  # type: ignore[no-untyped-def]
+    ) -> tuple[Any, list[JSONObject], str]:  # type: ignore[no-untyped-def]
         auth_source = _normalize_optional_text((import_capability or {}).get("auth_source")) or "unknown"
         if auth_source == "data_manage_auth":
             schema = self.backend.request("GET", context, f"/app/{app_key}/form", params={"type": 1})
@@ -744,16 +758,33 @@ class ImportTools(ToolBase):
                 }
             )
         expected_columns.sort(key=lambda item: int(item["field_id"]))
-        schema_fingerprint = hashlib.sha256(
-            json.dumps(expected_columns, ensure_ascii=False, sort_keys=True).encode("utf-8")
-        ).hexdigest()
+        schema_fingerprint = _stable_import_schema_fingerprint(expected_columns)
+        return index, expected_columns, schema_fingerprint
+
+    def _expected_import_columns(
+        self,
+        profile: str,
+        context,
+        app_key: str,
+        *,
+        import_capability: JSONObject | None = None,
+    ) -> tuple[list[JSONObject], str]:  # type: ignore[no-untyped-def]
+        _, expected_columns, schema_fingerprint = self._resolve_import_schema_bundle(
+            profile,
+            context,
+            app_key,
+            import_capability=import_capability,
+        )
         return expected_columns, schema_fingerprint
 
     def _local_verify(
         self,
         *,
+        profile: str,
+        context,
         path: Path,
         app_key: str,
+        field_index: Any,
         expected_columns: list[JSONObject],
         allowed_header_titles: list[str] | None,
         schema_fingerprint: str,
@@ -815,6 +846,16 @@ class ImportTools(ToolBase):
         )
         base_result["issues"].extend(header_analysis["issues"])
         base_result["repair_suggestions"].extend(header_analysis["repair_suggestions"])
+        if not any(issue.get("severity") == "error" for issue in base_result["issues"]):
+            semantic_issues, semantic_warnings = self._inspect_semantic_cells(
+                profile=profile,
+                context=context,
+                sheet=sheet,
+                expected_columns=expected_columns,
+                field_index=field_index,
+            )
+            base_result["issues"].extend(semantic_issues)
+            base_result["warnings"].extend(semantic_warnings)
         trailing_blank_rows = _count_trailing_blank_rows(sheet)
         if trailing_blank_rows > 0:
             base_result["warnings"].append(
@@ -840,6 +881,190 @@ class ImportTools(ToolBase):
             base_result["error_code"] = "IMPORT_VERIFICATION_FAILED"
         return base_result
 
+    def _inspect_semantic_cells(
+        self,
+        *,
+        profile: str,
+        context,
+        sheet,
+        expected_columns: list[JSONObject],
+        field_index: Any,
+    ) -> tuple[list[JSONObject], list[JSONObject]]:  # type: ignore[no-untyped-def]
+        issues: list[JSONObject] = []
+        warnings: list[JSONObject] = []
+        header_positions = _sheet_header_positions(sheet)
+        expected_by_key: dict[str, list[JSONObject]] = {}
+        for column in expected_columns:
+            key = _normalize_header_key(column.get("title"))
+            if key:
+                expected_by_key.setdefault(key, []).append(column)
+        for key, columns in expected_by_key.items():
+            positions = header_positions.get(key, [])
+            if len(columns) != 1 or len(positions) != 1:
+                continue
+            column = columns[0]
+            column_index = positions[0]
+            write_kind = _normalize_optional_text(column.get("write_kind")) or "scalar"
+            if column.get("options"):
+                issue = _inspect_enum_column(sheet, column_index=column_index, column=column)
+                if issue is not None:
+                    issues.append(issue)
+                    continue
+            if write_kind == "relation":
+                issue = _inspect_relation_column(sheet, column_index=column_index, column=column)
+                if issue is not None:
+                    issues.append(issue)
+                    continue
+            field = field_index.by_id.get(str(column.get("field_id"))) if field_index is not None else None
+            if (
+                write_kind == "member"
+                and field is not None
+                and (
+                    field.member_select_scope_type is not None
+                    or field.member_select_scope is not None
+                )
+            ):
+                member_issue, member_warning = self._inspect_member_column(
+                    context=context,
+                    sheet=sheet,
+                    column_index=column_index,
+                    column=column,
+                    field=field,
+                )
+                if member_issue is not None:
+                    issues.append(member_issue)
+                    continue
+                if member_warning is not None:
+                    warnings.append(member_warning)
+                    continue
+            if (
+                write_kind == "department"
+                and field is not None
+                and (
+                    field.dept_select_scope_type is not None
+                    or field.dept_select_scope is not None
+                )
+            ):
+                department_issue, department_warning = self._inspect_department_column(
+                    context=context,
+                    sheet=sheet,
+                    column_index=column_index,
+                    column=column,
+                    field=field,
+                )
+                if department_issue is not None:
+                    issues.append(department_issue)
+                    continue
+                if department_warning is not None:
+                    warnings.append(department_warning)
+                    continue
+        return issues, warnings
+
+    def _inspect_member_column(
+        self,
+        *,
+        context,
+        sheet,
+        column_index: int,
+        column: JSONObject,
+        field,
+    ) -> tuple[JSONObject | None, JSONObject | None]:  # type: ignore[no-untyped-def]
+        invalid_email_samples: list[str] = []
+        scope_miss_samples: list[str] = []
+        checked_values: set[str] = set()
+        for row_index in range(2, sheet.max_row + 1):
+            text = _normalize_optional_text(sheet.cell(row=row_index, column=column_index).value)
+            if text is None:
+                continue
+            normalized = text.strip()
+            if normalized in checked_values:
+                continue
+            checked_values.add(normalized)
+            if not EMAIL_PATTERN.fullmatch(normalized):
+                invalid_email_samples.append(f"row {row_index}: {normalized}")
+                if len(invalid_email_samples) >= 3:
+                    break
+                continue
+            try:
+                candidates = self._record_tools._resolve_member_candidates(context, field, keyword=normalized)
+                matches = self._record_tools._match_member_candidates(candidates, normalized)
+            except QingflowApiError as exc:
+                if exc.category == "not_supported":
+                    return None, {
+                        "code": "MEMBER_CANDIDATE_VALIDATION_SKIPPED",
+                        "message": f"Member candidate scope for column '{column['title']}' could not be resolved safely during local precheck.",
+                    }
+                raise
+            except RuntimeError:
+                return None, {
+                    "code": "MEMBER_CANDIDATE_VALIDATION_SKIPPED",
+                    "message": f"Member candidate scope for column '{column['title']}' could not be resolved safely during local precheck.",
+                }
+            if len(matches) != 1:
+                scope_miss_samples.append(f"row {row_index}: {normalized}")
+                if len(scope_miss_samples) >= 3:
+                    break
+        if invalid_email_samples:
+            return _issue(
+                "MEMBER_IMPORT_REQUIRES_EMAIL",
+                f"Column '{column['title']}' must use member email values in import files. Samples: {', '.join(invalid_email_samples)}",
+                severity="error",
+            ), None
+        if scope_miss_samples:
+            return _issue(
+                "MEMBER_NOT_IN_CANDIDATE_SCOPE",
+                f"Column '{column['title']}' contains members outside the current candidate scope. Samples: {', '.join(scope_miss_samples)}",
+                severity="error",
+            ), None
+        return None, None
+
+    def _inspect_department_column(
+        self,
+        *,
+        context,
+        sheet,
+        column_index: int,
+        column: JSONObject,
+        field,
+    ) -> tuple[JSONObject | None, JSONObject | None]:  # type: ignore[no-untyped-def]
+        scope_miss_samples: list[str] = []
+        checked_values: set[str] = set()
+        for row_index in range(2, sheet.max_row + 1):
+            value = sheet.cell(row=row_index, column=column_index).value
+            text = _normalize_optional_text(value)
+            if text is None:
+                continue
+            normalized = text.strip()
+            if normalized in checked_values:
+                continue
+            checked_values.add(normalized)
+            try:
+                candidates = self._record_tools._resolve_department_candidates(context, field, keyword=normalized)
+                matches = self._record_tools._match_department_candidates(candidates, normalized)
+            except QingflowApiError as exc:
+                if exc.category == "not_supported":
+                    return None, {
+                        "code": "DEPARTMENT_CANDIDATE_VALIDATION_SKIPPED",
+                        "message": f"Department candidate scope for column '{column['title']}' could not be resolved safely during local precheck.",
+                    }
+                raise
+            except RuntimeError:
+                return None, {
+                    "code": "DEPARTMENT_CANDIDATE_VALIDATION_SKIPPED",
+                    "message": f"Department candidate scope for column '{column['title']}' could not be resolved safely during local precheck.",
+                }
+            if len(matches) != 1:
+                scope_miss_samples.append(f"row {row_index}: {normalized}")
+                if len(scope_miss_samples) >= 3:
+                    break
+        if scope_miss_samples:
+            return _issue(
+                "DEPARTMENT_NOT_IN_CANDIDATE_SCOPE",
+                f"Column '{column['title']}' contains departments outside the current candidate scope. Samples: {', '.join(scope_miss_samples)}",
+                severity="error",
+            ), None
+        return None, None
+
     def _load_template_header_profile(
         self,
         context,
@@ -1215,12 +1440,17 @@ def _analyze_headers(
     *,
     allowed_titles: list[str] | None = None,
 ) -> dict[str, Any]:
-    expected_by_key = {_normalize_header_key(item["title"]): item for item in expected_columns}
-    allowed_by_key = (
-        {_normalize_header_key(title): title for title in allowed_titles if _normalize_optional_text(title)}
-        if allowed_titles
-        else {key: item["title"] for key, item in expected_by_key.items()}
-    )
+    expected_titles = [str(item["title"]) for item in expected_columns]
+    allowed_title_list = allowed_titles if allowed_titles else expected_titles
+    allowed_counts = _header_title_counts(allowed_title_list)
+    allowed_by_key = {
+        key: title
+        for key, title in (
+            (_normalize_header_key(title), _normalize_optional_text(title))
+            for title in allowed_title_list
+        )
+        if key and title
+    }
     seen: dict[str, int] = {}
     actual_headers: list[str] = []
     for item in header_row:
@@ -1231,10 +1461,24 @@ def _analyze_headers(
         actual_headers.append(text)
         key = _normalize_header_key(text)
         seen[key] = seen.get(key, 0) + 1
-    actual_keys = {key for key, count in seen.items() if key and count > 0}
-    missing = [title for key, title in allowed_by_key.items() if key not in actual_keys]
+    missing: list[str] = []
+    for key, expected_count in allowed_counts.items():
+        actual_count = seen.get(key, 0)
+        if actual_count >= expected_count:
+            continue
+        title = allowed_by_key.get(key) or key
+        if expected_count <= 1:
+            missing.append(title)
+        else:
+            missing.append(f"{title} (need {expected_count}, got {actual_count})")
     extra = [text for text in actual_headers if text and _normalize_header_key(text) not in allowed_by_key]
-    duplicates = [text for text in actual_headers if text and seen.get(_normalize_header_key(text), 0) > 1]
+    duplicates = []
+    for key, count in seen.items():
+        if not key:
+            continue
+        allowed_count = allowed_counts.get(key, 0)
+        if count > max(allowed_count, 1 if allowed_count == 0 else allowed_count):
+            duplicates.append(allowed_by_key.get(key) or key)
     issues: list[JSONObject] = []
     repair_suggestions: list[str] = []
     if missing:
@@ -1279,6 +1523,111 @@ def _analyze_headers(
     return {"issues": issues, "repair_suggestions": repair_suggestions}
 
 
+def _header_title_counts(titles: list[str]) -> dict[str, int]:
+    counts: dict[str, int] = {}
+    for title in titles:
+        key = _normalize_header_key(title)
+        if not key:
+            continue
+        counts[key] = counts.get(key, 0) + 1
+    return counts
+
+
+def _sheet_header_positions(sheet) -> dict[str, list[int]]:  # type: ignore[no-untyped-def]
+    mapping: dict[str, list[int]] = {}
+    for index, cell in enumerate(next(sheet.iter_rows(min_row=1, max_row=1), []), start=1):
+        key = _normalize_header_key(cell.value)
+        if not key:
+            continue
+        mapping.setdefault(key, []).append(index)
+    return mapping
+
+
+def _inspect_enum_column(sheet, *, column_index: int, column: JSONObject) -> JSONObject | None:  # type: ignore[no-untyped-def]
+    options = [str(item).strip() for item in column.get("options", []) if str(item).strip()]
+    if not options:
+        return None
+    option_map = {_normalize_header_key(item): item for item in options}
+    invalid_samples: list[str] = []
+    for row_index in range(2, sheet.max_row + 1):
+        text = _normalize_optional_text(sheet.cell(row=row_index, column=column_index).value)
+        if text is None:
+            continue
+        if _normalize_header_key(text) in option_map:
+            continue
+        invalid_samples.append(f"row {row_index}: {text}")
+        if len(invalid_samples) >= 3:
+            break
+    if not invalid_samples:
+        return None
+    return _issue(
+        "INVALID_ENUM_VALUES",
+        f"Column '{column['title']}' contains values outside the allowed options. Samples: {', '.join(invalid_samples)}",
+        severity="error",
+    )
+
+
+def _inspect_relation_column(sheet, *, column_index: int, column: JSONObject) -> JSONObject | None:  # type: ignore[no-untyped-def]
+    invalid_samples: list[str] = []
+    for row_index in range(2, sheet.max_row + 1):
+        value = sheet.cell(row=row_index, column=column_index).value
+        text = _normalize_optional_text(value)
+        if text is None:
+            continue
+        relation_id = _coerce_positive_relation_id(value)
+        if relation_id is not None:
+            continue
+        invalid_samples.append(f"row {row_index}: {text}")
+        if len(invalid_samples) >= 3:
+            break
+    if not invalid_samples:
+        return None
+    return _issue(
+        "RELATION_IMPORT_REQUIRES_APPLY_ID",
+        f"Column '{column['title']}' must use target record apply_id values during import. Samples: {', '.join(invalid_samples)}",
+        severity="error",
+    )
+
+
+def _stable_import_schema_fingerprint(expected_columns: list[JSONObject]) -> str:
+    stable_columns = []
+    for item in expected_columns:
+        stable_columns.append(
+            {
+                "field_id": item["field_id"],
+                "title": item["title"],
+                "que_type": item["que_type"],
+                "required": item["required"],
+                "write_kind": item["write_kind"],
+                "options": item.get("options", []),
+                "requires_lookup": bool(item.get("requires_lookup")),
+                "requires_upload": bool(item.get("requires_upload")),
+                "target_app_key": item.get("target_app_key"),
+            }
+        )
+    return hashlib.sha256(
+        json.dumps(stable_columns, ensure_ascii=False, sort_keys=True).encode("utf-8")
+    ).hexdigest()
+
+
+def _coerce_positive_relation_id(value: Any) -> int | None:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value if value > 0 else None
+    if isinstance(value, float):
+        if value.is_integer() and value > 0:
+            return int(value)
+        return None
+    text = _normalize_optional_text(value)
+    if text is None:
+        return None
+    if text.isdigit():
+        parsed = int(text)
+        return parsed if parsed > 0 else None
+    return None
+
+
 def _infer_header_depth(sheet) -> int:  # type: ignore[no-untyped-def]
     header_depth = 1
     merged_cells = getattr(sheet, "merged_cells", None)