@josephyan/qingflow-cli 0.2.0-beta.1000

package/src/qingflow_mcp/server_app_builder.py

@@ -0,0 +1,543 @@
+from __future__ import annotations
+
+import json
+
+from mcp.server.fastmcp import FastMCP
+
+from .backend_client import BackendClient
+from .config import DEFAULT_PROFILE
+from .response_trim import BUILDER_SERVER_METHOD_MAP, trim_error_response, trim_public_response, wrap_trimmed_methods
+from .session_store import SessionStore
+from .tools.ai_builder_tools import AiBuilderTools
+from .tools.auth_tools import AuthTools
+from .tools.feedback_tools import FeedbackTools
+from .tools.file_tools import FileTools
+from .tools.workspace_tools import WorkspaceTools
+
+
+def _config_failure(message: str, *, fix_hint: str) -> dict:
+    return {
+        "status": "failed",
+        "error_code": "CONFIG_ERROR",
+        "recoverable": True,
+        "message": message,
+        "details": {"fix_hint": fix_hint},
+        "verification": {},
+    }
+
+
+def build_builder_server() -> FastMCP:
+    server = FastMCP(
+        "Qingflow App Builder MCP",
+        instructions=(
+            "Use this server for AI-native Qingflow builder workflows. "
+            "`feedback_submit` is always available as a cross-cutting helper when the current capability is unsupported, awkward, or still cannot satisfy the user's need after reasonable use; it does not require Qingflow login or workspace selection, and it should be called only after explicit user confirmation. "
+            "Follow the resource path resolve -> summary read -> apply -> publish_verify. "
+            "Use builder_tool_contract when you need a machine-readable contract, aliases, allowed enums, or a minimal valid example for a public builder tool. "
+            "Use solution_install when the user explicitly wants to install a packaged solution/template by solution_key, optionally copying bundled demo data. "
+            "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 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. "
+            "If builder writes are blocked by the current user's own edit lock, use app_release_edit_lock_if_mine with the lock owner details from the failed result. "
+            "Do not handcraft internal solution payloads or rely on build_id/stage/repair. "
+            "If the current MCP capability is unsupported, the workflow is awkward, or the user's need still cannot be satisfied after reasonable use, first summarize the gap, ask whether to submit feedback, and call feedback_submit only after explicit user confirmation."
+        ),
+    )
+    sessions = SessionStore()
+    backend = BackendClient()
+    auth = wrap_trimmed_methods(AuthTools(sessions, backend), BUILDER_SERVER_METHOD_MAP)
+    workspace = wrap_trimmed_methods(WorkspaceTools(sessions, backend), BUILDER_SERVER_METHOD_MAP)
+    files = wrap_trimmed_methods(FileTools(sessions, backend), BUILDER_SERVER_METHOD_MAP)
+    ai_builder = wrap_trimmed_methods(AiBuilderTools(sessions, backend), BUILDER_SERVER_METHOD_MAP)
+    feedback = FeedbackTools(backend, mcp_side="App Builder MCP")
+
+    @server.tool()
+    def auth_use_credential(
+        profile: str = DEFAULT_PROFILE,
+        base_url: str | None = None,
+        qf_version: str | None = None,
+        credential: str = "",
+        persist: bool = False,
+    ) -> dict:
+        return auth.auth_use_credential(
+            profile=profile,
+            base_url=base_url,
+            qf_version=qf_version,
+            credential=credential,
+            persist=persist,
+        )
+
+    @server.tool()
+    def auth_whoami(profile: str = DEFAULT_PROFILE) -> dict:
+        return auth.auth_whoami(profile=profile)
+
+    @server.tool()
+    def auth_logout(profile: str = DEFAULT_PROFILE, forget_persisted: bool = False) -> dict:
+        return auth.auth_logout(profile=profile, forget_persisted=forget_persisted)
+
+    @server.tool()
+    def workspace_list(
+        profile: str = DEFAULT_PROFILE,
+        page_num: int = 1,
+        page_size: int = 20,
+        include_external: bool = False,
+    ) -> dict:
+        return workspace.workspace_list(
+            profile=profile,
+            page_num=page_num,
+            page_size=page_size,
+            include_external=include_external,
+        )
+
+    @server.tool()
+    def workspace_get(
+        profile: str = DEFAULT_PROFILE,
+        ws_id: int | None = None,
+    ) -> dict:
+        return workspace.workspace_get(
+            profile=profile,
+            ws_id=ws_id,
+        )
+
+    @server.tool()
+    def file_upload_local(
+        profile: str = DEFAULT_PROFILE,
+        upload_kind: str = "attachment",
+        file_path: str = "",
+        upload_mark: str | None = None,
+        content_type: str | None = None,
+        bucket_type: str | None = None,
+        path_id: int | None = None,
+        file_related_url: str | None = None,
+    ) -> dict:
+        return files.file_upload_local(
+            profile=profile,
+            upload_kind=upload_kind,
+            file_path=file_path,
+            upload_mark=upload_mark,
+            content_type=content_type,
+            bucket_type=bucket_type,
+            path_id=path_id,
+            file_related_url=file_related_url,
+        )
+
+    @server.tool()
+    def feedback_submit(
+        category: str = "",
+        title: str = "",
+        description: str = "",
+        expected_behavior: str | None = None,
+        actual_behavior: str | None = None,
+        impact_scope: str | None = None,
+        tool_name: str | None = None,
+        app_key: str | None = None,
+        record_id: str | int | None = None,
+        workflow_node_id: str | int | None = None,
+        note: str | None = None,
+    ) -> dict:
+        try:
+            return trim_public_response(
+                "builder:feedback_submit",
+                feedback.feedback_submit(
+                    category=category,
+                    title=title,
+                    description=description,
+                    expected_behavior=expected_behavior,
+                    actual_behavior=actual_behavior,
+                    impact_scope=impact_scope,
+                    tool_name=tool_name,
+                    app_key=app_key,
+                    record_id=record_id,
+                    workflow_node_id=workflow_node_id,
+                    note=note,
+                ),
+            )
+        except RuntimeError as exc:
+            try:
+                payload = json.loads(str(exc))
+            except json.JSONDecodeError:
+                raise
+            if isinstance(payload, dict):
+                raise RuntimeError(json.dumps(trim_error_response(payload), ensure_ascii=False)) from None
+            raise
+
+    @server.tool()
+    def builder_tool_contract(tool_name: str = "") -> dict:
+        return ai_builder.builder_tool_contract(tool_name=tool_name)
+
+    @server.tool()
+    def package_get(profile: str = DEFAULT_PROFILE, package_id: int = 0) -> dict:
+        return ai_builder.package_get(profile=profile, package_id=package_id)
+
+    @server.tool()
+    def package_apply(
+        profile: str = DEFAULT_PROFILE,
+        package_id: int | None = None,
+        package_name: str | None = None,
+        create_if_missing: bool = False,
+        icon: str | None = None,
+        color: str | None = None,
+        visibility: dict | None = None,
+        items: list[dict] | None = None,
+        allow_detach: bool = False,
+    ) -> dict:
+        return ai_builder.package_apply(
+            profile=profile,
+            package_id=package_id,
+            package_name=package_name,
+            create_if_missing=create_if_missing,
+            icon=icon,
+            color=color,
+            visibility=visibility,
+            items=items,
+            allow_detach=allow_detach,
+        )
+
+    @server.tool()
+    def solution_install(
+        profile: str = DEFAULT_PROFILE,
+        solution_key: str = "",
+        being_copy_data: bool = True,
+        solution_source: str = "solutionDetail",
+    ) -> dict:
+        return ai_builder.solution_install(
+            profile=profile,
+            solution_key=solution_key,
+            being_copy_data=being_copy_data,
+            solution_source=solution_source,
+        )
+
+    @server.tool()
+    def member_search(
+        profile: str = DEFAULT_PROFILE,
+        query: str = "",
+        page_num: int = 1,
+        page_size: int = 20,
+        contain_disable: bool = False,
+    ) -> dict:
+        return ai_builder.member_search(
+            profile=profile,
+            query=query,
+            page_num=page_num,
+            page_size=page_size,
+            contain_disable=contain_disable,
+        )
+
+    @server.tool()
+    def role_search(
+        profile: str = DEFAULT_PROFILE,
+        keyword: str = "",
+        page_num: int = 1,
+        page_size: int = 20,
+    ) -> dict:
+        return ai_builder.role_search(profile=profile, keyword=keyword, page_num=page_num, page_size=page_size)
+
+    @server.tool()
+    def role_create(
+        profile: str = DEFAULT_PROFILE,
+        role_name: str = "",
+        member_uids: list[int] | None = None,
+        member_emails: list[str] | None = None,
+        member_names: list[str] | None = None,
+        role_icon: str = "ex-user-outlined",
+    ) -> dict:
+        return ai_builder.role_create(
+            profile=profile,
+            role_name=role_name,
+            member_uids=member_uids or [],
+            member_emails=member_emails or [],
+            member_names=member_names or [],
+            role_icon=role_icon,
+        )
+
+    @server.tool()
+    def app_release_edit_lock_if_mine(
+        profile: str = DEFAULT_PROFILE,
+        app_key: str = "",
+        lock_owner_email: str = "",
+        lock_owner_name: str = "",
+    ) -> dict:
+        return ai_builder.app_release_edit_lock_if_mine(
+            profile=profile,
+            app_key=app_key,
+            lock_owner_email=lock_owner_email,
+            lock_owner_name=lock_owner_name,
+        )
+
+    @server.tool()
+    def app_resolve(
+        profile: str = DEFAULT_PROFILE,
+        app_key: str = "",
+        app_name: str = "",
+        package_id: int | None = None,
+    ) -> dict:
+        has_app_key = bool((app_key or "").strip())
+        has_app_name = bool((app_name or "").strip())
+        has_package_id = package_id is not None
+        if has_app_key and (has_app_name or has_package_id):
+            return _config_failure(
+                "app_resolve accepts exactly one selector mode.",
+                fix_hint="Use only `app_key`, or use `app_name` together with `package_id`.",
+            )
+        if not has_app_key and not (has_app_name and has_package_id):
+            return _config_failure(
+                "app_resolve requires either app_key, or app_name together with package_id.",
+                fix_hint="For an existing known app, pass `app_key`. For package-scoped lookup, pass both `app_name` and `package_id`.",
+            )
+        return ai_builder.app_resolve(profile=profile, app_key=app_key, app_name=app_name, package_id=package_id)
+
+    @server.tool()
+    def app_custom_button_list(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:
+        return ai_builder.app_custom_button_list(profile=profile, app_key=app_key)
+
+    @server.tool()
+    def app_custom_button_get(profile: str = DEFAULT_PROFILE, app_key: str = "", button_id: int = 0) -> dict:
+        return ai_builder.app_custom_button_get(profile=profile, app_key=app_key, button_id=button_id)
+
+    @server.tool()
+    def app_custom_button_create(profile: str = DEFAULT_PROFILE, app_key: str = "", payload: dict | None = None) -> dict:
+        return ai_builder.app_custom_button_create(profile=profile, app_key=app_key, payload=payload or {})
+
+    @server.tool()
+    def app_custom_button_update(
+        profile: str = DEFAULT_PROFILE,
+        app_key: str = "",
+        button_id: int = 0,
+        payload: dict | None = None,
+    ) -> dict:
+        return ai_builder.app_custom_button_update(profile=profile, app_key=app_key, button_id=button_id, payload=payload or {})
+
+    @server.tool()
+    def app_custom_button_delete(profile: str = DEFAULT_PROFILE, app_key: str = "", button_id: int = 0) -> dict:
+        return ai_builder.app_custom_button_delete(profile=profile, app_key=app_key, button_id=button_id)
+
+    @server.tool()
+    def app_get(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:
+        return ai_builder.app_get(profile=profile, app_key=app_key)
+
+    @server.tool()
+    def app_get_fields(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:
+        return ai_builder.app_get_fields(profile=profile, app_key=app_key)
+
+    @server.tool()
+    def app_repair_code_blocks(
+        profile: str = DEFAULT_PROFILE,
+        app_key: str = "",
+        field: str | None = None,
+        apply: bool = False,
+    ) -> dict:
+        return ai_builder.app_repair_code_blocks(profile=profile, app_key=app_key, field=field, apply=apply)
+
+    @server.tool()
+    def app_get_layout(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:
+        return ai_builder.app_get_layout(profile=profile, app_key=app_key)
+
+    @server.tool()
+    def app_get_views(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:
+        return ai_builder.app_get_views(profile=profile, app_key=app_key)
+
+    @server.tool()
+    def app_get_flow(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:
+        return ai_builder.app_get_flow(profile=profile, app_key=app_key)
+
+    @server.tool()
+    def app_get_charts(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:
+        return ai_builder.app_get_charts(profile=profile, app_key=app_key)
+
+    @server.tool()
+    def portal_list(profile: str = DEFAULT_PROFILE) -> dict:
+        return ai_builder.portal_list(profile=profile)
+
+    @server.tool()
+    def portal_get(
+        profile: str = DEFAULT_PROFILE,
+        dash_key: str = "",
+        being_draft: bool = True,
+    ) -> dict:
+        return ai_builder.portal_get(profile=profile, dash_key=dash_key, being_draft=being_draft)
+
+    @server.tool()
+    def view_get(profile: str = DEFAULT_PROFILE, view_key: str = "") -> dict:
+        return ai_builder.view_get(profile=profile, view_key=view_key)
+
+    @server.tool()
+    def chart_get(profile: str = DEFAULT_PROFILE, chart_id: str = "") -> dict:
+        return ai_builder.chart_get(profile=profile, chart_id=chart_id)
+
+    @server.tool()
+    def app_schema_apply(
+        profile: str = DEFAULT_PROFILE,
+        app_key: str = "",
+        package_id: int | None = None,
+        app_name: str = "",
+        app_title: str = "",
+        icon: str = "",
+        color: str = "",
+        visibility: dict | None = None,
+        create_if_missing: bool = False,
+        publish: bool = True,
+        add_fields: list[dict] | None = None,
+        update_fields: list[dict] | None = None,
+        remove_fields: list[dict] | None = None,
+    ) -> dict:
+        has_app_key = bool((app_key or "").strip())
+        has_app_name = bool((app_name or "").strip())
+        has_app_title = bool((app_title or "").strip())
+        has_package_id = package_id is not None
+        if has_app_key:
+            if create_if_missing or has_package_id:
+                return _config_failure(
+                    "app_schema_apply edit mode accepts app_key and optional app_name rename only.",
+                    fix_hint="For existing apps, use `app_key` and optionally `app_name`. For create mode, use `package_id + app_name + create_if_missing=true`.",
+                )
+        elif not (create_if_missing and has_package_id and (has_app_name or has_app_title)):
+            return _config_failure(
+                "app_schema_apply create mode requires package_id, app_name, and create_if_missing=true.",
+                fix_hint="Use `app_key` for existing apps, or pass `package_id + app_name + create_if_missing=true` to create a new app.",
+            )
+        return ai_builder.app_schema_apply(
+            profile=profile,
+            app_key=app_key,
+            package_id=package_id,
+            app_name=app_name,
+            app_title=app_title,
+            icon=icon,
+            color=color,
+            visibility=visibility,
+            create_if_missing=create_if_missing,
+            publish=publish,
+            add_fields=add_fields or [],
+            update_fields=update_fields or [],
+            remove_fields=remove_fields or [],
+        )
+
+    @server.tool()
+    def app_layout_apply(
+        profile: str = DEFAULT_PROFILE,
+        app_key: str = "",
+        mode: str = "merge",
+        publish: bool = True,
+        sections: list[dict] | None = None,
+    ) -> dict:
+        return ai_builder.app_layout_apply(profile=profile, app_key=app_key, mode=mode, publish=publish, sections=sections or [])
+
+    @server.tool()
+    def app_flow_apply(
+        profile: str = DEFAULT_PROFILE,
+        app_key: str = "",
+        mode: str = "replace",
+        publish: bool = True,
+        nodes: list[dict] | None = None,
+        transitions: list[dict] | None = None,
+    ) -> dict:
+        return ai_builder.app_flow_apply(
+            profile=profile,
+            app_key=app_key,
+            mode=mode,
+            publish=publish,
+            nodes=nodes or [],
+            transitions=transitions or [],
+        )
+
+    @server.tool()
+    def app_views_apply(
+        profile: str = DEFAULT_PROFILE,
+        app_key: str = "",
+        publish: bool = True,
+        upsert_views: list[dict] | None = None,
+        remove_views: list[str] | None = None,
+    ) -> dict:
+        return ai_builder.app_views_apply(
+            profile=profile,
+            app_key=app_key,
+            publish=publish,
+            upsert_views=upsert_views or [],
+            remove_views=remove_views or [],
+        )
+
+    @server.tool()
+    def app_charts_apply(
+        profile: str = DEFAULT_PROFILE,
+        app_key: str = "",
+        upsert_charts: list[dict] | None = None,
+        remove_chart_ids: list[str] | None = None,
+        reorder_chart_ids: list[str] | None = None,
+    ) -> dict:
+        return ai_builder.app_charts_apply(
+            profile=profile,
+            app_key=app_key,
+            upsert_charts=upsert_charts or [],
+            remove_chart_ids=remove_chart_ids or [],
+            reorder_chart_ids=reorder_chart_ids or [],
+        )
+
+    @server.tool()
+    def portal_apply(
+        profile: str = DEFAULT_PROFILE,
+        dash_key: str = "",
+        dash_name: str = "",
+        package_id: int | None = None,
+        publish: bool = True,
+        sections: list[dict] | None = None,
+        visibility: dict | None = None,
+        auth: dict | None = None,
+        icon: str | None = None,
+        color: str | None = None,
+        hide_copyright: bool | None = None,
+        dash_global_config: dict | None = None,
+        config: dict | None = None,
+    ) -> dict:
+        has_dash_key = bool((dash_key or "").strip())
+        has_dash_name = bool((dash_name or "").strip())
+        has_package_id = package_id is not None
+        if has_dash_key and has_package_id:
+            return _config_failure(
+                "portal_apply accepts exactly one selector mode.",
+                fix_hint="Use `dash_key` to update an existing portal, or use `package_id + dash_name` to create a new portal.",
+            )
+        if not has_dash_key and not (has_package_id and has_dash_name):
+            return _config_failure(
+                "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`.",
+            )
+        return ai_builder.portal_apply(
+            profile=profile,
+            dash_key=dash_key,
+            dash_name=dash_name,
+            package_id=package_id,
+            publish=publish,
+            sections=sections or [],
+            visibility=visibility,
+            auth=auth,
+            icon=icon,
+            color=color,
+            hide_copyright=hide_copyright,
+            dash_global_config=dash_global_config,
+            config=config or {},
+        )
+
+    @server.tool()
+    def app_publish_verify(
+        profile: str = DEFAULT_PROFILE,
+        app_key: str = "",
+        expected_package_id: int | None = None,
+    ) -> dict:
+        return ai_builder.app_publish_verify(
+            profile=profile,
+            app_key=app_key,
+            expected_package_id=expected_package_id,
+        )
+
+    return server
+
+
+def main() -> None:
+    build_builder_server().run()
+
+
+if __name__ == "__main__":
+    main()