@josephyan/qingflow-app-user-mcp 0.2.0-beta.50 → 0.2.0-beta.52

package/README.md

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

package/npm/lib/runtime.mjs

@@ -82,6 +82,16 @@ export function getVenvServerCommand(packageRoot, commandName = "qingflow-mcp")
     : path.join(getVenvDir(packageRoot), "bin", commandName);
 }
 
+function readPackageVersion(packageRoot) {
+  const packageJsonPath = path.join(packageRoot, "package.json");
+  try {
+    const payload = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+    return typeof payload.version === "string" && payload.version.trim() ? payload.version.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
 function getVenvPip(packageRoot) {
   return WINDOWS
     ? path.join(getVenvDir(packageRoot), "Scripts", "pip.exe")
@@ -123,8 +133,18 @@ export function ensurePythonEnv(packageRoot, { force = false, commandName = "qin
   const venvPython = getVenvPython(packageRoot);
   const serverCommand = getVenvServerCommand(packageRoot, commandName);
   const stampPath = path.join(venvDir, ".bootstrap.json");
+  const packageVersion = readPackageVersion(packageRoot);
+  let stampVersion = null;
+  if (fs.existsSync(stampPath)) {
+    try {
+      const payload = JSON.parse(fs.readFileSync(stampPath, "utf8"));
+      stampVersion = typeof payload.package_version === "string" && payload.package_version.trim() ? payload.package_version.trim() : null;
+    } catch {
+      stampVersion = null;
+    }
+  }
 
-  if (!force && fs.existsSync(serverCommand) && fs.existsSync(stampPath)) {
+  if (!force && fs.existsSync(serverCommand) && fs.existsSync(stampPath) && stampVersion && stampVersion === packageVersion) {
     return serverCommand;
   }
 
@@ -145,6 +165,7 @@ export function ensurePythonEnv(packageRoot, { force = false, commandName = "qin
       {
         installed_at: new Date().toISOString(),
         installer: "npm",
+        package_version: packageVersion,
       },
       null,
       2

package/package.json

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

package/src/qingflow_mcp/tools/import_tools.py

@@ -267,12 +267,13 @@ class ImportTools(ToolBase):
                 app_key,
                 import_capability=import_capability,
             )
-            template_header_titles, header_warnings = self._load_template_header_titles(
+            template_header_profile, header_warnings = self._load_template_header_profile(
                 context,
                 app_key,
                 import_capability=import_capability,
                 expected_columns=expected_columns,
             )
+            template_header_titles = template_header_profile.get("allowed_titles")
             local_check = self._local_verify(
                 path=path,
                 app_key=app_key,
@@ -280,9 +281,28 @@ class ImportTools(ToolBase):
                 allowed_header_titles=template_header_titles,
                 schema_fingerprint=schema_fingerprint,
             )
-            warnings = import_warnings + deepcopy(local_check["warnings"]) + header_warnings
-            issues = deepcopy(local_check["issues"])
-            can_import = bool(local_check["can_import"])
+            effective_path = path
+            effective_local_check = local_check
+            auto_normalization = self._maybe_auto_normalize_file(
+                source_path=path,
+                expected_columns=expected_columns,
+                template_header_profile=template_header_profile,
+                local_check=local_check,
+            )
+            if auto_normalization is not None:
+                effective_path = Path(str(auto_normalization["verified_file_path"]))
+                effective_local_check = self._local_verify(
+                    path=effective_path,
+                    app_key=app_key,
+                    expected_columns=expected_columns,
+                    allowed_header_titles=list(auto_normalization["header_titles"]),
+                    schema_fingerprint=schema_fingerprint,
+                )
+            warnings = import_warnings + deepcopy(effective_local_check["warnings"]) + header_warnings
+            if auto_normalization is not None:
+                warnings.extend(deepcopy(auto_normalization["warnings"]))
+            issues = deepcopy(effective_local_check["issues"])
+            can_import = bool(effective_local_check["can_import"])
             backend_verification = None
             if can_import:
                 try:
@@ -292,9 +312,9 @@ class ImportTools(ToolBase):
                         f"/app/{app_key}/upload/verification",
                         files={
                             "file": (
-                                path.name,
-                                path.read_bytes(),
-                                mimetypes.guess_type(path.name)[0] or "application/octet-stream",
+                                effective_path.name,
+                                effective_path.read_bytes(),
+                                mimetypes.guess_type(effective_path.name)[0] or "application/octet-stream",
                             )
                         },
                     )
@@ -334,8 +354,11 @@ class ImportTools(ToolBase):
                 "profile": profile,
                 "app_key": app_key,
                 "file_path": str(path.resolve()),
+                "source_file_path": str(path.resolve()),
+                "verified_file_path": str(effective_path.resolve()) if effective_path != path else None,
                 "file_name": path.name,
                 "file_sha256": local_check["file_sha256"],
+                "verified_file_sha256": effective_local_check["file_sha256"] if effective_path != path else None,
                 "file_size": local_check["file_size"],
                 "schema_fingerprint": schema_fingerprint,
                 "can_import": can_import,
@@ -344,7 +367,9 @@ class ImportTools(ToolBase):
                 "import_capability": import_capability,
                 "apply_rows": backend_verification.get("applyRows") if isinstance(backend_verification, dict) else None,
                 "backend_verification": backend_verification,
-                "local_precheck": local_check,
+                "local_precheck": effective_local_check,
+                "source_local_precheck": local_check,
+                "auto_normalization": auto_normalization,
             }
             self._verification_store.put(verification_id, verification_payload)
             return {
@@ -354,8 +379,10 @@ class ImportTools(ToolBase):
                 "can_import": can_import,
                 "verification_id": verification_id,
                 "file_path": str(path.resolve()),
+                "verified_file_path": str(effective_path.resolve()) if effective_path != path else None,
                 "file_name": path.name,
                 "file_sha256": local_check["file_sha256"],
+                "verified_file_sha256": effective_local_check["file_sha256"] if effective_path != path else None,
                 "file_size": local_check["file_size"],
                 "schema_fingerprint": schema_fingerprint,
                 "apply_rows": backend_verification.get("applyRows") if isinstance(backend_verification, dict) else None,
@@ -372,8 +399,10 @@ class ImportTools(ToolBase):
                     and backend_verification.get("beingValidated", True) is not False,
                     "schema_fingerprint": schema_fingerprint,
                     "file_sha256": local_check["file_sha256"],
+                    "verified_file_sha256": effective_local_check["file_sha256"] if effective_path != path else None,
                     "file_format": local_check["extension"],
                     "local_precheck_limited": bool(local_check["local_precheck_limited"]),
+                    "auto_normalized": effective_path != path,
                 },
             }
 
@@ -409,7 +438,7 @@ class ImportTools(ToolBase):
             stored = self._verification_store.get(verification_id)
             if stored is None:
                 return self._failed_repair_result(error_code="IMPORT_VERIFICATION_STALE", message="verification_id is missing or expired")
-            source_path = Path(str(stored["file_path"]))
+            source_path = Path(str(stored.get("source_file_path") or stored["file_path"]))
             extension = source_path.suffix.lower()
             if extension not in REPAIRABLE_IMPORT_EXTENSIONS:
                 return self._failed_repair_result(
@@ -510,11 +539,12 @@ class ImportTools(ToolBase):
                 return self._failed_start_result(error_code="IMPORT_VERIFICATION_STALE", message="verification_id does not belong to the requested app")
             if not bool(stored.get("can_import")):
                 return self._failed_start_result(error_code="IMPORT_VERIFICATION_FAILED", message="verification_id is not importable", extra={"accepted": False})
-            current_path = Path(str(stored["file_path"]))
+            current_path = Path(str(stored.get("verified_file_path") or stored["file_path"]))
             if not current_path.is_file():
                 return self._failed_start_result(error_code="IMPORT_VERIFICATION_STALE", message="verified file no longer exists")
             current_sha256 = _sha256_file(current_path)
-            if current_sha256 != stored.get("file_sha256"):
+            expected_sha256 = stored.get("verified_file_sha256") or stored.get("file_sha256")
+            if current_sha256 != expected_sha256:
                 return self._failed_start_result(
                     error_code="IMPORT_FILE_CHANGED_AFTER_VERIFY",
                     message="the file changed after verification; run record_import_verify again",
@@ -542,7 +572,7 @@ class ImportTools(ToolBase):
                     being_enter_auditing=bool(being_enter_auditing),
                     view_key=view_key,
                     excel_url=file_url,
-                    excel_name=current_path.name,
+                    excel_name=str(stored.get("file_name") or current_path.name),
                 )
             except QingflowApiError as exc:
                 error_code = "IMPORT_SOCKET_ACK_TIMEOUT" if exc.details and exc.details.get("error_code") == "IMPORT_SOCKET_ACK_TIMEOUT" else "IMPORT_VERIFICATION_FAILED"
@@ -558,7 +588,7 @@ class ImportTools(ToolBase):
                     "app_key": app_key,
                     "import_id": import_id,
                     "process_id_str": process_id_str,
-                    "source_file_name": current_path.name,
+                    "source_file_name": str(stored.get("file_name") or current_path.name),
                     "started_at": started_at,
                     "file_url": file_url,
                     "verification_id": verification_id,
@@ -571,7 +601,7 @@ class ImportTools(ToolBase):
                 "accepted": True,
                 "import_id": import_id,
                 "process_id_str": process_id_str,
-                "source_file_name": current_path.name,
+                    "source_file_name": str(stored.get("file_name") or current_path.name),
                 "file_url": file_url,
                 "warnings": warnings,
                 "verification": {
@@ -810,29 +840,35 @@ class ImportTools(ToolBase):
             base_result["error_code"] = "IMPORT_VERIFICATION_FAILED"
         return base_result
 
-    def _load_template_header_titles(
+    def _load_template_header_profile(
         self,
         context,
         app_key: str,
         *,
         import_capability: JSONObject | None = None,
         expected_columns: list[JSONObject] | None = None,
-    ) -> tuple[list[str] | None, list[JSONObject]]:  # type: ignore[no-untyped-def]
+    ) -> tuple[dict[str, Any], 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
+                return {"allowed_titles": None, "leaf_titles": None, "header_depth": 1}, warnings
             content = self.backend.download_binary(template_url)
-            workbook = load_workbook(BytesIO(content), read_only=True, data_only=False)
+            workbook = load_workbook(BytesIO(content), read_only=False, data_only=False)
             if not workbook.sheetnames:
-                return None, warnings
+                return {"allowed_titles": None, "leaf_titles": None, "header_depth": 1}, 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
+            header_depth = _infer_header_depth(sheet)
+            leaf_titles = [title for title in _extract_leaf_header_titles(sheet, header_depth) if title]
+            return {
+                "allowed_titles": normalized_titles or None,
+                "leaf_titles": leaf_titles or None,
+                "header_depth": header_depth,
+            }, warnings
         except Exception:
             if (
                 _normalize_optional_text((import_capability or {}).get("auth_source")) == "apply_auth"
@@ -844,14 +880,78 @@ class ImportTools(ToolBase):
                         "message": "Official template headers require data management permission; local precheck fell back to applicant import columns.",
                     }
                 )
-                return [str(item["title"]) for item in expected_columns], warnings
+                fallback_titles = [str(item["title"]) for item in expected_columns]
+                return {"allowed_titles": fallback_titles, "leaf_titles": fallback_titles, "header_depth": 1}, warnings
             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
+            return {"allowed_titles": None, "leaf_titles": None, "header_depth": 1}, warnings
+
+    def _maybe_auto_normalize_file(
+        self,
+        *,
+        source_path: Path,
+        expected_columns: list[JSONObject],
+        template_header_profile: dict[str, Any],
+        local_check: dict[str, Any],
+    ) -> dict[str, Any] | None:
+        if source_path.suffix.lower() != ".xlsx":
+            return None
+        workbook = load_workbook(source_path, read_only=False, data_only=False)
+        if not workbook.sheetnames:
+            return None
+        sheet = workbook[workbook.sheetnames[0]]
+        header_depth = _infer_header_depth(sheet)
+        trailing_blank_rows = _count_trailing_blank_rows(sheet)
+        if header_depth <= 1 and trailing_blank_rows <= 0:
+            return None
+        extracted_headers = _extract_leaf_header_titles(sheet, header_depth)
+        target_headers = _overlay_header_titles(
+            extracted_headers,
+            template_header_profile.get("leaf_titles"),
+        )
+        verified_path = _resolve_verified_output_path(source_path)
+        normalized_workbook = Workbook()
+        normalized_sheet = normalized_workbook.active
+        normalized_sheet.title = sheet.title
+        normalized_sheet.append(target_headers)
+        last_nonblank_row = max(header_depth, sheet.max_row - trailing_blank_rows)
+        for row_index in range(header_depth + 1, last_nonblank_row + 1):
+            normalized_sheet.append(
+                [sheet.cell(row=row_index, column=column_index).value for column_index in range(1, sheet.max_column + 1)]
+            )
+        verified_path.parent.mkdir(parents=True, exist_ok=True)
+        normalized_workbook.save(verified_path)
+        warnings: list[JSONObject] = []
+        applied_repairs: list[str] = []
+        if header_depth > 1:
+            applied_repairs.append("normalize_headers")
+            warnings.append(
+                {
+                    "code": "IMPORT_HEADERS_AUTO_NORMALIZED",
+                    "message": f"Workbook used {header_depth} header rows; record_import_verify normalized it to a single leaf-header row automatically.",
+                }
+            )
+        if trailing_blank_rows > 0:
+            applied_repairs.append("trim_trailing_blank_rows")
+            warnings.append(
+                {
+                    "code": "TRAILING_BLANK_ROWS_AUTO_TRIMMED",
+                    "message": f"Removed {trailing_blank_rows} trailing blank rows before backend verification.",
+                }
+            )
+        return {
+            "verified_file_path": str(verified_path.resolve()),
+            "header_titles": target_headers,
+            "warnings": warnings,
+            "applied_repairs": applied_repairs,
+            "header_depth": header_depth,
+            "trailing_blank_rows": trailing_blank_rows,
+            "source_local_check": local_check,
+        }
 
     def _fetch_import_capability(self, context, app_key: str) -> tuple[JSONObject, list[JSONObject]]:  # type: ignore[no-untyped-def]
         try:
@@ -919,8 +1019,10 @@ class ImportTools(ToolBase):
             "can_import": False,
             "verification_id": None,
             "file_path": str(Path(file_path).expanduser()) if file_path else file_path,
+            "verified_file_path": None,
             "file_name": Path(file_path).name if file_path else None,
             "file_sha256": None,
+            "verified_file_sha256": None,
             "file_size": None,
             "schema_fingerprint": None,
             "apply_rows": None,
@@ -1028,7 +1130,7 @@ class ImportTools(ToolBase):
         response = {
             "ok": False,
             "status": "failed",
-            "error_code": payload.get("details", {}).get("error_code") or error_code,
+            "error_code": ((payload.get("details") or {}) if isinstance(payload.get("details"), dict) else {}).get("error_code") or error_code,
             "warnings": [],
             "verification": {},
             "message": payload.get("message") or str(error),
@@ -1067,6 +1169,10 @@ def _resolve_repaired_output_path(source_path: Path, *, output_path: str | None)
     return source_path.with_name(f"{source_path.stem}.repaired{source_path.suffix}")
 
 
+def _resolve_verified_output_path(source_path: Path) -> Path:
+    return Path(tempfile.gettempdir()) / f"qingflow-import-verified-{source_path.stem}-{uuid4().hex[:8]}{source_path.suffix}"
+
+
 def _utc_now() -> datetime:
     return datetime.now(timezone.utc)
 
@@ -1173,6 +1279,52 @@ def _analyze_headers(
     return {"issues": issues, "repair_suggestions": repair_suggestions}
 
 
+def _infer_header_depth(sheet) -> int:  # type: ignore[no-untyped-def]
+    header_depth = 1
+    merged_cells = getattr(sheet, "merged_cells", None)
+    merged_ranges = getattr(merged_cells, "ranges", merged_cells) if merged_cells is not None else []
+    row_one_has_merge = False
+    for merged_range in merged_ranges or []:
+        min_row = int(getattr(merged_range, "min_row", 1))
+        max_row = int(getattr(merged_range, "max_row", 1))
+        if min_row == 1:
+            row_one_has_merge = True
+            header_depth = max(header_depth, max_row)
+    if row_one_has_merge and sheet.max_row >= 2:
+        row_two_values = [cell.value for cell in sheet[2]]
+        if any(_normalize_optional_text(value) for value in row_two_values):
+            header_depth = max(header_depth, 2)
+    return min(header_depth, max(1, int(sheet.max_row)))
+
+
+def _extract_leaf_header_titles(sheet, header_depth: int) -> list[str]:  # type: ignore[no-untyped-def]
+    titles: list[str] = []
+    max_column = max(1, int(sheet.max_column))
+    depth = max(1, min(header_depth, int(sheet.max_row)))
+    for column_index in range(1, max_column + 1):
+        selected = ""
+        for row_index in range(depth, 0, -1):
+            text = _normalize_optional_text(sheet.cell(row=row_index, column=column_index).value)
+            if text:
+                selected = text
+                break
+        titles.append(selected)
+    return titles
+
+
+def _overlay_header_titles(actual_titles: list[str], template_leaf_titles: Any) -> list[str]:
+    normalized = list(actual_titles)
+    if not isinstance(template_leaf_titles, list):
+        return normalized
+    for index, title in enumerate(template_leaf_titles):
+        normalized_title = _normalize_optional_text(title)
+        if normalized_title is None:
+            continue
+        if index < len(normalized):
+            normalized[index] = normalized_title
+    return normalized
+
+
 def _count_trailing_blank_rows(sheet) -> int:  # type: ignore[no-untyped-def]
     count = 0
     for row_index in range(sheet.max_row, 1, -1):