@josephyan/qingflow-cli 0.2.0-beta.69 → 0.2.0-beta.71

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-cli",
-  "version": "0.2.0-beta.69",
+  "version": "0.2.0-beta.71",
   "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
   "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.0b71"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

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,186 @@ 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 {}
+        warnings: list[dict[str, Any]] = []
+        verification = {
+            "chart_exists": True,
+            "chart_data_loaded": True,
+            "chart_config_loaded": True,
+        }
+        try:
+            base = self.charts.qingbi_report_get_base(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}},
+            )
+
+        try:
+            config = self.charts.qingbi_report_get_config(profile=profile, chart_id=chart_id).get("result") or {}
+        except (QingflowApiError, RuntimeError) as error:
+            config_from_data = data.get("config") if isinstance(data, dict) else None
+            if isinstance(config_from_data, dict):
+                config = deepcopy(config_from_data)
+                verification["chart_config_loaded"] = True
+                warnings.append(
+                    _warning(
+                        "CHART_CONFIG_FALLBACK_FROM_DATA",
+                        "chart config endpoint is unavailable for this chart id; using config embedded in chart data instead",
+                    )
+                )
+            else:
+                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": warnings,
+            "verification": verification,
+            "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 +9121,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 +9320,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 +9494,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 +11265,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 +11331,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 = {