@josephyan/qingflow-app-builder-mcp 0.2.0-beta.40 → 0.2.0-beta.42

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-builder-mcp",
-  "version": "0.2.0-beta.40",
+  "version": "0.2.0-beta.42",
   "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.0b40"
+version = "0.2.0b42"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"
@@ -26,8 +26,10 @@ dependencies = [
   "mcp>=1.9.4,<2.0.0",
   "httpx>=0.27,<1.0",
   "keyring>=25.5,<26.0",
+  "openpyxl>=3.1,<4.0",
   "pydantic>=2.8,<3.0",
   "pycryptodome>=3.20,<4.0",
+  "python-socketio[client]>=5.11,<6.0",
 ]
 
 [project.optional-dependencies]

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

@@ -67,6 +67,14 @@ Note:
 - For flow presets, map natural language to canonical values before calling MCP:
   - “默认审批/基础审批/普通审批” -> `basic_approval`
   - “先填报再审批/提交后审批” -> `basic_fill_then_approve`
+- Public flow building is intentionally limited to linear workflows:
+  - `start`
+  - `approve`
+  - `fill`
+  - `copy`
+  - `webhook`
+  - `end`
+  Do not generate `branch` or `condition` nodes in the public builder surface. The backend workflow route is not front-end stable for those node types.
 - For first-time flow or view work in a session, read `builder_tool_contract` before planning so keys, aliases, presets, and minimal examples come from MCP instead of memory.
 - For workflow assignees, prefer roles over explicit members:
   - use `role_search` first
@@ -181,6 +189,10 @@ For additive work on existing systems:
 - All public builder tools expose top-level `warnings`, `verification`, and `verified`. Read them before deciding whether a run is fully done.
 - For read tools, `status=success` can still pair with `verified=false` when some optional readback is unavailable; in that case prefer `warnings` and `verification` over the bare status code.
 - For `app_charts_apply`, `portal_apply`, and `app_publish_verify`, treat `success` as “write and verification completed” and `partial_success` as “write executed but verification is incomplete”.
+- For `app_schema_apply`, multiple relation fields are a known high-risk backend area. If you see `RELATION_FIELD_LIMIT_RISK` or `verification.relation_field_limit_verified=false`, do not describe the schema as fully safe.
+- For `app_layout_apply`, trust `verification.layout_verified` first and `verification.layout_summary_verified` second. `LAYOUT_SUMMARY_UNVERIFIED` means the raw form readback is more trustworthy than the compact summary.
+- For `app_views_apply`, treat `verification.views_verified` and `verification.view_filters_verified` separately. A created view with unverified filters is not a finished business view.
+- For `app_flow_apply`, treat only linear node structure as publicly supported. If you see `FLOW_NODE_TYPE_UNSUPPORTED`, redesign the workflow as a stable linear flow instead of retrying branch/condition nodes.
 - If readback mismatches the UI, compare `request_route` and do not assume the builder hit the same `qf_version` as the browser
 - Treat post-write readback as the source of truth, not just write status codes
 - For views, a top-level `VIEW_APPLY_FAILED` does not prove all requested views failed. Read back the view list and verify which views actually landed.

package/skills/qingflow-app-builder/references/update-flow.md

@@ -61,60 +61,16 @@ For flexible business requirements, do not jump straight to a full custom graph.
 2. identify the business-specific changes
 3. patch nodes/transitions explicitly
 
-For branch flows, keep the public shape canonical:
+Public flow building is intentionally limited to linear workflows. Use only:
 
-1. add a `branch` node
-2. add one or more `condition` nodes as branch lanes
-3. put filter rules on the `condition` nodes with `conditions` or `condition_groups`
-4. use an empty `condition` node as the default branch when needed
+- `start`
+- `approve`
+- `fill`
+- `copy`
+- `webhook`
+- `end`
 
-Canonical branch example:
-
-```json
-{
-  "tool_name": "app_flow_apply",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_123",
-    "mode": "replace",
-    "nodes": [
-      {"id": "start", "type": "start", "name": "发起"},
-      {"id": "route", "type": "branch", "name": "金额分支"},
-      {
-        "id": "high_amount",
-        "type": "condition",
-        "name": "金额大于等于一万",
-        "conditions": [
-          {"field_name": "预计金额", "operator": "gte", "value": 10000}
-        ]
-      },
-      {
-        "id": "approve_finance",
-        "type": "approve",
-        "name": "财务审批",
-        "assignees": {"role_names": ["财务负责人"]}
-      },
-      {"id": "default_lane", "type": "condition", "name": "其他情况"},
-      {
-        "id": "approve_manager",
-        "type": "approve",
-        "name": "部门审批",
-        "assignees": {"role_names": ["项目经理"]}
-      },
-      {"id": "end", "type": "end", "name": "结束"}
-    ],
-    "transitions": [
-      {"from": "start", "to": "route"},
-      {"from": "route", "to": "high_amount"},
-      {"from": "high_amount", "to": "approve_finance"},
-      {"from": "route", "to": "default_lane"},
-      {"from": "default_lane", "to": "approve_manager"},
-      {"from": "approve_finance", "to": "end"},
-      {"from": "approve_manager", "to": "end"}
-    ]
-  }
-}
-```
+Do not generate `branch` or `condition` nodes through `app_flow_apply`. The backend workflow route is not front-end stable for those node types, and MCP now returns `FLOW_NODE_TYPE_UNSUPPORTED` instead of writing a visually broken flow.
 After `app_flow_apply` returns blocking issues or canonical arguments, prefer reusing its `suggested_next_call.arguments` directly. Do not rewrite the result into internal fields such as `role_entries` or `editable_que_ids`.
 When you patch a preset, patch the preset node itself. Do not leave the preset approval node unassigned while adding a second custom approval node.
 
@@ -158,10 +114,13 @@ One or more transitions reference unknown nodes or create an invalid graph.
 The workflow referenced a field name that does not exist, often in:
 
 - `permissions.editable_fields`
-- branch `conditions`
 
 Call `app_read_fields` and retry with the exact field names returned by the app.
 
+### `FLOW_NODE_TYPE_UNSUPPORTED`
+
+The public workflow builder only supports linear flows. Remove `branch` and `condition` nodes and redesign the flow with stable sequential nodes instead of retrying the same graph.
+
 ### `STATUS_FIELD_REQUIRED`
 
 The app has no explicit status field recognized by the internal workflow compiler. Add one with `app_schema_apply`, then retry.

package/src/qingflow_mcp/__init__.py

@@ -2,4 +2,4 @@ from __future__ import annotations
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.0b40"
+__version__ = "0.2.0b42"

package/src/qingflow_mcp/backend_client.py

@@ -1,6 +1,9 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from threading import Event
+from typing import Any
+from urllib.parse import urlsplit, urlunsplit
 from uuid import uuid4
 
 import httpx
@@ -201,6 +204,182 @@ class BackendClient:
             "body": body,
         }
 
+    def download_binary(self, url: str, *, headers: dict[str, str] | None = None) -> bytes:
+        try:
+            response = self._client.get(url, headers=headers or None)
+        except httpx.RequestError as exc:
+            raise QingflowApiError(category="network", message=str(exc))
+        if response.status_code >= 400:
+            raise QingflowApiError(
+                category="http",
+                message=self._extract_message(response.text) or f"HTTP {response.status_code}",
+                http_status=response.status_code,
+            )
+        return response.content
+
+    def request_multipart(
+        self,
+        method: str,
+        context: BackendRequestContext,
+        path: str,
+        *,
+        data: dict[str, Any] | None = None,
+        files: dict[str, tuple[str, bytes, str | None]] | None = None,
+        unwrap: bool = True,
+    ) -> JSONValue:
+        return self.request_multipart_with_meta(
+            method,
+            context,
+            path,
+            data=data,
+            files=files,
+            unwrap=unwrap,
+        ).data
+
+    def request_multipart_with_meta(
+        self,
+        method: str,
+        context: BackendRequestContext,
+        path: str,
+        *,
+        data: dict[str, Any] | None = None,
+        files: dict[str, tuple[str, bytes, str | None]] | None = None,
+        unwrap: bool = True,
+    ) -> BackendResponse:
+        headers = self._base_headers(
+            context.token,
+            context.ws_id,
+            context.qf_request_id,
+            qf_version=context.qf_version,
+        )
+        request_files: dict[str, tuple[str, bytes, str | None]] | None = None
+        if files:
+            request_files = {key: value for key, value in files.items()}
+        try:
+            response = self._client.request(
+                method.upper(),
+                self._build_url(context.base_url, path),
+                data=data,
+                files=request_files,
+                headers=headers,
+            )
+        except httpx.RequestError as exc:
+            raise QingflowApiError(category="network", message=str(exc), request_id=headers["Qf-Request-Id"])
+        parsed = self._parse_response(response, headers["Qf-Request-Id"], unwrap=unwrap)
+        return BackendResponse(
+            data=parsed,
+            headers=dict(response.headers),
+            request_id=headers["Qf-Request-Id"],
+            http_status=response.status_code,
+            qf_response_version=self._extract_response_qf_version(response.headers),
+        )
+
+    def start_socket_data_import(
+        self,
+        context: BackendRequestContext,
+        *,
+        app_key: str,
+        being_enter_auditing: bool,
+        view_key: str | None,
+        excel_url: str,
+        excel_name: str,
+        ack_timeout_seconds: float = 8.0,
+        initial_wait_seconds: float = 4.0,
+    ) -> dict[str, Any]:
+        try:
+            import socketio  # type: ignore[import-not-found]
+        except ImportError as exc:
+            raise QingflowApiError(
+                category="config",
+                message=f"socket.io client dependency is missing: {exc}",
+            )
+
+        socket_base_url = self._build_socket_base_url(context.base_url)
+        import_result: dict[str, Any] = {
+            "import_id": None,
+            "process_id_str": None,
+            "status": "accepted",
+            "warnings": [],
+            "initial_event": None,
+            "failure_event": None,
+        }
+        initial_event_received = Event()
+        failure_event_received = Event()
+        sio = socketio.Client(reconnection=False, logger=False, engineio_logger=False)
+
+        def _handle_initial(payload: Any) -> None:
+            if isinstance(payload, dict):
+                import_result["initial_event"] = payload
+                process_id = payload.get("processIdStr") or payload.get("process_id_str") or payload.get("processId")
+                if process_id is not None:
+                    import_result["process_id_str"] = str(process_id)
+            initial_event_received.set()
+
+        def _handle_failure(payload: Any) -> None:
+            if isinstance(payload, dict):
+                import_result["failure_event"] = payload
+                process_id = payload.get("processIdStr") or payload.get("process_id_str") or payload.get("processId")
+                if process_id is not None:
+                    import_result["process_id_str"] = str(process_id)
+            failure_event_received.set()
+
+        try:
+            sio.connect(
+                socket_base_url,
+                transports=["polling", "websocket"],
+                socketio_path="socket.io",
+                headers=self._base_headers(
+                    context.token,
+                    context.ws_id,
+                    qf_version=context.qf_version,
+                ),
+                wait_timeout=ack_timeout_seconds,
+            )
+            ack = sio.call(
+                "dataImport",
+                [
+                    context.token,
+                    app_key,
+                    bool(being_enter_auditing),
+                    view_key,
+                    False,
+                    excel_url,
+                    excel_name,
+                ],
+                timeout=ack_timeout_seconds,
+            )
+            import_id = ack[0] if isinstance(ack, list) and ack else ack
+            if not import_id:
+                raise QingflowApiError(category="backend", message="socket import ack did not return import_id")
+            import_result["import_id"] = str(import_id)
+            sio.on(f"dataImportRes_{import_result['import_id']}", _handle_initial)
+            sio.on(f"dataImportFail_{import_result['import_id']}", _handle_failure)
+            if not initial_event_received.wait(timeout=initial_wait_seconds) and not failure_event_received.wait(timeout=0.1):
+                import_result["warnings"].append(
+                    {
+                        "code": "IMPORT_SOCKET_INITIAL_EVENT_PENDING",
+                        "message": "Import ack received, but no initial progress payload arrived within the initial wait window.",
+                    }
+                )
+        except Exception as exc:
+            message = str(exc)
+            if "timeout" in message.lower():
+                raise QingflowApiError(
+                    category="network",
+                    message="socket import ack timed out",
+                    details={"error_code": "IMPORT_SOCKET_ACK_TIMEOUT"},
+                )
+            if isinstance(exc, QingflowApiError):
+                raise
+            raise QingflowApiError(category="network", message=message or "socket import failed")
+        finally:
+            try:
+                if sio.connected:
+                    sio.disconnect()
+            except Exception:
+                pass
+        return import_result
+
     def _request_with_meta(
         self,
         method: str,
@@ -334,3 +513,13 @@ class BackendClient:
         if not normalized:
             raise QingflowApiError.config_error("base_url is required")
         return f"{normalized}/{path.lstrip('/')}"
+
+    def _build_socket_base_url(self, base_url: str) -> str:
+        normalized = normalize_base_url(base_url)
+        if not normalized:
+            raise QingflowApiError.config_error("base_url is required")
+        parsed = urlsplit(normalized)
+        path = parsed.path.rstrip("/")
+        if path.endswith("/api"):
+            path = path[:-4]
+        return urlunsplit((parsed.scheme, parsed.netloc, path or "", "", ""))

package/src/qingflow_mcp/builder_facade/models.py

@@ -266,6 +266,8 @@ class FieldPatch(StrictModel):
     description: str | None = None
     options: list[str] = Field(default_factory=list)
     target_app_key: str | None = None
+    display_field: FieldSelector | None = None
+    visible_fields: list[FieldSelector] = Field(default_factory=list)
     subfields: list["FieldPatch"] = Field(default_factory=list)
 
     @model_validator(mode="after")
@@ -274,6 +276,8 @@ class FieldPatch(StrictModel):
             raise ValueError("relation field requires target_app_key")
         if self.type != PublicFieldType.relation and self.target_app_key:
             raise ValueError("target_app_key is only allowed for relation fields")
+        if self.type != PublicFieldType.relation and (self.display_field is not None or self.visible_fields):
+            raise ValueError("display_field and visible_fields are only allowed for relation fields")
         if self.type == PublicFieldType.subtable and not self.subfields:
             raise ValueError("subtable field requires subfields")
         if self.type != PublicFieldType.subtable and self.subfields:
@@ -293,12 +297,16 @@ class FieldMutation(StrictModel):
     description: str | None = None
     options: list[str] | None = None
     target_app_key: str | None = None
+    display_field: FieldSelector | None = None
+    visible_fields: list[FieldSelector] | None = None
     subfields: list[FieldPatch] | None = None
 
     @model_validator(mode="after")
     def validate_shape(self) -> "FieldMutation":
         if self.type == PublicFieldType.relation and not self.target_app_key:
             raise ValueError("relation field requires target_app_key")
+        if self.type is not None and self.type != PublicFieldType.relation and (self.display_field is not None or self.visible_fields):
+            raise ValueError("display_field and visible_fields are only allowed for relation fields")
         if self.type == PublicFieldType.subtable and not self.subfields:
             raise ValueError("subtable field requires subfields")
         return self