@josephyan/qingflow-app-user-mcp 0.2.0-beta.981 → 0.2.0-beta.982

package/README.md

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

package/package.json

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

package/src/qingflow_mcp/__init__.py

@@ -5,7 +5,7 @@ from pathlib import Path
 
 __all__ = ["__version__"]
 
-_FALLBACK_VERSION = "0.2.0b981"
+_FALLBACK_VERSION = "0.2.0b982"
 
 
 def _resolve_local_pyproject_version() -> str | None:

package/src/qingflow_mcp/builder_facade/models.py

@@ -1536,8 +1536,8 @@ class PortalApplyRequest(StrictModel):
             raise ValueError("package_tag_id is required when dash_key is empty")
         if not self.dash_key and not self.dash_name:
             raise ValueError("dash_name is required when creating a portal")
-        if not self.sections:
-            raise ValueError("portal apply requires a non-empty sections list")
+        if not self.dash_key and not self.sections:
+            raise ValueError("portal apply requires a non-empty sections list when creating a portal")
         if self.visibility is not None and self.auth is not None:
             raise ValueError("visibility and auth cannot be provided together")
         return self

package/src/qingflow_mcp/builder_facade/service.py

@@ -1413,6 +1413,8 @@ class AiBuilderFacade:
         issues: list[dict[str, Any]] = []
         resolved: list[dict[str, Any]] = []
         seen_ids: set[int] = set()
+        if not dept_ids and not dept_names:
+            return {"department_entries": resolved, "issues": issues}
         listed = self.directory.directory_list_all_departments(
             profile=profile,
             parent_dept_id=None,
@@ -6706,6 +6708,7 @@ class AiBuilderFacade:
 
         for patch in request.upsert_charts:
             try:
+                config_update_requested = _chart_patch_updates_chart_config(patch)
                 chart_visible_auth = (
                     self._compile_visibility_to_chart_visible_auth(profile=profile, visibility=patch.visibility)
                     if patch.visibility is not None
@@ -6809,18 +6812,17 @@ class AiBuilderFacade:
                             existing_by_name.pop(old_name, None)
                     existing_by_name.setdefault(patch.name, []).append(deepcopy(updated_chart))
 
-                config_payload = _build_public_chart_config_payload(
-                    patch=patch,
-                    app_key=app_key,
-                    field_lookup=field_lookup,
-                    qingbi_fields_by_id=qingbi_fields_by_id,
-                )
-                if isinstance(chart_visible_auth, dict):
-                    raw_data_config = config_payload.get("rawDataConfigDTO")
-                    if isinstance(raw_data_config, dict):
-                        raw_data_config["authInfo"] = deepcopy(chart_visible_auth)
-                self.charts.qingbi_report_update_config(profile=profile, chart_id=chart_id, payload=config_payload)
-                if existing is not None and chart_id not in updated_ids:
+                config_updated = False
+                if existing is None or config_update_requested:
+                    config_payload = _build_public_chart_config_payload(
+                        patch=patch,
+                        app_key=app_key,
+                        field_lookup=field_lookup,
+                        qingbi_fields_by_id=qingbi_fields_by_id,
+                    )
+                    self.charts.qingbi_report_update_config(profile=profile, chart_id=chart_id, payload=config_payload)
+                    config_updated = True
+                if existing is not None and chart_id not in updated_ids and config_updated:
                     updated_ids.append(chart_id)
                 if patch.question_config:
                     self._request_backend(
@@ -6836,6 +6838,8 @@ class AiBuilderFacade:
                         path=f"/chart/{chart_id}/user/config",
                         json_body=patch.user_config,
                     )
+                if existing is not None and chart_id not in updated_ids and (patch.question_config or patch.user_config):
+                    updated_ids.append(chart_id)
                 chart_results.append(
                     {
                         "chart_id": chart_id,
@@ -6992,11 +6996,12 @@ class AiBuilderFacade:
         permission_outcomes: list[PermissionCheckOutcome] = []
         dash_key = str(request.dash_key or "").strip()
         creating = not dash_key
+        sections_requested = creating or bool(request.sections)
         verify_dash_name = creating or request.dash_name is not None
         verify_dash_icon = bool(request.icon or request.color)
         verify_auth = request.visibility is not None or request.auth is not None
-        verify_hide_copyright = request.hide_copyright is not None
-        verify_dash_global_config = request.dash_global_config is not None
+        verify_hide_copyright = request.hide_copyright is not None and sections_requested
+        verify_dash_global_config = request.dash_global_config is not None and sections_requested
         verify_tags = creating or request.package_tag_id is not None
         requested_visibility = request.visibility
         if requested_visibility is None and isinstance(request.auth, dict) and request.auth:
@@ -7073,6 +7078,25 @@ class AiBuilderFacade:
             if package_edit_outcome.block is not None:
                 return package_edit_outcome.block
             permission_outcomes.append(package_edit_outcome)
+        if not sections_requested:
+            unsupported_base_only_keys: list[str] = []
+            if request.hide_copyright is not None:
+                unsupported_base_only_keys.append("hide_copyright")
+            if request.dash_global_config is not None:
+                unsupported_base_only_keys.append("dash_global_config")
+            if request.config:
+                unsupported_base_only_keys.append("config")
+            if unsupported_base_only_keys:
+                return _failed(
+                    "PORTAL_SECTIONS_REQUIRED",
+                    "editing a portal without sections only supports base-info updates",
+                    normalized_args=normalized_args,
+                    details={
+                        "unsupported_without_sections": unsupported_base_only_keys,
+                        "fix_hint": "Pass sections when changing layout or global portal config, or omit those keys for visibility/icon/package updates.",
+                    },
+                    suggested_next_call={"tool_name": "portal_apply", "arguments": {"profile": profile, **normalized_args}},
+                )
         try:
             if creating:
                 create_payload = _build_public_portal_base_payload(
@@ -7098,7 +7122,6 @@ class AiBuilderFacade:
                         suggested_next_call={"tool_name": "portal_apply", "arguments": {"profile": profile, **normalized_args}},
                     )
                 base_payload = self.portals.portal_get(profile=profile, dash_key=dash_key, being_draft=True).get("result") or {}
-            component_payload = self._build_portal_components_from_sections(profile=profile, sections=request.sections)
             update_payload = _build_public_portal_base_payload(
                 dash_name=request.dash_name or str(base_payload.get("dashName") or "").strip() or "未命名门户",
                 package_tag_id=target_package_tag_id,
@@ -7110,8 +7133,10 @@ class AiBuilderFacade:
                 config=request.config,
                 base_payload=base_payload,
             )
-            update_payload["components"] = component_payload
-            self.portals.portal_update(profile=profile, dash_key=dash_key, payload=update_payload)
+            if sections_requested:
+                component_payload = self._build_portal_components_from_sections(profile=profile, sections=request.sections)
+                update_payload["components"] = component_payload
+                self.portals.portal_update(profile=profile, dash_key=dash_key, payload=update_payload)
             self.portals.portal_update_base_info(
                 profile=profile,
                 dash_key=dash_key,
@@ -7148,11 +7173,14 @@ class AiBuilderFacade:
                 publish_failed = True
 
         draft_components = draft_result.get("components") if isinstance(draft_result, dict) else None
-        expected_count = len(request.sections)
-        draft_verified = isinstance(draft_components, list) and len(draft_components) == expected_count
+        expected_count = len(request.sections) if sections_requested else None
+        draft_verified = isinstance(draft_result, dict) and (
+            expected_count is None or (isinstance(draft_components, list) and len(draft_components) == expected_count)
+        )
         draft_meta_verified, draft_meta_mismatches = _verify_portal_readback(
             actual=draft_result,
             expected_payload=update_payload,
+            expected_visibility=requested_visibility.model_dump(mode="json") if requested_visibility is not None else None,
             expected_section_count=expected_count,
             requested_config_keys=set((request.config or {}).keys()),
             verify_dash_name=verify_dash_name,
@@ -7168,12 +7196,18 @@ class AiBuilderFacade:
         if request.publish:
             live_verified = (
                 isinstance(live_result, dict)
-                and isinstance(live_result.get("components"), list)
-                and len(live_result.get("components")) == expected_count
+                and (
+                    expected_count is None
+                    or (
+                        isinstance(live_result.get("components"), list)
+                        and len(live_result.get("components")) == expected_count
+                    )
+                )
             )
             live_meta_verified, live_meta_mismatches = _verify_portal_readback(
                 actual=live_result,
                 expected_payload=update_payload,
+                expected_visibility=requested_visibility.model_dump(mode="json") if requested_visibility is not None else None,
                 expected_section_count=expected_count,
                 requested_config_keys=set((request.config or {}).keys()),
                 verify_dash_name=verify_dash_name,
@@ -7207,7 +7241,15 @@ class AiBuilderFacade:
             "status": status,
             "error_code": error_code,
             "recoverable": not verified,
-            "message": "applied portal" if verified else "applied portal; draft/live verification pending",
+            "message": (
+                "updated portal base info"
+                if verified and not sections_requested
+                else "applied portal"
+                if verified
+                else "updated portal base info; draft/live verification pending"
+                if not sections_requested
+                else "applied portal; draft/live verification pending"
+            ),
             "normalized_args": normalized_args,
             "missing_fields": [],
             "allowed_values": {"section.source_type": ["chart", "view", "grid", "filter", "text", "link"]},
@@ -8733,6 +8775,11 @@ def _build_public_chart_config_payload(
     return payload
 
 
+def _chart_patch_updates_chart_config(patch: ChartUpsertPatch) -> bool:
+    explicit_fields = set(getattr(patch, "model_fields_set", set()) or set())
+    return bool({"dimension_field_ids", "indicator_field_ids", "filters", "config"} & explicit_fields)
+
+
 def _build_public_portal_base_payload(
     *,
     dash_name: str,
@@ -8962,7 +9009,8 @@ def _verify_portal_readback(
     *,
     actual: Any,
     expected_payload: dict[str, Any],
-    expected_section_count: int,
+    expected_visibility: dict[str, Any] | None,
+    expected_section_count: int | None,
     requested_config_keys: set[str],
     verify_dash_name: bool,
     verify_dash_icon: bool,
@@ -8975,14 +9023,19 @@ def _verify_portal_readback(
     if not isinstance(actual, dict):
         return False, ["portal readback payload is unavailable"]
     components = actual.get("components")
-    if not isinstance(components, list) or len(components) != expected_section_count:
+    if expected_section_count is not None and (not isinstance(components, list) or len(components) != expected_section_count):
         mismatches.append(f"components expected {expected_section_count}, got {len(components) if isinstance(components, list) else 'unavailable'}")
     if verify_dash_name and str(actual.get("dashName") or "").strip() != str(expected_payload.get("dashName") or "").strip():
         mismatches.append("dash_name")
     if verify_dash_icon and str(actual.get("dashIcon") or "") != str(expected_payload.get("dashIcon") or ""):
         mismatches.append("dash_icon")
-    if verify_auth and not _mapping_contains(actual.get("auth"), expected_payload.get("auth")):
-        mismatches.append("auth")
+    if verify_auth:
+        if expected_visibility is not None:
+            actual_visibility = _public_visibility_from_member_auth(actual.get("auth"))
+            if not _visibility_matches_expected(actual_visibility, expected_visibility):
+                mismatches.append("auth")
+        elif not _mapping_contains(actual.get("auth"), expected_payload.get("auth")):
+            mismatches.append("auth")
     if verify_hide_copyright and bool(actual.get("hideCopyright", False)) != bool(expected_payload.get("hideCopyright", False)):
         mismatches.append("hide_copyright")
     if verify_dash_global_config and not _mapping_contains(actual.get("dashGlobalConfig") or {}, expected_payload.get("dashGlobalConfig") or {}):
@@ -9190,7 +9243,11 @@ def _visibility_matches_expected(actual: Any, expected: Any) -> bool:
         if expected_text and sorted_values(actual_group, text_key) != expected_text:
             return False
 
-    if "include_sub_departs" in expected_selectors and actual_selectors.get("include_sub_departs") != expected_selectors.get("include_sub_departs"):
+    if (
+        "include_sub_departs" in expected_selectors
+        and expected_selectors.get("include_sub_departs") is not None
+        and actual_selectors.get("include_sub_departs") != expected_selectors.get("include_sub_departs")
+    ):
         return False
     return True
 

package/src/qingflow_mcp/cli/commands/builder.py

@@ -160,7 +160,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     portal_apply.add_argument("--dash-name", default="")
     portal_apply.add_argument("--package-id", type=int)
     portal_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=True)
-    portal_apply.add_argument("--sections-file", required=True)
+    portal_apply.add_argument("--sections-file")
     portal_apply.add_argument("--visibility-file")
     portal_apply.add_argument("--auth-file")
     portal_apply.add_argument("--icon")
@@ -513,13 +513,14 @@ def _handle_portal_apply(args: argparse.Namespace, context: CliContext) -> dict:
             "portal apply requires either --dash-key, or --package-id together with --dash-name.",
             fix_hint="Use `--dash-key` for an existing portal. For create mode, pass `--package-id --dash-name`.",
         )
+    sections = [] if not args.sections_file else require_list_arg(args.sections_file, option_name="--sections-file")
     return context.builder.portal_apply(
         profile=args.profile,
         dash_key=args.dash_key,
         dash_name=args.dash_name,
         package_id=args.package_id,
         publish=bool(args.publish),
-        sections=require_list_arg(args.sections_file, option_name="--sections-file"),
+        sections=sections,
         visibility=load_object_arg(args.visibility_file, option_name="--visibility-file"),
         auth=load_object_arg(args.auth_file, option_name="--auth-file"),
         icon=args.icon,

package/src/qingflow_mcp/cli/formatters.py

@@ -268,6 +268,7 @@ def _format_import_status(result: dict[str, Any]) -> str:
         f"Process ID: {result.get('process_id_str') or '-'}",
         f"Total Rows: {result.get('total') or 0}",
         f"Finished Rows: {result.get('finished') or 0}",
+        f"Succeeded Rows: {result.get('succeeded') or 0}",
         f"Failed Rows: {result.get('failed') or 0}",
         f"Progress: {result.get('progress') or '-'}",
     ]

package/src/qingflow_mcp/response_trim.py

@@ -343,7 +343,7 @@ def _trim_record_schema(payload: JSONObject) -> None:
         payload["required_fields"] = required_fields
         payload["optional_fields"] = optional_fields
 
-    for key in ("required_fields", "optional_fields", "runtime_linked_required_fields", "fields"):
+    for key in ("required_fields", "optional_fields", "runtime_linked_required_fields", "fields", "ambiguous_fields"):
         if key in payload:
             payload[key] = _compact_schema_fields(payload.get(key), template_map=template_map)
 
@@ -353,11 +353,12 @@ def _trim_record_schema(payload: JSONObject) -> None:
                 _pick(item, ("field_id", "title")) for item in payload.get(key) if isinstance(item, dict)
             ]
 
-    for key in ("workflow_node", "view_resolution", "field_count", "record_context_probe", "view_probe_summary", "ambiguous_fields"):
+    for key in ("workflow_node", "view_resolution", "field_count"):
         payload.pop(key, None)
 
 
 def _trim_record_write(payload: JSONObject) -> None:
+    payload.pop("verification", None)
     data = payload.get("data")
     if not isinstance(data, dict):
         return
@@ -370,6 +371,24 @@ def _trim_record_write(payload: JSONObject) -> None:
         data["resource"] = resource
     else:
         data.pop("resource", None)
+    verification = data.get("verification")
+    if isinstance(verification, dict):
+        compact_verification = _pick(
+            verification,
+            (
+                "verified",
+                "verification_mode",
+                "field_level_verified",
+            ),
+        )
+        if compact_verification:
+            data["verification"] = compact_verification
+        else:
+            data.pop("verification", None)
+    for key in ("blockers", "field_errors", "confirmation_requests", "resolved_fields"):
+        value = data.get(key)
+        if value in (None, [], {}, ""):
+            data.pop(key, None)
 
 
 def _trim_record_get(payload: JSONObject) -> None:
@@ -386,6 +405,12 @@ def _trim_record_get(payload: JSONObject) -> None:
     record = data.get("record")
     if isinstance(record, dict):
         compact["record"] = record
+    normalized_record = data.get("normalized_record")
+    if isinstance(normalized_record, dict):
+        compact["normalized_record"] = normalized_record
+    normalized_ambiguous_fields = data.get("normalized_ambiguous_fields")
+    if isinstance(normalized_ambiguous_fields, dict):
+        compact["normalized_ambiguous_fields"] = normalized_ambiguous_fields
     payload["data"] = compact
 
 
@@ -558,11 +583,14 @@ def _compact_schema_field(item: Any, *, template_map: dict[str, Any] | None) ->
 
 
 def _compact_import_column(item: dict[str, Any]) -> dict[str, Any]:
-    compact: dict[str, Any] = {
-        "title": item.get("title"),
-        "kind": item.get("kind") or item.get("write_kind"),
-        "required": bool(item.get("required")),
-    }
+    compact: dict[str, Any] = {}
+    title = item.get("title")
+    if title not in (None, ""):
+        compact["title"] = title
+    kind = item.get("kind") or item.get("write_kind")
+    if kind not in (None, ""):
+        compact["kind"] = kind
+    compact["required"] = bool(item.get("required"))
     options = item.get("options")
     if isinstance(options, list) and options:
         compact["options"] = options
@@ -590,18 +618,24 @@ def _trim_import_verify_payload(payload: JSONObject) -> None:
     issues = payload.get("issues") if isinstance(payload.get("issues"), list) else []
     issue_summary = _summarize_import_issues(issues)
     payload["issue_summary"] = issue_summary
+    columns = payload.get("columns")
+    if "expected_columns" not in payload and isinstance(columns, list):
+        payload["expected_columns"] = columns
     file_name = payload.get("file_name")
     if not file_name:
         file_path = payload.get("file_path")
         if isinstance(file_path, str) and file_path:
             payload["file_name"] = file_path.split("/")[-1]
-    for key in ("issues", "apply_rows", "expected_columns", "schema_fingerprint", "import_capability", "file_path", "file_sha256", "verified_file_sha256", "file_format", "auto_normalized", "local_precheck_limited"):
+    for key in ("apply_rows", "schema_fingerprint", "import_capability", "file_sha256", "verified_file_sha256", "file_format", "local_precheck_limited"):
         payload.pop(key, None)
 
 
 def _trim_import_repair_payload(payload: JSONObject) -> None:
     payload["verification_id"] = payload.get("new_verification_id") or payload.get("verification_id")
-    for key in ("new_verification_id", "source_file_path", "repaired_file_path", "post_repair_issues", "verification"):
+    post_repair_issues = payload.get("post_repair_issues")
+    if isinstance(post_repair_issues, list):
+        payload["post_repair_issue_summary"] = _summarize_import_issues(post_repair_issues)
+    for key in ("new_verification_id", "verification"):
         payload.pop(key, None)
 
 
@@ -615,7 +649,13 @@ def _trim_import_status_payload(payload: JSONObject) -> None:
     success_rows = payload.get("success_rows")
     failed_rows = payload.get("failed_rows")
     payload["total"] = total_rows
-    payload["finished"] = success_rows
+    if isinstance(success_rows, int) and isinstance(failed_rows, int):
+        payload["finished"] = success_rows + failed_rows
+    elif isinstance(success_rows, int):
+        payload["finished"] = success_rows
+    else:
+        payload["finished"] = None
+    payload["succeeded"] = success_rows
     payload["failed"] = failed_rows
     for key in (
         "matched_by",

package/src/qingflow_mcp/server_app_builder.py

@@ -38,7 +38,7 @@ def build_builder_server() -> FastMCP:
             "If creating or updating an app package may be appropriate, use package_apply with explicit user intent; otherwise use package_get and app_resolve to locate resources, "
             "app_get/app_get_fields/app_repair_code_blocks/app_get_layout/app_get_views/app_get_flow/app_get_charts/portal_list/portal_get/view_get/chart_get for configuration reads, "
             "member_search/role_search/role_create when workflow assignees must come from the directory or role catalog, preferring roles over explicit members unless the user explicitly names members, "
-            "then app_schema_apply/app_layout_apply/app_flow_apply/app_views_apply/app_charts_apply/portal_apply to execute normalized patches; these apply tools perform planning, normalization, and dependency checks internally where applicable. Schema/layout/views noop requests skip publish, charts are immediate-live without publish and resolve targets by chart_id first then exact unique chart name, portal updates are replace-only and publish=false only guarantees draft/base-info updates, and flow should use publish=false whenever you only want draft/precheck behavior. "
+            "then app_schema_apply/app_layout_apply/app_flow_apply/app_views_apply/app_charts_apply/portal_apply to execute normalized patches; these apply tools perform planning, normalization, and dependency checks internally where applicable. Schema/layout/views noop requests skip publish, charts are immediate-live without publish and resolve targets by chart_id first then exact unique chart name, portal updates use replace semantics only when sections are supplied and edit-mode base-info-only updates may omit sections, publish=false only guarantees draft/base-info updates, and flow should use publish=false whenever you only want draft/precheck behavior. "
             "For code_block fields with output bindings, always use qf_output assignment rather than const/let qf_output, and use app_repair_code_blocks when an existing form hangs because output-bound fields stay loading. "
             "Use package_apply to manage package metadata, visibility, grouping, and ordering, and app_publish_verify for explicit final publish verification. "
             "For workflow edits, keep the public builder surface on stable linear flows only: start/approve/fill/copy/webhook/end. Branch and condition nodes are intentionally disabled because the backend workflow route is not front-end stable for those node types. Declare node assignees and editable fields explicitly. "

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -1763,7 +1763,7 @@ class AiBuilderTools(ToolBase):
         dash_name: str = "",
         package_id: int | None = None,
         publish: bool = True,
-        sections: list[JSONObject],
+        sections: list[JSONObject] | None = None,
         visibility: JSONObject | None = None,
         auth: JSONObject | None = None,
         icon: str | None = None,
@@ -3179,14 +3179,15 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "chart.filter.operator": [member.value for member in ViewFilterOperator],
             **deepcopy(_VISIBILITY_ALLOWED_VALUES),
         },
-        "execution_notes": [
-            "app_charts_apply is immediate-live and does not publish",
-            "chart matching precedence is chart_id first, then exact unique chart name",
-            "when chart names are not unique, supply chart_id instead of guessing by name",
-            "successful create results must return a real backend chart_id",
-            "upsert_charts[].visibility compiles to QingBI visibleAuth; omit it on updates to preserve the existing visibleAuth",
-            *_VISIBILITY_EXECUTION_NOTES,
-        ],
+            "execution_notes": [
+                "app_charts_apply is immediate-live and does not publish",
+                "chart matching precedence is chart_id first, then exact unique chart name",
+                "when chart names are not unique, supply chart_id instead of guessing by name",
+                "successful create results must return a real backend chart_id",
+                "upsert_charts[].visibility compiles to QingBI base visibleAuth only",
+                "visibility-only updates keep the existing chart config and do not rewrite rawDataConfigDTO.authInfo",
+                *_VISIBILITY_EXECUTION_NOTES,
+            ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
@@ -3242,14 +3243,15 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "dashStyleConfigBO": "dash_style_config",
         },
         "allowed_values": {"section.source_type": ["chart", "view", "grid", "filter", "text", "link"], **deepcopy(_VISIBILITY_ALLOWED_VALUES)},
-        "execution_notes": [
-            "use exactly one resource mode",
-            "update mode: dash_key",
-            "create mode: package_id + dash_name",
-            "portal_apply uses replace semantics for sections",
-            "remove a section by omitting it from the new sections list",
-            "package_id is required when creating a new portal",
-            "publish=false only guarantees draft and base-info updates; it does not claim live has changed",
+            "execution_notes": [
+                "use exactly one resource mode",
+                "update mode: dash_key",
+                "create mode: package_id + dash_name",
+                "portal_apply uses replace semantics for sections",
+                "when editing an existing portal, sections may be omitted to update only base info such as visibility, icon, or package",
+                "remove a section by omitting it from the new sections list",
+                "package_id is required when creating a new portal",
+                "publish=false only guarantees draft and base-info updates; it does not claim live has changed",
             "chart_ref resolves by chart_id first, then exact unique chart_name",
             "view_ref resolves by view_key first, then exact unique view_name",
             "position.pc/mobile is the canonical portal layout shape",

package/src/qingflow_mcp/tools/import_tools.py

@@ -760,6 +760,8 @@ class ImportTools(ToolBase):
                 error_code="CONFIG_ERROR",
                 message="record_import_status_get accepts import_id or process_id_str, but not both at the same time",
                 extra={
+                    "import_id": normalized_import_id,
+                    "process_id_str": normalized_process_id,
                     "details": {
                         "fix_hint": "Use only one of `import_id` or `process_id_str`. You may pass `app_key` as an optional routing hint for direct method compatibility.",
                     }
@@ -770,6 +772,8 @@ class ImportTools(ToolBase):
                 error_code="CONFIG_ERROR",
                 message="record_import_status_get requires at least one selector: process_id_str, import_id, or app_key",
                 extra={
+                    "import_id": normalized_import_id,
+                    "process_id_str": normalized_process_id,
                     "details": {
                         "fix_hint": "Use `process_id_str` or `import_id` for a known import, or use only `app_key` to inspect the latest import in that app.",
                     }
@@ -783,6 +787,9 @@ class ImportTools(ToolBase):
             if local_job is None and normalized_process_id:
                 matches = [item for item in self._job_store.list() if _normalize_optional_text(item.get("process_id_str")) == normalized_process_id]
                 local_job = matches[0] if len(matches) == 1 else None
+            effective_process_id = normalized_process_id
+            if effective_process_id is None and isinstance(local_job, dict):
+                effective_process_id = _normalize_optional_text(local_job.get("process_id_str"))
             resolved_app_key = normalized_app_key
             if not resolved_app_key and isinstance(local_job, dict):
                 resolved_app_key = str(local_job.get("app_key") or "").strip()
@@ -791,6 +798,8 @@ class ImportTools(ToolBase):
                     error_code="CONFIG_ERROR",
                     message="record_import_status_get could not determine app_key from the provided selector",
                     extra={
+                        "import_id": normalized_import_id,
+                        "process_id_str": effective_process_id,
                         "details": {
                             "fix_hint": "Use the original `app_key`, or call import status with the latest-import mode: only `app_key`.",
                         }
@@ -809,13 +818,18 @@ class ImportTools(ToolBase):
             matched_record, matched_by = _match_import_record(
                 records,
                 local_job=local_job,
-                process_id_str=normalized_process_id,
+                import_id=normalized_import_id,
+                process_id_str=effective_process_id,
             )
             if matched_record is None:
                 return self._failed_status_result(
                     error_code="IMPORT_STATUS_AMBIGUOUS",
                     message="could not uniquely resolve an import record from the provided identifiers",
-                    extra={"matched_by": matched_by},
+                    extra={
+                        "import_id": normalized_import_id,
+                        "process_id_str": effective_process_id,
+                        "matched_by": matched_by,
+                    },
                 )
             normalized_process = _normalize_optional_text(
                 matched_record.get("processIdStr") or matched_record.get("processId") or matched_record.get("process_id_str")
@@ -2079,6 +2093,7 @@ def _match_import_record(
     records: list[JSONObject],
     *,
     local_job: dict[str, Any] | None,
+    import_id: str | None,
     process_id_str: str | None,
 ) -> tuple[JSONObject | None, str | None]:
     if process_id_str:
@@ -2091,6 +2106,16 @@ def _match_import_record(
             return exact[0], "process_id_str"
         if len(exact) > 1:
             return None, "process_id_str"
+    if import_id:
+        exact = [
+            item
+            for item in records
+            if import_id in _extract_import_record_ids(item)
+        ]
+        if len(exact) == 1:
+            return exact[0], "import_id"
+        if len(exact) > 1:
+            return None, "import_id"
     if isinstance(local_job, dict):
         source_file_name = _normalize_optional_text(local_job.get("source_file_name"))
         started_at = _parse_utc(local_job.get("started_at"))
@@ -2121,6 +2146,15 @@ def _match_import_record(
     return None, None
 
 
+def _extract_import_record_ids(record: JSONObject) -> set[str]:
+    identifiers: set[str] = set()
+    for key in ("importId", "import_id", "dataImportId", "data_import_id"):
+        normalized = _normalize_optional_text(record.get(key))
+        if normalized:
+            identifiers.add(normalized)
+    return identifiers
+
+
 def _parse_utc(value: Any) -> datetime | None:
     text = _normalize_optional_text(value)
     if text is None: