@josephyan/qingflow-app-user-mcp 0.2.0-beta.41 → 0.2.0-beta.42

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.2.0-beta.41",
+  "version": "0.2.0-beta.42",
   "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.0b41"
+version = "0.2.0b42"
 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.0b41"
+__version__ = "0.2.0b42"

package/src/qingflow_mcp/tools/import_tools.py

@@ -4,6 +4,7 @@ import hashlib
 import json
 import mimetypes
 import shutil
+from io import BytesIO
 from copy import deepcopy
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
@@ -197,13 +198,15 @@ class ImportTools(ToolBase):
 
         def runner(session_profile, context):
             expected_columns, schema_fingerprint = self._expected_import_columns(profile, context, app_key)
+            template_header_titles, header_warnings = self._load_template_header_titles(context, app_key)
             local_check = self._local_verify(
                 path=path,
                 app_key=app_key,
                 expected_columns=expected_columns,
+                allowed_header_titles=template_header_titles,
                 schema_fingerprint=schema_fingerprint,
             )
-            warnings = deepcopy(local_check["warnings"])
+            warnings = deepcopy(local_check["warnings"]) + header_warnings
             issues = deepcopy(local_check["issues"])
             can_import = bool(local_check["can_import"])
             backend_verification = None
@@ -629,6 +632,7 @@ class ImportTools(ToolBase):
         path: Path,
         app_key: str,
         expected_columns: list[JSONObject],
+        allowed_header_titles: list[str] | None,
         schema_fingerprint: str,
     ) -> dict[str, Any]:
         extension = path.suffix.lower()
@@ -681,7 +685,11 @@ class ImportTools(ToolBase):
             return base_result
         sheet = workbook[workbook.sheetnames[0]]
         header_row = [cell.value for cell in next(sheet.iter_rows(min_row=1, max_row=1), [])]
-        header_analysis = _analyze_headers(header_row, expected_columns)
+        header_analysis = _analyze_headers(
+            header_row,
+            expected_columns,
+            allowed_titles=allowed_header_titles,
+        )
         base_result["issues"].extend(header_analysis["issues"])
         base_result["repair_suggestions"].extend(header_analysis["repair_suggestions"])
         trailing_blank_rows = _count_trailing_blank_rows(sheet)
@@ -709,6 +717,31 @@ class ImportTools(ToolBase):
             base_result["error_code"] = "IMPORT_VERIFICATION_FAILED"
         return base_result
 
+    def _load_template_header_titles(self, context, app_key: str) -> tuple[list[str] | None, list[JSONObject]]:  # type: ignore[no-untyped-def]
+        warnings: list[JSONObject] = []
+        try:
+            payload = self.backend.request("GET", context, f"/app/{app_key}/apply/excelTemplate")
+            template_url = _pick_template_url(payload)
+            if not template_url:
+                return None, warnings
+            content = self.backend.download_binary(template_url)
+            workbook = load_workbook(BytesIO(content), read_only=True, data_only=False)
+            if not workbook.sheetnames:
+                return None, warnings
+            sheet = workbook[workbook.sheetnames[0]]
+            header_row = [cell.value for cell in next(sheet.iter_rows(min_row=1, max_row=1), [])]
+            titles = [_normalize_optional_text(value) for value in header_row]
+            normalized_titles = [title for title in titles if title]
+            return normalized_titles or None, warnings
+        except Exception:
+            warnings.append(
+                {
+                    "code": "IMPORT_TEMPLATE_HEADER_UNAVAILABLE",
+                    "message": "Official template headers could not be loaded during local precheck; falling back to applicant writable columns only.",
+                }
+            )
+            return None, warnings
+
     def _failed_template_result(
         self,
         *,
@@ -919,8 +952,18 @@ def _issue(code: str, message: str, *, severity: str, repairable: bool = False,
     return payload
 
 
-def _analyze_headers(header_row: list[Any], expected_columns: list[JSONObject]) -> dict[str, Any]:
+def _analyze_headers(
+    header_row: list[Any],
+    expected_columns: list[JSONObject],
+    *,
+    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()}
+    )
     seen: dict[str, int] = {}
     actual_headers: list[str] = []
     for item in header_row:
@@ -932,8 +975,8 @@ def _analyze_headers(header_row: list[Any], expected_columns: list[JSONObject])
         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 = [item["title"] for key, item in expected_by_key.items() if key not in actual_keys]
-    extra = [text for text in actual_headers if text and _normalize_header_key(text) not in expected_by_key]
+    missing = [title for key, title in allowed_by_key.items() if key not in actual_keys]
+    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]
     issues: list[JSONObject] = []
     repair_suggestions: list[str] = []
@@ -947,9 +990,9 @@ def _analyze_headers(header_row: list[Any], expected_columns: list[JSONObject])
     for text in actual_headers:
         if not text:
             continue
-        matched = expected_by_key.get(_normalize_header_key(text))
-        if matched and matched["title"] != text:
-            normalized_changes.append((text, matched["title"]))
+        canonical = allowed_by_key.get(_normalize_header_key(text))
+        if canonical and canonical != text:
+            normalized_changes.append((text, canonical))
     if normalized_changes:
         repair_suggestions.append("normalize_headers")
     return {"issues": issues, "repair_suggestions": repair_suggestions}