@josephyan/qingflow-app-builder-mcp 0.2.0-beta.69 → 0.2.0-beta.70

package/README.md

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

package/package.json

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

package/skills/qingflow-app-builder/SKILL.md

@@ -48,7 +48,7 @@ Default modeling rules:
 
 - Authentication and workspace: `auth_*`, `workspace_*`
 - File upload: `file_upload_local`
-- Resource resolve/read: `package_list`, `package_resolve`, `package_create`, `builder_tool_contract`, `member_search`, `role_search`, `app_resolve`, `app_read_summary`, `app_read_fields`, `app_read_layout_summary`, `app_read_views_summary`, `app_read_flow_summary`, `app_read_charts_summary`, `portal_read_summary`
+- Resource resolve/read: `package_list`, `package_resolve`, `package_create`, `builder_tool_contract`, `member_search`, `role_search`, `app_resolve`, `app_read_summary`, `app_read_fields`, `app_read_layout_summary`, `app_read_views_summary`, `app_read_flow_summary`, `app_read_charts_summary`, `portal_list`, `portal_get`, `portal_read_summary`, `view_get`, `chart_get`
 - Resource patch: `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, `app_charts_apply`, `portal_apply`, `package_attach_app`, `app_release_edit_lock_if_mine`, `role_create`
 - Publish and verify: `app_publish_verify`
 
@@ -60,7 +60,11 @@ Note:
 - `app_charts_apply` is immediate-live and does not publish; it resolves targets by `chart_id` first and then exact unique chart name.
 - `portal_apply` uses replace semantics for sections; remove a section by omitting it from the next full sections list. `publish=false` only guarantees draft/base-info updates, and `chart_ref/view_ref` resolve by `id/key` first and exact unique name second.
 - `app_read_charts_summary` is the compact discovery path for current chart inventory; use it before `app_charts_apply` when you need exact `chart_id` values.
+- `chart_get` returns one chart's base info, config, and concrete chart data; prefer it over low-level `qingbi_report_*` reads in public builder flows.
+- `portal_list` is the discovery path for accessible portals.
 - `portal_read_summary` is the compact discovery path for portal draft/live summaries; it returns section summaries, not the raw dash payload.
+- `portal_get` returns portal-level detail plus a component inventory; it does not inline chart/view detail.
+- `view_get` returns one view's definition detail only; use `record_list` separately when you need rows from that view.
 - `app_schema_apply` / `app_layout_apply` / `app_flow_apply` / `app_views_apply` now perform planning, normalization, and dependency checks internally; when prechecks block, read the returned blocking issues and `suggested_next_call` directly from the apply result.
 - If you are unsure about a public builder tool's keys, aliases, presets, or minimal legal shape, call `builder_tool_contract` instead of guessing.
 - For views, always write the canonical key `columns`. Do not emit `column_names`; treat `fields` only as a tolerated legacy alias, not the preferred shape.
@@ -103,10 +107,10 @@ For builder work:
 2. Decide whether the target is one app or a multi-app package:
    - one app: continue with `app_resolve`
    - multi-app package/system: create or resolve the package, then create each app separately before adding relations
-3. Resolve the target app with `app_resolve` if the request is an update.
+3. Resolve the target app with `app_resolve` if the request is an update. Use exactly one selector mode: `app_key`, or `app_name + package_tag_id`.
 4. Read only the smallest summary you need: `app_read_summary`, `app_read_fields`, `app_read_layout_summary`, `app_read_views_summary`, `app_read_flow_summary`, `app_read_charts_summary`, `portal_read_summary`.
 5. Use `app_schema_apply` for create/upsert/remove field work. It publishes by default after the patch lands; noop schema requests do not publish.
-6. If the app must belong to a package, use `package_attach_app` explicitly after schema work unless readback already shows the target `tag_id`.
+6. If the app must belong to a package, use `package_attach_app` explicitly after schema work with `tag_id + app_key` unless readback already shows the target `tag_id`.
 7. Use `app_layout_apply` only when the user is explicitly changing layout. Prefer the default `mode=merge`; use `mode=replace` only when you intend to place every field explicitly. It publishes by default after the patch lands; noop layout requests do not publish.
 8. Use `app_flow_apply` after schema exists. It publishes by default; pass `publish=false` when you only want draft/precheck behavior.
 9. Use `app_views_apply` when the user wants explicit table/card/board/gantt views. It publishes by default after the patch lands; noop view requests do not publish.

package/skills/qingflow-app-builder/references/tool-selection.md

@@ -27,7 +27,7 @@ If the user asks for multiple forms/modules that relate to each other, this is a
 - `member_search`: resolve named people from the directory
 - `role_search`: resolve reusable roles from the directory
 - `role_create`: create a reusable role when the business owner wants role-based routing
-- `app_resolve`: locate an existing app by `app_key` or `app_name`
+- `app_resolve`: locate an existing app by exactly one selector mode: `app_key`, or `app_name + package_tag_id`
 
 ## Summary reads
 
@@ -48,11 +48,11 @@ These execute normalized patches and publish by default unless `publish=false`.
 - `app_flow_apply`: replace workflow
 - `app_views_apply`: upsert or remove views
 - `app_charts_apply`: upsert/remove/reorder QingBI charts; charts are immediate-live and do not publish; use `chart_id` when names are not unique
-- `portal_apply`: create or replace-update portal pages; sections are replace-only and omission deletes old sections; `publish=false` only guarantees draft/base-info updates
+- `portal_apply`: create or replace-update portal pages; use `dash_key` for update mode or `package_tag_id + dash_name` for create mode; sections are replace-only and omission deletes old sections; `publish=false` only guarantees draft/base-info updates
 
 ## Explicit post-apply tools
 
-- `package_attach_app`: attach an app to a package; do not assume create or publish attaches it
+- `package_attach_app`: attach an app to a package with `tag_id + app_key`; do not assume create or publish attaches it
 - `app_publish_verify`: explicit final publish verification when the user asks for live confirmation
 
 ## Decision shortcuts

package/skills/qingflow-app-builder-code-integrations/references/code-block.md

@@ -31,6 +31,32 @@ Outputs:
 - summary
 - next follow date
 
+## Target Field Rules
+
+Required:
+- every `outputs[*].target_field` must point to an existing field
+
+Allowed target field types:
+- text
+- long text
+- number
+- amount
+- date
+- datetime
+- single select
+- multi select
+- boolean
+
+Do not bind code block outputs to:
+- q_linker
+- code_block
+- relation
+- subtable
+- attachment
+- member
+- department
+- address
+
 ## Safe Verification
 
 - `app_read_fields`

package/skills/qingflow-app-builder-code-integrations/references/q-linker.md

@@ -44,6 +44,9 @@ Useful paths:
 
 ## Target Field Rules
 
+Required:
+- every `outputs[*].target_field` must point to an existing field
+
 Prefer:
 - text
 - long text

package/src/qingflow_mcp/backend_client.py

@@ -4,7 +4,6 @@ from dataclasses import dataclass
 from threading import Event
 from time import sleep
 from typing import Any
-from urllib.parse import urlsplit, urlunsplit
 from uuid import uuid4
 
 import httpx

package/src/qingflow_mcp/builder_facade/models.py

@@ -1382,6 +1382,11 @@ class AppChartsReadResponse(StrictModel):
     chart_count: int = 0
 
 
+class PortalListResponse(StrictModel):
+    items: list[dict[str, Any]] = Field(default_factory=list)
+    total: int = 0
+
+
 class PortalReadSummaryResponse(StrictModel):
     dash_key: str
     being_draft: bool = True
@@ -1395,6 +1400,35 @@ class PortalReadSummaryResponse(StrictModel):
     sections: list[dict[str, Any]] = Field(default_factory=list)
 
 
+class PortalGetResponse(StrictModel):
+    dash_key: str
+    being_draft: bool = True
+    dash_name: str | None = None
+    package_tag_ids: list[int] = Field(default_factory=list)
+    dash_icon: str | None = None
+    hide_copyright: bool | None = None
+    auth: dict[str, Any] = Field(default_factory=dict)
+    config: dict[str, Any] = Field(default_factory=dict)
+    dash_global_config: dict[str, Any] = Field(default_factory=dict)
+    component_count: int = 0
+    components: list[dict[str, Any]] = Field(default_factory=list)
+
+
+class ViewGetResponse(StrictModel):
+    viewgraph_key: str
+    base_info: dict[str, Any] = Field(default_factory=dict)
+    config: dict[str, Any] = Field(default_factory=dict)
+    questions: list[dict[str, Any]] = Field(default_factory=list)
+    associations: list[dict[str, Any]] = Field(default_factory=list)
+
+
+class ChartGetResponse(StrictModel):
+    chart_id: str
+    base: dict[str, Any] = Field(default_factory=dict)
+    config: dict[str, Any] = Field(default_factory=dict)
+    data: dict[str, Any] = Field(default_factory=dict)
+
+
 class SchemaPlanRequest(StrictModel):
     app_key: str = ""
     package_tag_id: int | None = None

package/src/qingflow_mcp/builder_facade/service.py

@@ -34,8 +34,8 @@ from .models import (
     AppChartsReadResponse,
     AppFieldsReadResponse,
     AppFlowReadResponse,
+    ChartGetResponse,
     AppLayoutReadResponse,
-    PortalReadSummaryResponse,
     AppReadSummaryResponse,
     AppViewsReadResponse,
     ChartApplyRequest,
@@ -53,6 +53,9 @@ from .models import (
     LayoutSectionPatch,
     LayoutPreset,
     PortalApplyRequest,
+    PortalGetResponse,
+    PortalListResponse,
+    PortalReadSummaryResponse,
     PortalSectionPatch,
     PublicFieldType,
     PublicRelationMode,
@@ -65,6 +68,7 @@ from .models import (
     ViewButtonBindingPatch,
     ViewUpsertPatch,
     ViewFilterOperator,
+    ViewGetResponse,
     ViewsPlanRequest,
     ViewsPreset,
     FlowPreset,
@@ -114,6 +118,18 @@ FIELD_TYPE_TO_QUESTION_TYPE: dict[str, int] = {
     FieldType.relation.value: 25,
 }
 
+INTEGRATION_OUTPUT_TARGET_FIELD_TYPES: tuple[str, ...] = (
+    FieldType.text.value,
+    FieldType.long_text.value,
+    FieldType.number.value,
+    FieldType.amount.value,
+    FieldType.date.value,
+    FieldType.datetime.value,
+    FieldType.single_select.value,
+    FieldType.multi_select.value,
+    FieldType.boolean.value,
+)
+
 MATCH_TYPE_ACCURACY = 1
 JUDGE_EQUAL = 0
 JUDGE_UNEQUAL = 1
@@ -2261,6 +2277,38 @@ class AiBuilderFacade:
             **response.model_dump(mode="json"),
         }
 
+    def portal_list(self, *, profile: str) -> JSONObject:
+        try:
+            raw_items = self.portals.portal_list(profile=profile).get("items") or []
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "PORTAL_LIST_FAILED",
+                api_error,
+                normalized_args={},
+                details={},
+                suggested_next_call=None,
+            )
+        items = _normalize_portal_list_items(raw_items)
+        response = PortalListResponse(items=items, total=len(items))
+        return {
+            "status": "success",
+            "error_code": None,
+            "recoverable": False,
+            "message": "list accessible portals",
+            "normalized_args": {},
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {},
+            "request_id": None,
+            "suggested_next_call": None,
+            "noop": False,
+            "warnings": [],
+            "verification": {"portal_list_loaded": True},
+            "verified": True,
+            **response.model_dump(mode="json"),
+        }
+
     def _load_chart_list_for_builder(self, *, profile: str, app_key: str) -> tuple[list[dict[str, Any]], str]:
         try:
             sorted_items = self.charts.qingbi_report_list_sorted(profile=profile, app_key=app_key, page_num=1, page_size=500).get("items") or []
@@ -2271,6 +2319,57 @@ class AiBuilderFacade:
         fallback_items = self.charts.qingbi_report_list(profile=profile, app_key=app_key).get("items") or []
         return list(fallback_items) if isinstance(fallback_items, list) else [], "fallback"
 
+    def portal_get(self, *, profile: str, dash_key: str, being_draft: bool = True) -> JSONObject:
+        try:
+            result = self.portals.portal_get(profile=profile, dash_key=dash_key, being_draft=being_draft).get("result") or {}
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "PORTAL_GET_FAILED",
+                api_error,
+                normalized_args={"dash_key": dash_key, "being_draft": being_draft},
+                details={"dash_key": dash_key, "being_draft": being_draft},
+                suggested_next_call={"tool_name": "portal_get", "arguments": {"profile": profile, "dash_key": dash_key, "being_draft": being_draft}},
+            )
+        response = PortalGetResponse(
+            dash_key=dash_key,
+            being_draft=being_draft,
+            dash_name=str(result.get("dashName") or "").strip() or None,
+            package_tag_ids=[
+                tag_id
+                for tag_id in (
+                    _coerce_positive_int((item or {}).get("tagId"))
+                    for item in (result.get("tags") or [])
+                    if isinstance(item, dict)
+                )
+                if tag_id is not None
+            ],
+            dash_icon=str(result.get("dashIcon") or "").strip() or None,
+            hide_copyright=bool(result.get("hideCopyright")) if "hideCopyright" in result else None,
+            auth=deepcopy(result.get("auth")) if isinstance(result.get("auth"), dict) else {},
+            config=deepcopy(result.get("config")) if isinstance(result.get("config"), dict) else {},
+            dash_global_config=deepcopy(result.get("dashGlobalConfig")) if isinstance(result.get("dashGlobalConfig"), dict) else {},
+            component_count=len(result.get("components") or []) if isinstance(result.get("components"), list) else 0,
+            components=_normalize_portal_components(result.get("components")),
+        )
+        return {
+            "status": "success",
+            "error_code": None,
+            "recoverable": False,
+            "message": "read portal detail",
+            "normalized_args": {"dash_key": dash_key, "being_draft": being_draft},
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {},
+            "request_id": None,
+            "suggested_next_call": None,
+            "noop": False,
+            "warnings": [],
+            "verification": {"portal_exists": True, "being_draft": being_draft},
+            "verified": True,
+            **response.model_dump(mode="json"),
+        }
+
     def portal_read_summary(self, *, profile: str, dash_key: str, being_draft: bool = True) -> JSONObject:
         try:
             result = self.portals.portal_get(profile=profile, dash_key=dash_key, being_draft=being_draft).get("result") or {}
@@ -2321,6 +2420,151 @@ class AiBuilderFacade:
             **response.model_dump(mode="json"),
         }
 
+    def view_get(self, *, profile: str, viewgraph_key: str) -> JSONObject:
+        try:
+            config = self.views.view_get_config(profile=profile, viewgraph_key=viewgraph_key).get("result") or {}
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "VIEW_GET_FAILED",
+                api_error,
+                normalized_args={"viewgraph_key": viewgraph_key},
+                details={"viewgraph_key": viewgraph_key},
+                suggested_next_call={"tool_name": "view_get", "arguments": {"profile": profile, "viewgraph_key": viewgraph_key}},
+            )
+
+        warnings: list[dict[str, Any]] = []
+        verification = {
+            "view_exists": True,
+            "base_info_verified": True,
+            "questions_verified": True,
+            "associations_verified": True,
+        }
+
+        base_info: dict[str, Any] = {}
+        try:
+            base_info_payload = self.views.view_get_base_info(profile=profile, viewgraph_key=viewgraph_key, passcode=None).get("result") or {}
+            if isinstance(base_info_payload, dict):
+                base_info = deepcopy(base_info_payload)
+        except (QingflowApiError, RuntimeError):
+            verification["base_info_verified"] = False
+            warnings.append(_warning("VIEW_BASE_INFO_UNAVAILABLE", "view base info readback is unavailable"))
+
+        questions: list[dict[str, Any]] = []
+        try:
+            questions_payload = self.views.view_list_questions(profile=profile, viewgraph_key=viewgraph_key).get("result") or []
+            if isinstance(questions_payload, list):
+                questions = [deepcopy(item) for item in questions_payload if isinstance(item, dict)]
+        except (QingflowApiError, RuntimeError):
+            verification["questions_verified"] = False
+            warnings.append(_warning("VIEW_QUESTIONS_UNAVAILABLE", "view question list readback is unavailable"))
+
+        associations: list[dict[str, Any]] = []
+        try:
+            associations_payload = self.views.view_list_associations(profile=profile, viewgraph_key=viewgraph_key).get("result") or []
+            if isinstance(associations_payload, list):
+                associations = [deepcopy(item) for item in associations_payload if isinstance(item, dict)]
+        except (QingflowApiError, RuntimeError):
+            verification["associations_verified"] = False
+            warnings.append(_warning("VIEW_ASSOCIATIONS_UNAVAILABLE", "view association list readback is unavailable"))
+
+        response = ViewGetResponse(
+            viewgraph_key=viewgraph_key,
+            base_info=base_info,
+            config=deepcopy(config) if isinstance(config, dict) else {},
+            questions=questions,
+            associations=associations,
+        )
+        return {
+            "status": "success",
+            "error_code": None,
+            "recoverable": False,
+            "message": "read view detail",
+            "normalized_args": {"viewgraph_key": viewgraph_key},
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {},
+            "request_id": None,
+            "suggested_next_call": None,
+            "noop": False,
+            "warnings": warnings,
+            "verification": verification,
+            "verified": all(bool(value) for value in verification.values()),
+            **response.model_dump(mode="json"),
+        }
+
+    def chart_get(
+        self,
+        *,
+        profile: str,
+        chart_id: str,
+        data_payload: dict[str, Any] | None = None,
+        page_num: int | None = None,
+        page_size: int | None = None,
+        page_num_y: int | None = None,
+        page_size_y: int | None = None,
+    ) -> JSONObject:
+        normalized_payload = deepcopy(data_payload) if isinstance(data_payload, dict) else {}
+        try:
+            base = self.charts.qingbi_report_get_base(profile=profile, chart_id=chart_id).get("result") or {}
+            config = self.charts.qingbi_report_get_config(profile=profile, chart_id=chart_id).get("result") or {}
+            data = self.charts.qingbi_report_get_data(
+                profile=profile,
+                chart_id=chart_id,
+                payload=normalized_payload,
+                page_num=page_num,
+                page_size=page_size,
+                page_num_y=page_num_y,
+                page_size_y=page_size_y,
+            ).get("result") or {}
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "CHART_GET_FAILED",
+                api_error,
+                normalized_args={
+                    "chart_id": chart_id,
+                    "data_payload": normalized_payload,
+                    "page_num": page_num,
+                    "page_size": page_size,
+                    "page_num_y": page_num_y,
+                    "page_size_y": page_size_y,
+                },
+                details={"chart_id": chart_id},
+                suggested_next_call={"tool_name": "chart_get", "arguments": {"profile": profile, "chart_id": chart_id}},
+            )
+
+        response = ChartGetResponse(
+            chart_id=chart_id,
+            base=deepcopy(base) if isinstance(base, dict) else {},
+            config=deepcopy(config) if isinstance(config, dict) else {},
+            data=deepcopy(data) if isinstance(data, dict) else {"value": data},
+        )
+        return {
+            "status": "success",
+            "error_code": None,
+            "recoverable": False,
+            "message": "read chart detail",
+            "normalized_args": {
+                "chart_id": chart_id,
+                "data_payload": normalized_payload,
+                "page_num": page_num,
+                "page_size": page_size,
+                "page_num_y": page_num_y,
+                "page_size_y": page_size_y,
+            },
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {},
+            "request_id": None,
+            "suggested_next_call": None,
+            "noop": False,
+            "warnings": [],
+            "verification": {"chart_exists": True, "chart_data_loaded": True},
+            "verified": True,
+            **response.model_dump(mode="json"),
+        }
+
     def app_schema_plan(self, *, profile: str, request: SchemaPlanRequest) -> JSONObject:
         normalized_args = request.model_dump(mode="json")
         target = self._preview_target_app(
@@ -8842,8 +9086,9 @@ def _compile_code_block_binding_fields(
                 selector_payload=target_payload,
                 location=f"code_block_binding.outputs[{output_index}].target_field",
             )
-            if str(target_field.get("type") or "") in {FieldType.code_block.value, FieldType.subtable.value, FieldType.relation.value}:
-                raise ValueError(f"code_block output target field '{target_field.get('name')}' uses an unsupported field type")
+            target_type = str(target_field.get("type") or "")
+            if not _integration_output_target_type_supported(target_type):
+                raise ValueError(_integration_output_target_type_error("code_block", str(target_field.get("name") or ""), target_type))
             target_que_ref = _coerce_positive_int(target_field.get("que_id"))
             if target_que_ref is None:
                 target_que_ref = _coerce_any_int(target_field.get("que_temp_id"))
@@ -9040,18 +9285,17 @@ def _overlay_code_block_binding_fields(*, target_fields: list[dict[str, Any]], s
             field["code_block_binding"] = binding
 
 
-def _q_linker_target_type_supported(field_type: str) -> bool:
-    return field_type in {
-        FieldType.text.value,
-        FieldType.long_text.value,
-        FieldType.number.value,
-        FieldType.amount.value,
-        FieldType.date.value,
-        FieldType.datetime.value,
-        FieldType.single_select.value,
-        FieldType.multi_select.value,
-        FieldType.boolean.value,
-    }
+def _integration_output_target_type_supported(field_type: str) -> bool:
+    return field_type in INTEGRATION_OUTPUT_TARGET_FIELD_TYPES
+
+
+def _integration_output_target_type_error(binding_kind: str, field_name: str, field_type: str) -> str:
+    allowed = ", ".join(INTEGRATION_OUTPUT_TARGET_FIELD_TYPES)
+    rendered_type = field_type or "unknown"
+    return (
+        f"{binding_kind} output target field '{field_name}' uses unsupported field type '{rendered_type}'. "
+        f"Allowed target field types: {allowed}"
+    )
 
 
 def _compile_q_linker_binding_fields(
@@ -9215,8 +9459,8 @@ def _compile_q_linker_binding_fields(
                 location=f"q_linker_binding.outputs[{output_index}].target_field",
             )
             target_type = str(target_field.get("type") or "")
-            if not _q_linker_target_type_supported(target_type):
-                raise ValueError(f"q_linker output target field '{target_field.get('name')}' uses an unsupported field type")
+            if not _integration_output_target_type_supported(target_type):
+                raise ValueError(_integration_output_target_type_error("q_linker", str(target_field.get("name") or ""), target_type))
             target_ref = _coerce_positive_int(target_field.get("que_id"))
             if target_ref is None:
                 target_ref = _coerce_any_int(target_field.get("que_temp_id"))
@@ -10986,6 +11230,38 @@ def _summarize_charts(result: Any) -> list[dict[str, Any]]:
     return items
 
 
+def _normalize_portal_list_items(raw_items: Any) -> list[dict[str, Any]]:
+    if not isinstance(raw_items, list):
+        return []
+    items: list[dict[str, Any]] = []
+    for item in raw_items:
+        if not isinstance(item, dict):
+            continue
+        dash_key = str(item.get("dashKey") or "").strip()
+        dash_name = str(item.get("dashName") or "").strip()
+        dash_icon = str(item.get("dashIcon") or "").strip() or None
+        package_tag_ids = [
+            tag_id
+            for tag_id in (
+                _coerce_positive_int((tag or {}).get("tagId"))
+                for tag in (item.get("tags") or [])
+                if isinstance(tag, dict)
+            )
+            if tag_id is not None
+        ]
+        if not any((dash_key, dash_name, dash_icon, package_tag_ids)):
+            continue
+        items.append(
+            {
+                "dash_key": dash_key or None,
+                "dash_name": dash_name or None,
+                "dash_icon": dash_icon,
+                "package_tag_ids": package_tag_ids,
+            }
+        )
+    return items
+
+
 def _summarize_portal_sections(components: Any) -> list[dict[str, Any]]:
     if not isinstance(components, list):
         return []
@@ -11020,6 +11296,50 @@ def _summarize_portal_sections(components: Any) -> list[dict[str, Any]]:
     return items
 
 
+def _normalize_portal_components(components: Any) -> list[dict[str, Any]]:
+    if not isinstance(components, list):
+        return []
+    items: list[dict[str, Any]] = []
+    config_key_map = {
+        "grid": "gridConfig",
+        "link": "linkConfig",
+        "text": "textConfig",
+        "filter": "filterConfig",
+        "chart": "chartConfig",
+        "view": "viewgraphConfig",
+    }
+    for index, component in enumerate(components):
+        if not isinstance(component, dict):
+            continue
+        source_type = _normalize_portal_component_source_type(component.get("type"))
+        title = _extract_portal_component_title(component, source_type=source_type)
+        summary: dict[str, Any] = {
+            "order": index,
+            "source_type": source_type,
+            "title": title,
+        }
+        position = component.get("position")
+        if isinstance(position, dict):
+            summary["position"] = deepcopy(position)
+        config_key = config_key_map.get(source_type, "")
+        config = component.get(config_key) if isinstance(component.get(config_key), dict) else {}
+        if source_type == "chart":
+            summary["chart_ref"] = {
+                "chart_id": str(config.get("biChartId") or "").strip() or None,
+                "chart_name": str(config.get("chartComponentTitle") or title or "").strip() or None,
+            }
+        elif source_type == "view":
+            summary["view_ref"] = {
+                "app_key": str(config.get("appKey") or "").strip() or None,
+                "view_key": str(config.get("viewgraphKey") or "").strip() or None,
+                "view_name": str(config.get("viewgraphName") or title or "").strip() or None,
+            }
+        elif source_type in {"grid", "link", "text", "filter"} and config:
+            summary["config"] = deepcopy(config)
+        items.append(summary)
+    return items
+
+
 def _normalize_portal_component_source_type(value: Any) -> str:
     raw = str(value or "").strip()
     mapping = {